Docker Compose deployment

⚠️ Warning: Do not deploy this setup to production. This configuration is meant solely for local development and testing.

πŸ›‘οΈ Ensure your firewall is enabled on the machine running this setup (e.g., ufw on Linux). Running this deployment without a firewall can lead to data leaks or insecure access to internal institutional directories ( especially if LDAP is enabled).

πŸ” Choosing the Components

Before you start, review the components available in map/components.qmd and decide which ones you need.

The main Compose file (docker/docker-compose.yaml) is modular. It uses the include directive and profiles to enable only selected components.

Main docker-compose.yaml 
name: crisalid

include:
  - path: ./neo4j/neo4j.yaml
    env_file: ./neo4j/.env
    project_directory: ./neo4j
  - path: ./apollo/apollo.yaml
    env_file: ./apollo/.env
    project_directory: ./apollo
  - path: ./crisalid-bus/crisalid-bus.yaml
    env_file: ./crisalid-bus/.env
    project_directory: ./crisalid-bus
  - path: ./harvester/harvester.yaml
    env_file: ./harvester/.env
    project_directory: ./harvester
  - path: ./ikg/ikg.yaml
    env_file: ./ikg/.env
    project_directory: ./ikg
  - path: ./cdb/cdb.yaml
    env_file: ./cdb/.env
    project_directory: ./cdb
  - path: ./sovisuplus/sovisuplus.yaml
    env_file: ./sovisuplus/.env
    project_directory: ./sovisuplus
  - path: ./keycloak/keycloak.yaml
    env_file: ./keycloak/.env
    project_directory: ./keycloak

For example:

docker compose \
  --profile neo4j \
  --profile apollo \
  --profile crisalid-bus \
  --profile harvester \
  --profile ikg \
  --profile cdb \
  --profile keycloak \
  --profile sovisuplus \
  up

🧰 Preparation Steps

1. 🧾 .env Files

Each directory under docker/ (e.g. apollo, crisalid-bus, ikg, neo4j, cdb, harvester) has its own .env.sample file.

  • Copy each .env.sample to .env
  • Fill in appropriate values (hostnames, ports, secrets, etc.)
  • The main docker/.env.sample includes values used by multiple components (like RabbitMQ or Neo4j credentials)

If you plan to connect the CRISalid Directory Bridge (cdb) to your institutional LDAP, make sure to set:

LDAP_HOST=
LDAP_BIND_DN=
LDAP_BIND_PASSWORD=

2. πŸ”§ Configure CRISalid Bus

This script reads the .env values and generates the RabbitMQ definitions.json file (exchanges, queues, admin user, etc.).

./docker/configure_crisalid_bus.sh

3. πŸ”§ Configure CRISalid Directory Bridge (CDB)

This script clones the DAGs and runs the Airflow initialization:

./docker/configure_cdb.sh

ℹ️ In dev, Airflow GUI admin credentials are set to admin:admin.

After running the script, if you intend to use the CSV mode for structures and people (instead of LDAP), place your data files in:

docker/cdb/data/
β”œβ”€β”€ structure.csv
└── people.csv

Sample CSVs:

Full documentation (in French):

4. πŸ”‘ Configure Keycloak

Keycloak is handling authentication within the system. Multiple client applications (such as Sovisu+) can share the same authentication realm. To set up Keycloak in this environment, follow these steps:

  1. Global .env Configuration

In the global .env file, you will find the shared Keycloak configuration variables, such as the realm name ( KEYCLOAK_REALM) and the client secrets (SOVISUPLUS_KEYCLOAK_CLIENT_SECRET). The KEYCLOAK_REALM can be customized ( e.g., crisalid-my-university) for readability.

Example:

KEYCLOAK_REALM=crisalid-inst
SOVISUPLUS_KEYCLOAK_CLIENT_SECRET=MY-SECRET-VALUE
  1. Keycloak Configuration Script

Run the ./configure_keycloak.sh script. This will create the required configuration file from the template ( docker/keycloak/config/crisalid-inst.json.template).

  1. Customizing Keycloak .env Settings

The docker/keycloak/.env.sample file provides the environment settings for Keycloak, such as the admin credentials and database configurations. Copy the sample file to .env and modify the settings as needed.

KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=admin
KEYCLOAK_DB_VENDOR=postgres
KEYCLOAK_DB_HOST=keycloak-db
KEYCLOAK_DB_PORT=5432
KEYCLOAK_DB_NAME=keycloak
KEYCLOAK_DB_USER=keycloak
KEYCLOAK_DB_PASSWORD=keycloak

5. Define specific URIs in /etc/hosts

To ensure that Sovisu+ and Keycloak can be accessed correctly, you need to define specific URIs in your /etc/hosts file. This is necessary because Sovisu+ uses OAuth2 with ORCID, which requires a specific hostname even to deliver β€œsandbox” keys.

# Add these lines to your /etc/hosts file
127.0.0.1 sovisuplus.local
127.0.0.1 keycloak.local

πŸ”Œ Communication with Host Machine

If you want to connect external tools (on your host) to the containers, open the necessary ports.

For example, to expose RabbitMQ’s AMQP port on the host machine, edit docker/crisalid-bus/crisalid-bus.yaml and uncomment the 2nd ports line:

ports:
  - "${CRISALID_BUS_HTTP_PORT}:15672"
#  - "${CRISALID_BUS_AMQP_PORT}:5672"
expose:
  - "${CRISALID_BUS_AMQP_PORT}"

♻️ Resetting Containers

To stop and delete containers + volumes for one profile:

docker compose --profile cdb down --volumes

To also delete images:

docker compose --profile cdb down --volumes --rmi all

To ensure volumes are removed, you can also run:

docker volume rm postgres-db-volume redis-db-volume data-versioning-redis-volume
docker volume rm keycloak_postgres_data
docker volume rm svp-db-volume
docker volume rm crisalid-bus-volume
docker volume rm neo4j-data-volume neo4j-logs-volume neo4j-import-volume neo4j-plugins-volume neo4j-backups-volume

πŸš€ Starting the Services

To start the services, run:

docker compose --profile neo4j --profile apollo --profile crisalid-bus --profile harvester --profile ikg --profile cdb --profile keycloak --profile sovisuplus up

This command will start the selected components in the background. You can add or remove profiles as needed.

βœ… Next Steps

Once your services are up, follow the component-specific instructions in each section of the documentation. You can now:

🧭 Back to Development Index