Skip to content

Keycloak

Shared Keycloak identity provider for all BluesBraces projects. Runs as a standalone Docker Compose stack on the VPS at /opt/keycloak, exposed via Traefik at https://auth.bluebraces.online.

For Recron-specific realm and client configuration (clients, LinkedIn IdP, token settings), see Keycloak Setup.

Structure

├── docker-compose.yml       # Keycloak service + Traefik labels
├── .env.example             # Template for admin credentials
├── realms/
│   └── realm-export.json    # Realm config, auto-imported on first start
└── themes/
    └── keywind/             # Custom login theme

Realms

Realm Used by
recron Recron (app.bluebraces.online)

New projects should create their own realm or reuse recron for SSO.

Realm Import / Export

Import

realms/realm-export.json is auto-imported on first startup only. If the realm already exists in the database, Keycloak skips the import.

To force re-import after updating the JSON:

cd /opt/keycloak
docker compose down -v    # removes data volume — ALL realm data is lost
docker compose up -d      # fresh start, realm re-imported from JSON

Export

After making changes in the Keycloak Admin UI, export the realm to keep realm-export.json in sync:

  1. Log in to Keycloak Admin Console (https://auth.bluebraces.online)
  2. Select the target realm
  3. Realm settings → Action → Partial export
  4. Enable: Include clients, Include roles
  5. Replace realms/realm-export.json with the export and commit

Deployment

CI/CD (GitHub Actions)

Push to main triggers .github/workflows/deploy.yml which SSHs into the VPS, pulls the repo via GHCR_TOKEN, and runs docker compose up -d.

Required secrets: VPS_HOST, VPS_USER, VPS_SSH_KEY, GHCR_TOKEN, KEYCLOAK_ADMIN, KEYCLOAK_ADMIN_PASSWORD.

Manual Deployment

# Requires the "proxy" network (created by Traefik)
docker network inspect proxy >/dev/null 2>&1 || docker network create proxy

# Clone / update repo
cd /opt
git clone https://github.com/JanKrajewskiIT/keycloak.git keycloak 2>/dev/null || (cd keycloak && git pull)
cd /opt/keycloak

# Configure (first time only)
cp .env.example .env    # Edit KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD

# Deploy
docker compose pull
docker compose up -d --remove-orphans

Updating After Changes

cd /opt/keycloak
git pull
docker compose pull
docker compose up -d --remove-orphans