# Install

# Requirements

# Hardware

Cytomine is a set of multi-threaded tools. A minimum of 8 CPU cores is required. The number of required cores is proportional to the expected activity. The more you want to support active users, the more you need cores. For a server-setup configuration, we recommend to use at least 16 cores.

Regarding memory, a minimum of 8 GB is required, but we recommend at least 16 GB.

Cytomine installation requires about 15GB. You need to provide enough space to store your images (depends on their size). If database backup is enabled, extra-space has to be provided.

# Software

Cytomine can be installed on any operating system supporting recent versions of Docker and bash. Most of Linux distributions (including Ubuntu, CentOS) and Mac OS X Yosemite and above.

Docker must be installed. See Official Docker installation (opens new window).

On Mac OS, check official Docker documentation to install Docker for Mac (opens new window). By default, Docker for Mac drastically limits resources available to Docker. Once Docker for Mac is running, go to Preferences for the menu bar and configure the runtime options to use at least 75% of the available resources on your Mac.

# Install

TIP

If you experiment any issue, please describe your problem precisely in our ticket system on Github. (opens new window)

# 1. Retrieve Cytomine-bootstrap

Cytomine-bootstrap gathers all commands and scripts to manage your Cytomine instance.

To install the last Cytomine ULiège R&D version, run:

wget https://github.com/cytomine-uliege/Cytomine-bootstrap/archive/2021.1.zip -O bootstrap.zip
unzip bootstrap.zip
cd Cytomine-bootstrap-2021.1

1
2
3

# 2. Configure Cytomine installation

Open the file configuration.sh in a text editor.

# Configure URLs

In order to open Cytomine in your browser, URLs pointing to Cytomine components have to be configured.

CORE_URL is the URL of the main Cytomine server.
IMS_URL is the URL for the image server.
UPLOAD_URL is the URL used to upload new images.

CORE_URL, IMS_URL and UPLOAD_URL have to be different (even if they are pointing to the same host). As an example, cytomine.domain.my and cytomine.domain.my/ims will not work as ims is subURL of the main ones. cytomine.domain.my, cytomine-ims.domain.my, ... is a valid example.

Decide about the accessibility of your installation:

To share your installation and make your Cytomine instance accessible from anywhere, create DNS entries and make their HTTP(S) ports (80/443) accessible for these URLs. This operation can often be realised by your network administrator or your IT department.
To install locally (on a laptop for example), open the file /etc/hosts in a text editor. Append these lines:
```
127.0.0.1 $CORE_URL
127.0.0.1 $IMS_URL
127.0.0.1 $UPLOAD_URL
127.0.0.1 rabbitmq
```
1
2
3
4
where $CORE_URL, $IMS_URL and $UPLOAD_URL have been substituted by the values you chose.

On Mac OS, run sudo killall -HUP mDNSResponder after /etc/hosts update.

# Configure disk paths

All paths referenced in ..._PATH configuration keys must exist and be mappable in the Docker engine.

# Other configuration

You can learn about the other variables on this dedicated page.

# 3. Start Cytomine

Initialize your Cytomine instance with the configuration you chose at previous step. Run

bash init.sh

Then, start your Cytomine instance using

sudo bash start.sh

The first time, a lot of components have to be downloaded. Depending on network and server speed, this step can take several minutes.

# 4. First connection

You can now discover Cytomine by browsing the URL you chose for CORE_URL. By default, a admin account has been created for you. To connect to the platform in your browser, retrieve the randomly generated admin password with

cat configs/core/cytomineconfig.groovy | grep adminPassword

Once connected, update the admin password.

# Update configuration

If you want to change the configuration of a running instance, update the configuration.sh file and run

bash init.sh
sudo bash restart.sh

1
2

# Stop Cytomine

To stop your Cytomine instance, use the stop.sh script stored in Cytomine-bootstrap.

sudo bash stop.sh

The server is stopped but data (databases and images) are preserved.

← Introduction Upgrade →