Install Bigpicture Edition

TIP

If you encounter any issues, please provide a detailed description of the problem in the Bigpicture edition ticket system on Github. (opens new window)

Prerequisites

A cluster must be installed and running before proceeding with the installation. See Clusters.

Installation

This installation procedure is for desktop or laptop computers running a Debian based Linux operating systems.

You must have installed Docker engine (opens new window) and git, and have root permissions (sudo in Debian/Ubuntu).

1. Clone the repository on your computer:

   git clone --branch BP2025.1 https://github.com/Cytomine-ULiege/Cytomine-bigpicture-edition.git
   

2. Go into the cloned folder:

   cd Cytomine-bigpicture-edition
   

3. Edit the file cytomine.template if you want to change default values (like URLs and/or SMTP setup) and also to configure the light import of BP Structured datasets (See specific features).

   WARNING

   The variable SCHEDULER_MASTER_URL and SCHEDULER_OAUTH_TOKEN have to be set to the value generated by your cluster in order to use the App Engine. See MicroK8s Cytomine configuration for more information on how to get these values.

4. Launch the Cytomine installer. This will create all the folders and files necessary to launch Cytomine with Compose:

   sudo docker pull cytomine/installer
   sudo docker run -v $(pwd):/install --user "$(id -u):$(id -g)" --rm -it cytomine/installer:latest deploy -s /install
   

5. Launch cytomine:

   sudo docker compose up -d
   

6. Cytomine is ready to be used:

   • If you have kept the default values your Cytomine is now available on http://localhost/ (opens new window).
   • By default, an admin account has been created for you. To connect to the platform in your browser, retrieve the randomly generated admin password by opening the cytomine.yml file and go to services: default: core : constant: ADMIN_PASSWORD:. You can use this password with the adminusername to get authenticated on your Cytomine.

Update configuration

If you want to change the configuration of a running instance:

1. Update your configuration in the cytomine.template file.

2. Relaunch the Cytomine installer to update your configuration file:

   sudo docker pull cytomine/installer
   sudo docker run -v $(pwd):/install --user "$(id -u):$(id -g)" --rm -it cytomine/installer:latest deploy -s /install
   

3. Restart your running instance:

   sudo docker compose restart
   

Stop Cytomine

To stop your Cytomine instance, use:

sudo docker compose down

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

OIDC Identity Broker LS-AAI integration configuration

Cytomine uses keycloak as IAM and also as a broker to negotiate with LS-AAI to authenticate users using authorization_code flow and go to https://127.0.0.1/iam/realms/cytomine/.well-known/openid-configuration (opens new window) for the metadata, for configuration follow steps below:

A. Configure the broker

1. Access keycloak admin console https://127.0.0.1/iam/admin (opens new window) and authenticate using the default admin user and find the password for it in cytomine.yml under KEYCLOAK_ADMIN_PASSWORD and notice this is not the cytomine admin.
2. Click Identity Providers in the menu.
3. From the Add provider list, select OpenID Connect v1.0 or keycloak openID connect.
4. Redirect URI is prefilled
5. Enter display name as LS_AAI
6. Enter this link https://login.aai.lifescience-ri.eu/oidc/.well-known/openid-configuration in Discovery Endpoint for LS-AAI OIDC metadata
7. In client authentication select Client secret set as basic auth
8. Contact cytomine team at Uliege to get the client ID and client secret , click contact us button below
9. Click save

B. Map claims to roles

The following config assigns the role admin to all external users and this is mandatory.

1. Go to Mappers tab click on add mapper
2. Enter name for the mapper and keep sync mode override as inherit
3. Select Hardcoded Role Mapper
4. From client core select ADMIN role
5. Click save

once steps above are followed a new button appears in the login form to start the authentication process for users coming from other organizations.