Skip to main content

Advanced Local Development Setup

The dev container is designed to be flexible. While core services like PostgreSQL and NATS run by default, other backing services like identity providers are optional and can be enabled as needed.

Prerequisites​

  • Visual Studio Code
  • Docker Desktop
  • The VS Code Dev Containers extension

This guide explains how to enable and configure Keycloak for local development, allowing you to test authentication and authorization flows.

Setting up a Local Identity Provider (Keycloak)​

1. Enable Keycloak Services​

The Docker Compose files for Keycloak and its database are disabled by default. To enable them, you need to edit the dev container configuration file:

  1. Open .devcontainer/devcontainer.json.

  2. Find the dockerCompose section.

  3. Uncomment the line for compose.keycloak.yml.

    "dockerCompose": [
        "compose.core.yml",
        "compose.keycloak.yml", // <-- Uncomment this line
        // ... other services
    ],

  4. After saving the file, rebuild your dev container. VS Code should prompt you to do this automatically.

2. Configure Keycloak​

Once the container is rebuilt and Keycloak is running, you need to run a setup script to configure the realm and clients.

  1. Run the setup script from the workspace root:

    ./scripts/keycloak/setup.sh

  2. This script will:

    • Wait for Keycloak to be ready.
    • Create a new realm named citadel.
    • Create the necessary clients and service accounts.
    • Create a default realm admin user (admin@example.com / StrongP@ssw0rd!).
    • Update the .env file in the project root with the required client IDs and secrets.

Note: If a .env file already exists, the script will update the relevant Keycloak variables.

3. Starting Dependent Services​

With Keycloak configured and the .env file populated, you can start downstream services.

Starting the IAM Service​

The iam-service needs to be seeded with the super admin user ID from Keycloak. The start-iam.sh script handles this automatically.

  1. Run the start script for the iam-service:

    ./scripts/start-iam.sh

  2. This script reads the .env file and executes the database seed command, linking the iam-service to the Keycloak super admin.

Starting the Shell App​

The shell-app can now be started to log in against the live iam-service and Keycloak.

  1. To start the shell-app connected to the live backend services:

    ./scripts/start-shell.sh

  2. The application will be available at http://localhost:5000. You can now log in using the Keycloak credentials (user: admin, password: password).

Note: Starting a Micro-Frontend (MFE) Once the shell-app is running, you can start individual micro-frontends. For example, to start the admin-portal-ui:

pnpm --filter=admin-portal-ui start

The admin portal will then be accessible at http://localhost:5000/admin within the shell application after you log in.

4. Resetting the Environment​

If you need to start the setup process from scratch (e.g., to re-run the setup script), you need to clean up the existing configuration.

  1. Reset Keycloak: Keycloak configuration is persistent in the citadel realm. To reset it:

    • Open the Keycloak Admin Console at http://localhost/keycloak/.
    • Log in with the admin credentials (default is usually admin/admin for the Keycloak master realm, unless changed).
    • Select the citadel realm from the top-left dropdown.
    • Go to Realm Settings.
    • Click the Action dropdown (top right) and select Delete.
    • Confirm the deletion.

    Deleting the realm allows ./scripts/keycloak/setup.sh to run again as if it were a fresh install.

  2. Reset the IAM Service Database: A helper script is provided to drop and recreate the iam-service database schema.

    ./scripts/iam/cleanup.sh

  3. Remove the .env file:

    rm .env

After resetting, you can run the setup scripts again to generate a new configuration.

Running E2E Tests​

To run the end-to-end (E2E) test suite, several additional services must be enabled in your development environment.

1. Prerequisites​

Before opening the project in the dev container (or rebuilding it), ensure the following services are uncommented in your .devcontainer/devcontainer.json file:

  • compose.keycloak.yml
  • compose.temporal.yml
  • compose.spicedb.yml
  • compose.mailpit.yml

This ensures that Keycloak, Temporal, SpiceDB, and Mailpit are available.

2. Setup Keycloak​

Once inside the dev container, run the Keycloak setup script to configure the necessary realms and clients:

./scripts/keycloak/setup.sh

Note: If this was configured already you can reset and reconfigure or proceed with credentials in .env

3. Install Playwright Browsers​

Install the required browsers for Playwright:

pnpm exec playwright install --with-deps

4. Run E2E Tests​

Finally, execute the E2E test script:

./scripts/e2e.sh

Note: Internal Orchestration The e2e.sh script internally uses ./scripts/start-all.sh to spin up all required services (including those listed in prerequisites) and the frontend apps. If you prefer to manually explore the application with all services running, you can run ./scripts/start-all.sh directly.

Interactive Mode (Playwright UI)​

If you want to manually run tests or explore the state of the application using Playwright's UI, you can pass the --ui flag. This will open the Playwright UI in a browser window:

./scripts/e2e.sh --ui