...
Table of Contents outline true
Install Cytomine
Step 1 - Retrieve Cytomine-bootstrap
First of all, we retrieve the Cytomine-bootstrap installation procedure.
1.1 Install latest official release from Cytomine cooperative
If you want to install the last official release, copy/paste these commands:
Code Block | ||||
---|---|---|---|---|
| ||||
mkdir Cytomine_src/ cd Cytomine_src/ wget https://github.com/cytomine/Cytomine-bootstrap/archive/master.zip -O bootstrap.zip unzip bootstrap.zip mv Cytomine-bootstrap-master Cytomine-bootstrap |
1.2 Install latest release with last developments from Cytomine ULiege
To install Cytomine with the last features from ULiège research team, copy/paste these commands:
Code Block | ||||
---|---|---|---|---|
| ||||
sudo apt-get install git mkdir Cytomine_src/ cd Cytomine_src/ git clone https://github.com/Cytomine-ULiege/Cytomine-bootstrap.git cd Cytomine-bootstrap |
Step 2 - Install Docker
Then, we need to install the Docker engine.
...
If needed, you will find a complete documentation on the official site.
Step 3 - 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.:
...
You have two deployment options:
3.1 If you want to deploy on a local host :
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".
...
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.
3.2 If you want to make your Cytomine instance accessible from anywhere :
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
The following tables explain how to configure your installation.
For a basic, simple installation, you need to configure only the mandatory variables.
URLS
Please use URLs that are not already present in your /etc/hosts file to avoid conflicts.
Variable | Importance | Explanation | Example value |
---|---|---|---|
CORE_URL | Mandatory | the URL dedicated to the Core of Cytomine | localhost-core |
IMS_URLS | Mandatory | the URL(s) dedicated to one or more image server Be careful that their value are space free even between two values | [localhost-ims] |
UPLOAD_URL | Mandatory | the URL for image upload | localhost-upload |
RETRIEVAL_URL | Advanced | the URL of retrieval server | localhost-retrieval |
IIP_CYTO_URL | Advanced | the URL of Cytomine IIP server | localhost-iip-cyto |
IIP_JP2_URL | Advanced | the URL of IIP server for JPEG2000 | localhost-iip-jp2 |
Storage Paths
You have to choose existing paths on an available filesystem where image files will be stored. Please note you have to specify paths without a "/" at the end (e.g. "/data", not "/data/").
Variable | Importance | Explanation | Example value |
---|---|---|---|
IMS_STORAGE | Mandatory | A pre-existing filesystem path to store images (withtout ending /) | /data (but not /data/) |
IMS_BUFFER_PATH | Mandatory | A pre-existing filesystem path to IMS buffer (without ending /) | /data/buffer (but not /data/buffer/) |
ALGO_PATH | Mandatory | A pre-existing filesystem path to store Cytomine softwares (without ending /) | /data/algo |
RETRIEVAL_PATH | Mandatory | A pre-existing filesytem path to store retrieval data (without ending /) | /data/thumb |
BACKUP_PATH | If backup | A pre-existing filesystem path to store auto backup |
Email
Variable | Importance | Explanation | Example value |
---|---|---|---|
SENDER_EMAIL | Optional to test the app, mandatory otherwise | email params of the sending account | |
SENDER_EMAIL_PASS | Optional to test the app, mandatory otherwise | email params of the sending account | |
SENDER_EMAIL_SMTP_PORT | Optional to test the app, mandatory otherwise | email params of the sending account | |
SENDER_EMAIL_SMTP_HOST | Optional to test the app, mandatory otherwise | email params of the sending account | |
RECEIVER_EMAIL | If backup | email adress of the backup reports receiver |
IRIS
Variable | Importance | Explanation | Example value |
---|---|---|---|
IRIS_ENABLED | Advanced | Enable IRIS (see IRIS project) | |
IRIS_URL | Advanced | ||
IRIS_ID | Advanced | Usefull if we are admin of multiple IRIS version | |
IRIS_ADMIN_NAME | Advanced | ||
IRIS_ADMIN_ORGANIZATION_NAME | Advanced | ||
IRIS_ADMIN_EMAIL | Advanced | The email adress where user will ask permissions for IRIS projects |
Other advanced configuration
Variable | Importance | Explanation | Example value |
---|---|---|---|
BACKUP_BOOL | Advanced | To enable an automatic daily backup, set to true | false |
IS_LOCAL | Advanced | To deploy on distinct machines, set to false | true |
RETRIEVAL_ENGINE | Advanced | memory, redis | redis |
RETRIEVAL_PASSWD | Advanced | ||
RABBITMQ_LOGIN | Advanced | ||
RABBITMQ_PASSWORD | Advanced | ||
NB_IIP_PROCESS | Advanced | Number of simultaneous IIP processes | 20 |
MEMCACHED_PASS | Advanced | ||
BIOFORMAT_ENABLED | Advanced | Enable the bioformat convertor to support more formats (VSI, OME-TIFF,...) | |
BIOFORMAT_ALIAS | Advanced | ||
BIOFORMAT_PORT | Advanced |
Step 4 - Deploy Cytomine
Then, you can generate your installation file and deploy Cytomine. Run following commands in the Bootstrap directory:
Code Block | ||||
---|---|---|---|---|
| ||||
sudo bash init.sh sudo bash start_deploy.sh |
Step 5 - Install test data (optional) - temporary unavailable
At the end of the installation we recommend to install test data (which takes roughly 30 additional minutes) in order to follow examples from our user guide.
Step 6 - Contact us and cite us (optional)
We kindly ask you to cite our (Marée et al., Bionformatics 2016) paper and website (http://www.cytomine.be/) when using Cytomine in your work.
Please also consider contacting us to let us know who you are and why you are using Cytomine.
...
Troubleshooting
In case of problems, see page Known problems of v1.0 (and specially the entry "Error : postgis_data not found/not started").
...
Please note that server components might take one or two minutes to boot the first time (which will generate a "502 Bad Gateway message" or the browser to wait for a reponse).
...
How to test your installation.
You can log into Cytomine through the http://CORE_URL (by default: http://localhost-core/) in your web browser using the admin session (the password was asked during installation). If you did not install the "test data", you will have an empty instance. You have to create a project, users, ...
...
Code Block |
---|
####################### # Root logger option log4j.rootLogger=DEBUG, stdout # Direct log messages to stdout log4j.appender.stdout=org.apache.log4j.ConsoleAppender log4j.appender.stdout.Target=System.out log4j.appender.stdout.layout=org.apache.log4j.PatternLayout log4j.appender.stdout.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %m%n ####################### |
...
How to update your installation.
Docker is also used to easily update your Cytomine installation.
...
Tip |
---|
NB : If you add a custom container to your installation, you have to update this script. |
...
How to uninstall Cytomine.
Please let us know why Cytomine does not meet your expectations.
...