# Docker-compose installation

Ontopic Studio can be deployed on a multitude of different systems. This flexibility is obtained thanks to the usage of a technology called Docker. Docker allows packaging an application and everything it depends on, such as libraries and files, into a single file, called Docker image. This file is independent of the environment it will be deployed on, be it Windows, MacOS, or Linux. A Docker image can be deployed on a simple PC, on servers, or in the cloud. In the case of Ontopic Studio, which consists of multiple applications, a small number of such images is needed.

Prerequisites

Please contact us for obtaining the License key for installation. Contact Us (opens new window)

# Requirements

It is necessary to have Docker and git 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

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.

# Get the files

Change to the directory where to place the Ontopic Studio installation. In Windows, you have to do this in WSL2/Ubuntu.

Get the configuration files with git using the credentials you received by email, substituting the values <username> and <deploy-token>

git clone https://<username>:<deploy_token>@gitlab.com/ontopic/studio.git
cd studio/

By default you are getting the latest version (available in the main branch). If you want to run a specific version (opens new window), execute this extra command:

git checkout <version_number>

# Copy the license file

Copy the license you received by mail into the folder default-secrets/license, and make sure it is named user-license

# Login to the container registry

Read the container registry images, by signing in to the Gitlab Container Registry, substituting <username> and <deploy-token> with the given credentials:

docker login -u <username> -p <deploy-token> registry.gitlab.com

# Configure your installation

We offer you two options for configuring your installation:

  1. Using the default configuration
  2. Running an initialization script

# Using the default configuration

Before using Ontopic Studio, it is necessary to configure its secrets and environment variables. Copy the .env.template file to .env file.

cp .env.template .env

A bash script by the name of init-configuration-local.sh has been included in the repository to help with the configuration.

It will guide the user into entering the needed configuration variables for a default installation of Ontopic Studio, while also running all necessary one-time setup jobs.

When it is requested, you should provide the information for the local authentication, inserting: username, email, fullname, user group and password. You can also proceed accepting the suggested values and providing only a password for the user test. Be sure to remember the user and password or keep them in a safe place.

It will create a local directory volumes, to store the Ontopic Studio data (while the default configuration only uses Docker volumes).

If you have already used Ontopic Studio: export your projects before running the script

Since new volumes are created, your data will not be automatically moved from the docker volumes to the local directory volumes. You can export your Ontopic Studio Projects for backup clicking on the button export project on the Dashboard. After running the script and restarted Ontopic Studio you can reimport your project, creating a new project with the data source connection and clicking on the button import project on the Dashboard.

./init-configuration-local.sh

# Set up the materialization

See the dedicated page

# What's next

Start Ontopic Studio