Skip to content
Klutch.sh Docs

Deploying a Keycloak App

Introduction

Keycloak is an open-source identity and access management solution that provides SSO, OAuth2, and OIDC. Deploying Keycloak with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for realms and user data—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and best practices for secure authentication.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your Keycloak configuration (GitHub is the only supported git source)
  • Docker familiarity and basic Keycloak/Quarkus knowledge
  • Database credentials (PostgreSQL recommended)

For onboarding help, see the Quick Start.

Architecture and ports

  • Keycloak serves HTTP on port 8080; set the internal container port to 8080 in Klutch.sh.
  • PostgreSQL should run as a separate Klutch.sh TCP app, exposed on port 8000, connected internally on 5432.
  • Persistent storage is recommended for /opt/keycloak/data to retain themes, exports, and stateful data.

Repository layout

keycloak/
├── themes/                 # Custom themes (optional, mount as volume)
├── providers/              # Custom SPI providers (optional)
├── Dockerfile              # Must be at repo root for auto-detection
├── import/                 # Realm export files (optional)
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Quick local run with the official image:

Terminal window
docker run --rm -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=change_me \
  quay.io/keycloak/keycloak:24.0.5 start-dev

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
exec /opt/keycloak/bin/kc.sh start --optimized

Make it executable with chmod +x start.sh.

Dockerfile for Keycloak (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM quay.io/keycloak/keycloak:24.0.5


WORKDIR /opt/keycloak


# Copy custom themes or providers if needed
COPY themes /opt/keycloak/themes
COPY providers /opt/keycloak/providers
COPY import /opt/keycloak/data/import


EXPOSE 8080
CMD ["/opt/keycloak/bin/kc.sh", "start", "--optimized"]

Notes:

  • Pin the Keycloak image tag for reproducible builds.
  • If you import realms at startup, keep files under /opt/keycloak/data/import and set the appropriate env vars.

Environment variables (Klutch.sh)

Set these in the Klutch.sh app settings (Secrets tab) before deploying:

  • PORT=8080
  • KEYCLOAK_ADMIN=<admin-user>
  • KEYCLOAK_ADMIN_PASSWORD=<admin-password>
  • KC_DB=postgres
  • KC_DB_URL=jdbc:postgresql://<host>:<port>/<db>
  • KC_DB_USERNAME=<db-user>
  • KC_DB_PASSWORD=<db-password>
  • KC_HOSTNAME=example-app.klutch.sh
  • KC_HEALTH_ENABLED=true
  • KC_METRICS_ENABLED=true (optional)

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD="echo Keycloak uses prebuilt image"
  • NIXPACKS_START_CMD=/opt/keycloak/bin/kc.sh start --optimized
  • NIXPACKS_JDK_VERSION=17

These keep Keycloak compatible with Nixpacks defaults when a Dockerfile is absent.

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /opt/keycloak/data — for imports, themes, and stateful data.
  • /opt/keycloak/providers — optional if you add custom SPI providers at runtime.

Ensure these paths are writable inside the container.

Deploy Keycloak on Klutch.sh (Dockerfile workflow)

  1. Push your repository (with the Dockerfile at the root) to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  1. Connect the GitHub repository; Klutch.sh automatically detects the Dockerfile.
  2. Choose HTTP traffic for Keycloak.
  3. Set the internal port to 8080.
  4. Add the environment variables above (admin credentials, DB settings, hostname, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /opt/keycloak/data (and /opt/keycloak/providers if used), selecting sizes that fit your realm exports and themes.
  6. Deploy. Your Keycloak admin console will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

Sample admin API call

Obtain a token and list realms (replace placeholders and secure secrets):

Terminal window
export KEYCLOAK_URL=https://example-app.klutch.sh
export ADMIN_USER=admin
export ADMIN_PASS=change_me


TOKEN=$(curl -s -X POST "$KEYCLOAK_URL/realms/master/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=$ADMIN_USER" -d "password=$ADMIN_PASS" -d "grant_type=password" -d "client_id=admin-cli" \
  | jq -r .access_token)


curl -s -H "Authorization: Bearer $TOKEN" "$KEYCLOAK_URL/admin/realms" | jq .

Health checks and production tips

  • Enable health endpoints (KC_HEALTH_ENABLED=true) and probe /health via your reverse proxy.
  • Enforce HTTPS at the edge; forward HTTP to port 8080 internally.
  • Rotate admin credentials and DB passwords regularly; store them only in Klutch.sh secrets.
  • Monitor disk usage on /opt/keycloak/data and resize volumes before they fill.
  • Keep image tags pinned; upgrade intentionally alongside database migrations.

Keycloak on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and port 8080 configured, you can deliver secure identity and SSO without extra YAML or workflow overhead.