Skip to main content

Local Development Setup

This guide gets the complete ClickID stack running on your local machine using Docker Compose. You will have a fully functional Keycloak IdP, the SP Portal, a demo SP, and Mailhog for email testing.

Prerequisites​

Before you begin, ensure you have the following installed:

ToolMinimum versionNotes
Docker24.xDocker Engine or Docker Desktop
Docker Composev2.20Included with Docker Desktop; docker compose (v2) not docker-compose (v1)
bash5.xmacOS ships 3.x; install via Homebrew if needed
curlanyFor the setup scripts
jq1.6+JSON processing in setup scripts
macOS users

Install bash, curl, and jq via Homebrew: brew install bash curl jq

Step 1: Clone the repository​

git clone https://github.com/clickid/clickid
cd clickid

Step 2: Configure environment variables​

Copy the example environment file:

cp .env.example .env

Open .env in your editor. The one value you must set before first run is SECTOR_ID_PEPPER:

# Generate a cryptographically random pepper
SECTOR_ID_PEPPER=$(openssl rand -base64 32)

# Write it into .env (or paste the output manually)
sed -i "s|^SECTOR_ID_PEPPER=.*|SECTOR_ID_PEPPER=${SECTOR_ID_PEPPER}|" .env
Do not lose your pepper

The SECTOR_ID_PEPPER is used to derive all sector-IDs. If you change it after users have logged in, every user will receive a different sector-ID on next login — effectively unlinking their accounts at every SP. For local dev this does not matter, but treat it seriously in any persistent environment.

The other values in .env.example have sensible defaults for local development and do not need to be changed.

Step 3: Build and start the stack​

docker compose up --build -d

This will:

  1. Build the custom Keycloak image (includes the Sector-ID Mapper SPI JAR and the EU Theme)
  2. Build the SP Portal image
  3. Start PostgreSQL, Keycloak, the SP Portal, the demo SP, and Mailhog
  4. Import the clickid and clickid-sandbox realms into Keycloak on first startup

First build takes 3–5 minutes. Subsequent starts are much faster.

Wait until Keycloak is healthy before proceeding:

docker compose logs -f keycloak | grep "Keycloak .* started"

You should see a line like Keycloak 24.x.x started in ...ms.

Step 4: Run setup scripts​

These scripts create the SP Portal admin account and seed the demo user. They only need to be run once.

./scripts/setup-sp-portal-admin.sh
./scripts/seed-demo-user.sh

setup-sp-portal-admin.sh creates a Keycloak OIDC client and admin user that the SP Portal uses to call the Keycloak Admin API.

seed-demo-user.sh creates the demo user resident@example.nl in both realms with the password Welkom12345! and TOTP disabled (for easy testing).

Service URLs​

Once everything is running, the following services are available:

ServiceURLPurpose
Keycloak Admin Consolehttp://localhost:8080/adminManage realms, users, clients
Live IdP metadatahttp://localhost:8080/realms/clickid/protocol/saml/descriptorSAML metadata for live realm
Sandbox IdP metadatahttp://localhost:8080/realms/clickid-sandbox/protocol/saml/descriptorSAML metadata for sandbox realm
SP Portalhttp://localhost:3000Self-service SP registration
Demo SPhttp://localhost:8082Sample service provider for testing
Mailhoghttp://localhost:8025Catch-all SMTP for email testing

Default Keycloak admin credentials (set in .env):

FieldDefault value
Usernameadmin
Passwordadmin (change this)

Verifying the stack​

Check that all containers are running​

docker compose ps

All services should show running (or healthy for services with healthchecks). If any service is in restarting, check its logs:

docker compose logs <service-name>

Test the demo SP login flow​

  1. Open http://localhost:8082 in your browser
  2. Click Login with ClickID
  3. You should be redirected to the Keycloak login page (EU Theme, blue)
  4. Log in with resident@example.nl / Welkom12345!
  5. You should be redirected back to the demo SP and see your sector-ID displayed

Test the SP Portal​

  1. Open http://localhost:3000
  2. Sign in with the portal admin credentials created by setup-sp-portal-admin.sh (printed to stdout during that script)
  3. You should see the SP registration dashboard

Email testing with Mailhog​

All outbound email from Keycloak (email verification, password reset) is routed to Mailhog in the local dev environment. Open http://localhost:8025 to view caught emails.

No real emails are sent. You can also trigger email verification flows and inspect the full email content and headers from the Mailhog UI.

Stopping and resetting​

Stop the stack (preserves data):

docker compose down

Full reset including database volumes (useful after changing .env or realm config):

docker compose down -v
docker compose up --build -d
./scripts/setup-sp-portal-admin.sh
./scripts/seed-demo-user.sh