Sandbox Environment Guide

The development sandbox provides an isolated local environment for development and testing. It uses Docker to mock the live system, granting you full control over local data and interfaces.

Pre-requisites

Depending on your organization's procurement policies (e.g., BC Government restrictions), choose one of the following container engines:

1. Choose Your Container Engine

• Standard: Docker Desktop (Requires WSL2 on Windows).
• Policy-Compliant Alternatives: - Podman (Recommended for Mac/Linux)
• Rancher Desktop
• Docker Engine (Linux native)

2. Manual CLI Setup (Non-Docker Desktop Users)

If you are using the Docker CLI without the Desktop GUI, ensure your environment is linked:

OS	Installation / Setup Command
macOS	brew install docker docker-compose docker-buildx mkdir -p ~/.docker/cli-plugins ln -s $HOMEBREW_PREFIX/lib/docker/cli-plugins/docker-compose ~/.docker/cli-plugins/docker-compose
Windows	Follow the WSL2 + Native Docker Guide

Getting Started

Spin Up the Sandbox

Launch the environment. The setup includes automated provisioning for Keycloak and n8n custom nodes and external endpoints.

In docker-compose directory, run:

cp .env.example .env
docker compose up --build

docker compose automatically reads docker-compose/.env, so .env.example is the committed template and .env is your active local config.

Service Catalog

Once the containers are healthy, the following services are available:

Service	Description	Local Access
Keycloak	Identity & Access Management	http://localhost:8080
n8n	Workflow Automation	http://localhost:5678
Postgres	Primary DB (v18.0)	localhost:5432

Automated Provisioning Details

The sandbox uses a "Dependency Chain" to ensure services configure themselves in the correct order:

1. Postgres (initdb): Creates the initial schemas. Note: Ensure your ./initdb folder contains a script to create the keycloak database, as Postgres only creates the one defined in POSTGRES_DB by default.
2. Keycloak Provisioning: The keycloak-provision service uses the Keycloak Admin CLI or API to create the starter realm and the OIDC client.
3. n8n Provisioning:

• Idempotency: Checks if workflows exist before importing to avoid duplicates.
• Custom Nodes: Injects community nodes into the /home/node/.n8n/nodes directory.
• Hooks: Runs migrate.cjs to set up external hooks (e.g., custom logging or auditing).

UI Backend Auth Config

The sandbox uses the single OIDC flow. The external UI does not bootstrap settings from GET /ui-api/runtime-config; the backend reads UI_OIDC_* and OIDC_* variables from docker-compose/.env via docker-compose/docker-compose.yml, exposes the sole callback at GET /rest/auth/oidc/callback, verifies ID tokens (JWKS/issuer/audience/nonce, userinfo.sub bound to id_token.sub, OIDC_ISSUER required in every mode), and issues both artifacts on eligibility: n8n-auth cookie and a one-time session exchange handle that the SPA trades at POST /ui-api/auth/exchange with JSON body {"session": "<handle>"} (authExchangeSchema). Ineligible identities receive a UI-only handle to /ui/access-request and any prior n8n-auth is cleared on the access-request callback. There is no frontend-hook mode switch and no pre-warming via the old callback — eligible logins pre-warm tenant roles/groups and sync tenant projects non-blocking together.

💾 Persistence & Volumes

Data is persisted across restarts using named Docker volumes. If you need to wipe the environment, run docker-compose down -v.

• n8n_storage: Stores the .n8n folder, including SQLite (if used), binary data, and installed nodes.
• postgres_storage: Stores the physical database files for both n8n and Keycloak.