# 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
ubuntuon 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
ubuntuon 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:
- Using the default configuration
- 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
# Running the init script (recommended for production)
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