Production-ready Docker Compose configurations for Keycloak 26.x with PostgreSQL, reverse proxy, clustering, monitoring, and security hardening.
Full tutorial: Keycloak Docker Compose Production: Complete Deployment Guide
# Clone
git clone https://github.com/IAMDevBox/keycloak-docker-production.git
cd keycloak-docker-production
# Configure
cp .env.example .env
# Edit .env with your passwords and hostname
# Single node
docker compose up -d
# Clustered (2 nodes + Nginx)
docker compose -f docker-compose.cluster.yml up -d| File | Description |
|---|---|
docker-compose.yml |
Single-node production setup |
docker-compose.cluster.yml |
2-node HA cluster with Nginx load balancer |
Dockerfile |
Optimized build for faster startup (~10s vs ~30s) |
nginx/keycloak.conf |
Nginx reverse proxy with TLS, admin restriction, path filtering |
.env.example |
Environment variable template |
- PostgreSQL tuned for Keycloak workload (shared_buffers, work_mem, connection limits)
- Connection pool sized per Keycloak docs (initial = min = max for best performance)
- Health checks on both PostgreSQL and Keycloak (port 9000 management interface)
- Network isolation — database on internal-only network
- Resource limits — memory and CPU caps to prevent noisy neighbor issues
- Security hardening — unused features disabled, admin endpoint restricted
- Load shedding —
KC_HTTP_MAX_QUEUED_REQUESTSprevents cascade failures - JSON logging — structured output for log aggregation (ELK, Loki, etc.)
- JDBC_PING2 clustering — no multicast, no external discovery service needed
The included Nginx config restricts public access to only:
/realms/— OIDC/SAML endpoints/resources/— Static assets (cached 1 year)/.well-known/— OIDC discovery
Admin console (/admin/) is restricted to internal IPs. Health and metrics endpoints are blocked.
For Traefik or Caddy configurations, see the full tutorial.
- Keycloak Docker Compose Production Guide — Full walkthrough with explanations
- Keycloak High Availability: Clustering Guide — Clustering concepts and strategies
- Keycloak Complete Guide — Comprehensive Keycloak overview
- Keycloak Session Troubleshooting — Session timeout configuration
MIT