This guide is designed for Linux Ubuntu 16.04+ (18.04 tested). Other distributions should be supported with slightly little modifications.
This page describes how to run a production-ready instance of Cytomine in a few steps, either on personal computers (such as laptops, desktops) or on larger servers. Once Cytomine's server is installed, your Cytomine instance can be accessed through a modern web browser or via clients using the RESTful API.
Step 1 - Install requirements
Cytomine runs in Docker containers, so that the only requirement is to install Docker.
Check official Docker documentation to install Docker for Ubuntu. In particular, choose Install using the repository, set up the repository and install Docker CE.
You can optionally improve your Docker installation with the post installation steps for Linux.
Step 2 - Retrieve Cytomine bootstrap
Latest Cytomine ULiege release is available at: https://github.com/Cytomine-ULiege/Cytomine-bootstrap/releases/latest
Latest Cytomine ULiege release can be downloaded here: https://github.com/Cytomine-ULiege/Cytomine-bootstrap/releases/latest/download/Cytomine-bootstrap.zip
Download the archive and extract it.
To install Cytomine ULiege latest developments, continuous builds or pre-releases, you can clone the Git repository:
Step 3 - Configure your instance
configuration.sh file in your favorite text editor such as
Have a look at Cytomine configuration reference to configure your instance.
Be sure to use URLs that are not already used by other applications (avoid
localhost) to prevent conflicts.
Add the XXX_URL variable values into the /etc/hosts of your host machine.
In the /etc/hosts, add the following lines and don't forget to adapt them with values you chose for XXX_URL variables.
Configure data paths
All paths referenced in variables
XXX_PATH must exist and be mappable in the Docker engine. To create the data in your
$HOME, set paths with
Don't forget to create all these directories (
mkdir) if they don't exist.
Step 4 - Initialize your deployment
Generate your installation script with the command
Step 5 - Deploy your instance
Run the generated deployment script with the command
Deployment can take some time, especially if it's the first time you install Cytomine on your host machine. All Docker container images have to be downloaded.
Step 6 - Check your running instance
When start up is finished, check the application is running in your browser on the URL specified in your CORE_URL variable (by default: localhost-core).
An admin account is created by default. To connect,
- Username: admin
Password: retrieve it in
Cytomine-bootstrap/configs/core/cytomineconfig.groovy. Search the line with
grails.adminPassword. For example, in
'5366E276-7574-4155-84C1-E1EA5ECB1039', the password is 5366E276-7574-4155-84C1-E1EA5ECB1039
CORE_URL = localhost-core), click on you name at the top right in the web interface, and go to Account to change the admin password.