Platform Development Setup

This guide is for developers who want to build applications on top of the Citadel Platform. It explains how to spin up a fully pre-configured Citadel environment (IAM, Admin Portal, Shell App, etc.) as a dependency for your project using our XaaSified Dev Container setup.

Overview

We provide a specialized Dev Container configuration (devcontainer-citadel) that provides the complete Citadel stack as a set of ready-to-use services. This setup includes automated bootstrapping for:

• Keycloak: Auto-created realms, clients, and admin users.
• IAM: Pre-initialized with OIDC connections and default tenants.
• Shared Infrastructure: Postgres, Redis, NATS, and Traefik pre-configured with routing rules.

Prerequisites

• Visual Studio Code
• Docker Desktop or Docker Engine
• Dev 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. Initializing the Environment

When you first open your project in VS Code with the .devcontainer folder present, you will be prompted to Reopen in Container.

1. Click Reopen in Container.
2. VS Code will build the environment and start the full Citadel stack.
3. Bootstrapping Sequence: On the first run, a keycloak-setup service will automatically initialize the Identity Provider, generate the necessary credentials, and propagate them to the other services.

3. Verify Services

Once the "up at once" sequence completes, you can verify the services are running at their standard local development endpoints:

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 /admin).
Onboarding UI	http://localhost:5002	User onboarding flows (accessible via Shell App /signup).
Keycloak	http://localhost/keycloak	Identity Provider (Admin Console).
Mailpit	http://localhost:8025	Email testing interface.
Temporal UI	http://localhost:8233	Workflow orchestration dashboard.

4. Development Workflow

The devcontainer provides a "batteries-included" workspace where you can develop your own microservices or micro-frontends.

• Zero-Conf Auth: Your workspace is pre-configured to authenticate against the running IAM instance.
• Service Discovery: Use internal hostnames like iam:1111 or admin-bff:3001 to communicate with platform services.
• Routing: Traefik handles all routing on localhost:80. You can add your own routing rules in .devcontainer/traefik/dynamic.yml.

Configuration Details

The .devcontainer folder is self-contained and includes:

• citadel-config/: Templates for service configurations (IAM, Shell App, etc.).
• scripts/: Orchestration scripts for Keycloak and environment initialization.
• compose.citadel.yml: The "XaaS" service definitions for the platform.
• compose.core.yml: Infrastructure definitions and the workspace setup.
• citadel.env.example: A template for environment variables if you need to override defaults.

Alternatives & Advanced Usage

If you prefer a more modular approach where you only start specific services, you can modify the dockerComposeFile array in .devcontainer/devcontainer.json. However, the default "all-at-once" setup is recommended for the best "Platform-as-a-Service" development experience.