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.
Requirements
Hardware
| Minimum | Recommended | ||
| CPU | 8 cores | 16 cores | Cytomine is a set of multithread servers/tools. If you want to support more users, you need to have more cores. |
| Memory | 8GB | 16GB | |
| Disk | 100GB | 1TB | Note that you will need 20GB for the Cytomine installation and the 100GB does not include backup space! |
System
- 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 : "127.0.0.1 XXX_URL".
With the default URL your /etc/hosts will contain the following lines
127.0.0.1 localhost-core 127.0.0.1 localhost-ims 127.0.0.1 localhost-ims2 127.0.0.1 localhost-upload 127.0.0.1 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
127.0.0.1 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.