Skip to main content

Development Setup

This document provides instructions for running and managing the Keycloak instance used for local development in TUMApply only. For production Keycloak setup and configuration, please refer to the Production Setup.

Keycloak Docker Container​

warning

All commands below must be executed from the project root directory.

▶️ Start Keycloak​

To start the Keycloak docker container with the required realm configuration, run this command from the project root:

note

The first startup may take up to a minute as Keycloak initializes and imports the realm configuration.

docker compose -f src/main/docker/keycloak.yml up --build

Verify Setup​

After running the above command, two URLs will be available:

ServiceURLDescriptionUsernamePassword
Admin Consolehttp://localhost:9080/adminKeycloak Management UIadminadmin
Realmhttp://localhost:9080/realms/tumapplyTUMApply realm endpoint

  • Open the Admin Console at http://localhost:9080/admin and log in with username admin and password admin.

  • Navigate to the TUMApply realm and verify that the test users listed below are present. (If you do not see the TUMApply realm, use "Manage realms" button in the top left of the Keycloak Admin Console to switch from the default master realm to tumapply. Then, open the Users section in the left-hand menu to view all available test users and confirm that the configuration has been imported correctly.)

  • Confirm that the realm configuration is loaded and the server is responsive.

View Keycloak Logs​

To view the Keycloak logs run the following command:

docker logs -f tumapply-keycloak-1

🛑 Stop Keycloak​

To stop the Keycloak docker container run the following command:

docker compose -f src/main/docker/keycloak.yml down

🔄 Reset Keycloak​

To reset the Keycloak volume and re-import the realm configuration:

danger

This command will remove all data.

docker compose -f src/main/docker/keycloak.yml down && docker compose -f src/main/docker/keycloak.yml up --build

📁 Realm Import​

Keycloak imports the realm configuration from src/main/docker/realm-config/tumapply-realm.json during startup.

warning

Any manual changes made in the Keycloak Admin UI are not persisted after container restarts unless explicitly exported back to the realm JSON file.

To apply changes made to the realm configuration file (tumapply-realm.json), restart Keycloak with:

docker compose -f src/main/docker/keycloak.yml down
docker compose -f src/main/docker/keycloak.yml up --build

⚠️ Common Issues​

Common Issues
  • Port 9080 already in use: Change the port in src/main/docker/keycloak.yml or stop the other container using it.
  • "Invalid configuration" error: Check the Keycloak logs and JSON syntax in src/main/docker/realm-config/tumapply-realm.json.
  • Realm not visible in Admin Console: Verify the realm file path in src/main/docker/keycloak.yml is correct.
  • Login fails: Double-check user credentials against the test users table above.

ℹ️ Important Notes​

info

This local Keycloak environment uses an embedded in-memory database and is intended for local development only. All Keycloak data, including users, sessions, and tokens, are temporary and deleted when the container is stopped or removed.

It should not be used for persistent or shared data.

For production Keycloak setup and management, please refer to the Production Setup.