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.

This guide explains how to enable and configure the included R-Auth identity provider for local development, allowing you to test authentication and authorization flows.

Setting up a Local Identity Provider (R-Auth)​

1. Enable R-Auth Services​

The Docker Compose files for R-Auth and its MongoDB 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 lines for compose.mongo.yml and compose.rauth.yml.

    "dockerCompose": [
        "compose.core.yml",
        "compose.mongo.yml", // <-- Uncomment this line
        "compose.rauth.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 R-Auth and Start the Admin BFF​

The admin-bff service needs to be started to automatically configure R-Auth and generate the necessary environment variables.

  1. Once inside the rebuilt container, run the setup script from the workspace root:

    ./scripts/start-admin-bff.sh

  2. This script will:

    • Set up the R-Auth instance.
    • Create a .env file in the project root with the required client IDs and secrets.
    • The default admin user is admin@example.com with the password 14CharP@ssword.

Note: If a .env file already exists, the script will not run. To re-run the setup, you must first reset the environment.

3. Starting Dependent Services​

With R-Auth running and the .env file created, you can now start downstream services that depend on the IdP for authentication.

Starting the IAM Service​

The iam-service needs to be seeded with the super admin user ID from the newly created R-Auth instance. 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 R-Auth super admin.

Starting the Shell App​

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

  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 R-Auth credentials.

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 R-Auth setup process from scratch, you must remove the old .env file and clear the databases for both R-Auth and the iam-service.

  1. Reset the R-Auth Database: You need to execute a command inside the rauth-backend container to drop its database.

    # 1. Get a shell inside the rauth-backend container
    docker exec -it citadel_devcontainer-rauth-backend-1 bash

    # 2. Run the cleanup script inside the container
    AUTH_SOURCE=admin TEST_MONGO_URI=mongodb://root:changeit@mongo/rauthdb node scripts/cleanup.js

  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 scripts again to generate a new configuration.