Platform Development Setup

This guide is for developers who want to build applications on top of the Citadel Platform. It explains how to easily spin up a full Citadel environment (IAM, Admin Portal, Shell App, etc.) as a dependency for your project using our provided instruction set.

Overview

We provide a self-contained Dev Container configuration (devcontainer-citadel) that allows you to run the complete Citadel stack alongside your own application code. This eliminates the need to manually configure multiple repositories, databases, and authentication flows just to start developing.

Prerequisites

• Visual Studio Code
• Docker Desktop or Docker Engine
• Remote - Containers extension for VS Code

Setup Guide

1. Copy Configuration

Copy the devcontainer-citadel directory from the Citadel repository into the root of your new project and rename it to .devcontainer.

# Example
cp -r /path/to/citadel/devcontainer-citadel ./my-new-project/.devcontainer

2. Configure Dev Container

Open .devcontainer/devcontainer.json in your editor. By default, it runs a minimal core stack. To enable the full Citadel platform:

1. Locate the dockerComposeFile array.
2. Uncomment compose.citadel.yml.

  "dockerComposeFile": [
    "compose.core.yml",

    // --- Citadel Platform Stack ---
    // Comment out the below line if you do not want to run the full Citadel platform dependencies
    "compose.citadel.yml"
  ],

3. Start the Environment

1. Open your project in VS Code.
2. Run the command Dev Containers: Reopen in Container.
3. VS Code will build the container and spin up all defined services.

4. Verify Services

Once the container is running, the Citadel platform services will be accessible at the following URLs:

Service	URL	Description
Shell App	http://localhost:5000	The main entry point for the frontend application.
Admin Portal	http://localhost:5001	Administrative interface (accessible via Shell App).
Onboarding UI	http://localhost:5002	User onboarding flows.
Keycloak	http://localhost/keycloak	Identity Provider (Admin Console).
Mailpit	http://localhost:8025	Email testing interface.
Temporal UI	http://localhost:8233	Workflow orchestration dashboard.

5. Development Workflow

You can now develop your own services or micro-frontends and integrate them with the running Citadel stack.

• Authentication: Your apps can authenticate against the running Keycloak/IAM instance.
• Routing: The stack includes Traefik routing rules that makes services available on localhost.
• Database: A shared PostgreSQL instance is available with pre-configured databases for Citadel services.

Configuration Details

The devcontainer-citadel folder includes a citadel-config directory containing all necessary template files (IAM config, validation rules, Traefik routes) to initialize the platform in a zero-conf manner.

• compose.citadel.yml: Defines the platform services (IAM, Admin BFF, UI apps) and infrastructure interactions.
• init-multiple-dbs.sh: Automatically initializes required databases on startup.
• citadel-init service: Auto-generates runtime configuration using the templates in citadel-config.