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 external UI no longer bootstraps OIDC settings from GET /ui-api/runtime-config. In the sandbox, the backend reads UI_OIDC_* variables from docker-compose/.env via docker-compose/docker-compose.yml, manages the OIDC callback itself, then returns a signed UI JWT to the browser.

💾 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.