# Configuration

This page provides some features that can be configured on Cytomine.

# Configure LS-AAI Identity Broker

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

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.
Click Identity Providers in the menu.
From the Add provider list, select OpenID Connect v1.0 or keycloak openID connect.
Redirect URI is prefilled
Enter display name as LS_AAI
Enter this link https://login.aai.lifescience-ri.eu/oidc/.well-known/openid-configuration in Discovery Endpoint for LS-AAI OIDC metadata
In client authentication select Client secret set as basic auth
Contact cytomine team at Uliege to get the client ID and client secret , click contact us button below
Click save

# B. Map claims to roles

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

Go to Mappers tab click on add mapper
Enter name for the mapper and keep sync mode override as inherit
Select Hardcoded Role Mapper
From client core select ADMIN role
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.

# Datasets Importation

TIP

Importing does not create explicit copies or duplication of files, only database entries and symbolic links are created.

This section outlines the procedure for importing datasets, which are formatted according to the BP Dataset File Structure Standard (opens new window).

# Prerequisites

Cytomine Python client (opens new window) (v3.1.0+ recommended)
sdafs (opens new window) (optional)

TIP

sdafs is optional and only needed if you do not have the datasets on your filesystem.

The installation guide is available in the sdafs repository (opens new window).

The structure of the imported directory should follows:

root
|--- {DATASET_UUID}
|    |--- DATASET_{IDENTIFIER}
|         |--- METADATA
|         |    |--- dataset.xml
|         |    |--- policy.xml
|         |    |--- image.xml
|         |    |--- annotation.xml
|         |    |--- observation.xml
|         |    |--- observer.xml
|         |    |--- sample.xml
|         |    |--- staining.xml
|         |
|         |--- IMAGES
|         |    |--- IMAGE_{IDENTIFIER}
|         |    |    |--- *.dcm files of an Image
|         |    |--- IMAGE_{IDENTIFIER}
|         |    |    |--- *.dcm files of an Image
|         |
|         |--- ANNOTATIONS
|         |    |--- *.geojson

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

The METADATA and ANNOTATIONS directories are optional.

TIP

If you’re working with sdafs, the directories are already organised in the structure shown above.

# [Optional] Configuration

TIP

This configuration is optional if you planned to use the default location ./cytomine/data/dataset for importing your datasets.

Create .env in the cytomine folder and add the path to your dataset folder:

IMPORT_PATH=<path-to-dataset-folder>

Where <path-to-dataset-folder> is the path to your dataset folder.

If no .env file was provided, the default location is ./cytomine/data/dataset

WARNING

This step should be done before the docker compose up -d command in the Cytomine installation guide.

# Usage

Using the Cytomine python client, you can import the datasets with the following command:

python import_datasets.py --host <cytomine-host> --private_key <private-key> --public_key <public-key>

where <cytomine-host> is your Cytomine host, <public-key> and <private-key> are your public and private keys.

WARNING

Several factors can slow down the importation:

You are using sdafs, it is currently slow the first time the data are loaded
You have a large amount of files on your filesystem

← Installation Guide Backup and restore →