Ontopic Docs

# Install Docker and Git

It is necessary to have git and Docker with docker-compose installed to be able to run Ontopic Studio.

Minimum and recommended versions

The minimum version of docker-compose supported is 1.29.0, we recommend using a version 2.24.7+ (integrated in Docker Desktop 4.29.0+) to avoid encountering networking issues.

# Preparing Linux for the installation of Ontopic Studio

On recent Linux distributions (e.g. Ubuntu 22.04), git and Docker, as provided by your distribution should be perfectly adapted for installing and running Ontopic Studio. On Ubuntu install them with

sudo apt install git-all docker docker-compose-plugin

For older distributions, installing Docker as described on the official Docker documentation (opens new window) is recommended.

Unless your distro is not very old, git, as provided by your distro, should work.

# Preparing MacOS for the installation of Ontopic Studio

Follow the recommended installation for git (opens new window).

You can install homebrew with the command

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

later run:

brew install git

Install Docker interactively as described on the official Docker documentation (opens new window)

# Preparing Windows for the installation of Ontopic Studio

Preparing the installation of Ontopic Studio in a Windows environment is a little bit more elaborate than on Linux.

Docker is a technology that was initially developed for the Linux operating system and still needs a Linux system to run correctly. WSL2 (Windows Subsystem for Linux) is a technology developed by Microsoft that allows running Linux, on Windows and is the preferred option for installing Docker on Windows. WSL2 has the additional advantage to include several other small programs needed for the installation of Ontopic Studio.

# Installing WSL2

Download and install WSL on your machine: you should follow the official documentation (opens new window). We suggest creating the default Ubuntu machine. The necessary steps are:

  • open a PowerShell. You can open a PowerShell by hitting the Windows key and typing powershell. A window containing some text, such as "Windows PowerShell" should pop up. Click on that window and type:
wsl --install

This will install, as a default the Linux distribution "Ubuntu" on your PC. You will be asked for a username and a password for your Linux distribution. You can choose any name and password, but it is important to remember them. To avoid confusion, you might choose to use the same username and password as for Windows username. You will need the password each time you have to use the command sudo, which stands for SuperUser DO, a Linux command allowing you to perform commands with higher privileges.

  • Once Ubuntu is installed, you have multiple options to start it, either by opening a PowerShell and entering ubuntu on the command-line prompt or by clicking on the orange Ubuntu tile in the Start Menu.

  • update the packages with the command

sudo apt update && sudo apt upgrade

# Installing Docker

As mentioned above, Ontopic Studio is delivered as Docker image files and you need a working Docker installation. Download and install Docker for Windows interactively, as described in the official documentation (opens new window), choosing the WSL 2 backend option. Don't get confused, as by now WSL and WSL 2 refer to the same software. You can refer as well to the wsl official documentation (opens new window) for more guidance.

# Installing Git

The initial files for installing Ontopic Studio are fetched by a small software called Git. The simplest way to install Git from within the Ubuntu environment:

  • Start WSL, launching a WSL Ubuntu virtual machine, either by entering ubuntu on the command-line prompt (as above either cmd.exe or PowerShell), or by clicking on the Ubuntu tile in the Start Menu.
  • Install git inside WSL2 with the following command.
sudo apt-get install git

You can have more information on git in WSL from the official documentation (opens new window).

  • From now on, you can use the same installation procedure as on Linux and MacOS. It is important to remember to fetch the initial installation files (in git jargon called "Clone the repository") inside your WSL Linux distribution, as it is also true for the rest of the instructions present in the step Installing Ontopic Studio.

Some notes about WSL2:

You can access and visualize your WSL2 files in Windows explorer by accessing the folders starting with \\wsl$.

You can access data in Windows file system from WSL2 from /mnt/c directory.

For example, copying the license could be done with the command:

cp /mnt/c/Users/.../user-license ~/.../studio/default-secrets/license

# Username

If you are in doubt about the username you are currently using, open a command prompt by hitting the Windows key and writing in the dialog window, that popped up cmd. A window with some text will pop up. Click into that window and type echo %username%. The system will return the username you are currently using.