Readme

This repository contains User Management modules for Gazelle.

• Gazelle User Management

  • Requirements

  • Build artifacts

  • Testing

  • Configuration

    • Environment variables

  • Applications deployment (for dev)

    • Deploy with Maven

      • Check the logs

      • Stop the services

    • Deploy with Compose

      • Requirements

  • How to configure the gazelle realm

  • Configuration to integrate a CAS Client

  • Troubleshooting guide

  • License

Requirements

• JDK 21+/Maven 3.8.8+

• Docker 27.0.2+

• Docker-compose 2.18.+

• PostgreSQL 12+ with authorized prepared transactions

Build artifacts

It is possible to generate the artifacts with maven.

This command will directly build the docker image of the project :

• rg.fr-par.scw.cloud/gazelle-snapshot/app/gazelle-keycloak:${project.version}

• rg.fr-par.scw.cloud/gazelle-snapshot/app/gazelle-quarkus:${project.version}

mvn clean package

Testing

It is possible to run different types of test in this application :

• Unit tests that are run with the following command, the jacoco results can be found in module_path/target/site/jacoco/

mvn clean test

• Integration tests that can be run with the following command

mvn verify

• Mutation tests that can be run with the following command, the results can be found in module_path/target/pit-reports/

  In keycloak-provider module, the mutation tests are skipped.

mvn test-compile org.pitest:pitest-maven:mutationCoverage

Be careful of tests that need environment variables, they will more than likely not work, so you will need to exclude them from pitest. To do that add the following in the pom.xml of the module, in the configuration section of the pitest plugin, where the classes to exclude are in :

<excludedClasses>
    <param>path.of.the.class.to.excludes</param>
    <param>path.of.the.classes.to.exclude.*</param>
</excludedClasses>
<excludedTestClasses>
<param>path.of.the.test.class.to.excludes</param>
<param>path.of.the.test.classes.to.exclude.*</param>
</excludedTestClasses>

Configuration

Environment variables

There are many environment variables that can be set to configure the applications.

Refer to the installation guide for more information.

See the official documentation of Keycloak for more information about the environment variables.

Applications deployment (for dev)

Deploy with Maven

The first possibility is to deploy GUM with maven-docker-plugin. This process is useful for integrations tests.

mvn -f gazelle-keycloak/keycloak-provider/pom.xml docker:start

Keycloak should be available by default at http://localhost:28080/.

The list of applications that will be deployed :

• gazelle-database (https://gitlab.inria.fr/gazelle/private/industrialization/docker/gazelle-database)

• gazelle-user-management-keycloak (The keycloak instance)

• gazelle-user-management-quarkus (The GUM backend micro-service)

• Mailhog for testing mails (https://github.com/mailhog/MailHog)

Check the logs

mvn -f user-management/user-management docker:logs 

ℹ️ Tips: you can add the flag -Ddocker.follow to your command to automatically follow the logs.

Stop the services

mvn -f gazelle-keycloak/keycloak-provider/pom.xml docker:stop

Deploy with Compose

For end-to-end testing you can use the docker-compose to deploy the applications that you need.

Requirements

• Data for gazelle-tm

• Environment files (.env)

1) Start the database

docker compose up -d gazelle-database

2) Import data [First deployment only]

psql -h localhost -U gazelle -d postgres -c "CREATE DATABASE gazelle;"
psql -h 127.0.0.1 -U gazelle gazelle < ./gazelle-tm-dev-database.sql

3) Configure realm [Optional]

Copy your realm to /opt/keycloak/data/import/ (create folders if necessary) if additional realms are required.

sudo cp ./realm-gazelle.json /opt/keycloak/data/import/

4) Start GUM

docker-compose up -d gazelle-user-management-keycloak gazelle-user-management-quarkus

How to configure the gazelle realm

To understand better how the gazelle realm works and how to configure it, see Keycloak administrator manual.

Configuration to integrate a CAS Client

In CAS file .properties of your client application:

casServerUrlPrefix="http://localhost:28080/realms/gazelle/protocol/cas"
casServerLoginUrl="http://localhost:28080/realms/gazelle/protocol/cas/login"
casLogoutUrl="http://localhost:28080/realms/gazelle/protocol/cas/logout"
service|serverName=${your.app.service|server.name}

Troubleshooting guide

In case of problems you can check this guide to see if your problem is already in here.

License

    Copyright 2022-2025 IHE International
    
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
    
    http://www.apache.org/licenses/LICENSE-2.0
    
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.