How to install Cytomine

On this page, you will learn how to install a Cytomine instance on a Linux machine with Docker.
We will also see how to install a local instance on a personal computer.

Once Cytomine's server is installed, one can access Cytomine through a modern web browser or through clients using RESTful API.

This installation documentation has been tested on Ubuntu 16.04LTS, 18.04LTS, Debian 9 and 10 but can be used for other platforms supported by Docker.  

Please note we use Docker which is a kind of lightweight virtualization platform, so you do not need to create virtual machines to install Cytomine (it's better not do so for better performances).

If you experiment any issue, please describe your problem precisely in our ticket system on Github.



CPU8 cores16 coresCytomine is a set of multithread servers/tools. If you want to support more users, you need to have more cores.
Disk100GB1TBNote that you will need 20GB for the Cytomine installation and the 100GB does not include backup space!


  • Your operating system must be supported by Docker as almost all Linux distribution.
  • Docker must be installed, see here
  • In the following steps, we will use the command line. It is recommanded to know how to use it

Step 1 - Retrieve Cytomine-bootstrap

First of all, we retrieve the Cytomine-bootstrap installation procedure.

Install latest official release from Cytomine cooperative

If you want to install the last official release, copy/paste these commands:

mkdir Cytomine_bootstrap/
cd Cytomine_bootstrap/
wget https://github.com/cytomine/Cytomine-bootstrap/archive/v3.0.0.zip -O bootstrap.zip
unzip bootstrap.zip
mv Cytomine-bootstrap-3.0.0/* .
rm -rf bootstrap.zip Cytomine-bootstrap-3.0.0/

Remark :
To install another version, replace the 3.0.0 into the above procedure by the desired version numbers.

The previous major stable version of Cytomine was the version 2.1.1 and you will find all version on this link

Step 2 - Configure Cytomine installation

Now, it is required to edit the Cytomine file configuration.sh in the Cytomine-bootstrap/ directory to prepare the installation of Cytomine Docker containers, using e.g.:

nano configuration.sh

We have two possibilities :

 a) If you want to deploy on localhost :

First of all, the variables "XXX_URL" will not be visible outside of your local server. So, due to the Docker architecture (isolation of the Docker's containers), we need to apply some changes to authorize network communication between our IMS and CORE containers (see below for further details). To do so, add these URL values (CORE_URL, IMS_URLS, UPLOAD_URL, RETRIEVAL_URL) to your /etc/hosts file with the following format : " XXX_URL".

With the default URL your /etc/hosts will contain the following lines   localhost-core   localhost-ims   localhost-ims2   localhost-upload   rabbitmq

NB : Please be careful that some problems might appear if you use localhost instead of CORE_URL for a connection to Cytomine. So, keep using CORE_URL.
For an instance test, you can let the file configuration.sh unchanged.

Remark :
For the version 1 of Cytomine, you must add the localhost-retrieval

line too.

b) If you want to make your Cytomine instance accessible from other computers :

Contact your institutional system/network administrator before installing Cytomine so that they create DNS entries and make their HTTP port (80) accessible for CORE_URL, IMS_URLS and UPLOAD_URL.

Detailed explanation of configuration options

This page will explain the variables used to configure your installation.

Then run the init script

bash init.sh

Step 3 - Deploy Cytomine

Then, you can deploy Cytomine by launching the following command in the Bootstrap directory (the installation of Cytomine can take up to 1 hour depending on network and server speed):

sudo sh restart.sh

Step 4 - First connection

You can now discover Cytomine by browsing the selected url for the core and connecting as the admin user.
To know the randomly auto-generated admin password, run the following command

cat configs/core/cytomineconfig.groovy | grep adminPassword

We recommand you to change it at your first connexion.

Follow the User Guide to learn how to use the Cytomine platform.