docker.recipes

Keycloak + PostgreSQL + Themes

advanced

Enterprise identity and access management.

Overview

Keycloak is an open-source identity and access management solution developed by Red Hat that provides enterprise-grade authentication and authorization services. Originally created in 2014, Keycloak has become the leading self-hosted alternative to commercial identity providers like Auth0 and Okta, offering single sign-on (SSO), identity brokering, user federation, and support for standard protocols including OAuth2, OpenID Connect, and SAML. Its comprehensive feature set includes multi-tenancy through realms, social login integration, LDAP/Active Directory federation, and fine-grained authorization policies. This stack combines Keycloak with PostgreSQL as the backend database and includes support for custom themes, creating a robust and scalable identity management platform. PostgreSQL provides enterprise-grade data persistence with ACID compliance, ensuring user credentials, session data, and configuration remain consistent even under high load. The themes volume enables complete customization of login pages, admin console styling, and user-facing interfaces to match corporate branding requirements. This combination delivers production-ready identity services that can handle thousands of concurrent users while maintaining data integrity. Enterprise architects, security teams, and organizations implementing microservices architectures should consider this stack when they need centralized authentication without vendor lock-in. The self-hosted nature provides complete control over user data and compliance requirements, while PostgreSQL's proven reliability makes it suitable for mission-critical identity services. Custom theme support makes this particularly valuable for customer-facing applications where brand consistency is essential, and the combination scales from small development teams to large enterprises managing multiple applications and user bases.

Key Features

  • Single Sign-On (SSO) with OAuth2, OpenID Connect, and SAML protocol support
  • PostgreSQL backend ensuring ACID-compliant storage for user credentials and sessions
  • Custom theme support with dedicated volume for login page and admin console branding
  • Identity brokering for social logins (Google, Facebook, GitHub) and enterprise providers
  • User federation with LDAP and Active Directory integration
  • Multi-tenant realm architecture for isolating different applications or organizations
  • Fine-grained authorization policies with role-based and attribute-based access control
  • Admin REST API for programmatic user management and configuration

Common Use Cases

  • 1Enterprise SSO implementation replacing legacy authentication systems across multiple applications
  • 2Microservices architecture requiring centralized JWT token validation and user management
  • 3Customer-facing applications needing branded login pages with social authentication options
  • 4B2B SaaS platforms requiring multi-tenant user isolation and custom identity provider integration
  • 5Legacy application modernization where existing LDAP/AD infrastructure must be preserved
  • 6Compliance-heavy environments requiring self-hosted identity management with audit trails
  • 7Development teams building multiple applications that need shared user authentication and authorization

Prerequisites

  • Minimum 1.5GB RAM available (1GB for Keycloak, 512MB for PostgreSQL)
  • Port 8080 available for Keycloak admin console and authentication endpoints
  • Basic understanding of OAuth2/OpenID Connect flows for application integration
  • Knowledge of PostgreSQL administration for backup and performance tuning
  • Familiarity with Keycloak realm concepts and user federation if integrating existing directories
  • Understanding of theme development using FreeMarker templates for custom branding

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  keycloak: 
3    image: quay.io/keycloak/keycloak:latest
4    command: start
5    environment: 
6      - KC_DB=postgres
7      - KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
8      - KC_DB_USERNAME=${POSTGRES_USER}
9      - KC_DB_PASSWORD=${POSTGRES_PASSWORD}
10      - KC_HOSTNAME=localhost
11      - KC_HOSTNAME_STRICT=false
12      - KC_HOSTNAME_STRICT_HTTPS=false
13      - KC_HTTP_ENABLED=true
14      - KC_PROXY=edge
15      - KEYCLOAK_ADMIN=${ADMIN_USER}
16      - KEYCLOAK_ADMIN_PASSWORD=${ADMIN_PASSWORD}
17    volumes: 
18      - keycloak-themes:/opt/keycloak/themes
19    ports: 
20      - "8080:8080"
21    depends_on: 
22      - postgres
23    networks: 
24      - keycloak-network
25    restart: unless-stopped
26
27  postgres: 
28    image: postgres:15
29    environment: 
30      - POSTGRES_USER=${POSTGRES_USER}
31      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
32      - POSTGRES_DB=keycloak
33    volumes: 
34      - postgres-data:/var/lib/postgresql/data
35    networks: 
36      - keycloak-network
37    restart: unless-stopped
38
39volumes: 
40  keycloak-themes: 
41  postgres-data: 
42
43networks: 
44  keycloak-network: 
45    driver: bridge

.env Template

.env
1# Keycloak
2POSTGRES_USER=keycloak
3POSTGRES_PASSWORD=secure_postgres_password
4ADMIN_USER=admin
5ADMIN_PASSWORD=secure_admin_password

Usage Notes

  1. 1Admin console at http://localhost:8080
  2. 2Create realms for apps
  3. 3OAuth2/OIDC and SAML
  4. 4LDAP federation
  5. 5Custom themes supported

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

keycloak
keycloak:
  image: quay.io/keycloak/keycloak:latest
  command: start
  environment:
    - KC_DB=postgres
    - KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
    - KC_DB_USERNAME=${POSTGRES_USER}
    - KC_DB_PASSWORD=${POSTGRES_PASSWORD}
    - KC_HOSTNAME=localhost
    - KC_HOSTNAME_STRICT=false
    - KC_HOSTNAME_STRICT_HTTPS=false
    - KC_HTTP_ENABLED=true
    - KC_PROXY=edge
    - KEYCLOAK_ADMIN=${ADMIN_USER}
    - KEYCLOAK_ADMIN_PASSWORD=${ADMIN_PASSWORD}
  volumes:
    - keycloak-themes:/opt/keycloak/themes
  ports:
    - "8080:8080"
  depends_on:
    - postgres
  networks:
    - keycloak-network
  restart: unless-stopped
postgres
postgres:
  image: postgres:15
  environment:
    - POSTGRES_USER=${POSTGRES_USER}
    - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    - POSTGRES_DB=keycloak
  volumes:
    - postgres-data:/var/lib/postgresql/data
  networks:
    - keycloak-network
  restart: unless-stopped

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  keycloak:
5    image: quay.io/keycloak/keycloak:latest
6    command: start
7    environment:
8      - KC_DB=postgres
9      - KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
10      - KC_DB_USERNAME=${POSTGRES_USER}
11      - KC_DB_PASSWORD=${POSTGRES_PASSWORD}
12      - KC_HOSTNAME=localhost
13      - KC_HOSTNAME_STRICT=false
14      - KC_HOSTNAME_STRICT_HTTPS=false
15      - KC_HTTP_ENABLED=true
16      - KC_PROXY=edge
17      - KEYCLOAK_ADMIN=${ADMIN_USER}
18      - KEYCLOAK_ADMIN_PASSWORD=${ADMIN_PASSWORD}
19    volumes:
20      - keycloak-themes:/opt/keycloak/themes
21    ports:
22      - "8080:8080"
23    depends_on:
24      - postgres
25    networks:
26      - keycloak-network
27    restart: unless-stopped
28
29  postgres:
30    image: postgres:15
31    environment:
32      - POSTGRES_USER=${POSTGRES_USER}
33      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
34      - POSTGRES_DB=keycloak
35    volumes:
36      - postgres-data:/var/lib/postgresql/data
37    networks:
38      - keycloak-network
39    restart: unless-stopped
40
41volumes:
42  keycloak-themes:
43  postgres-data:
44
45networks:
46  keycloak-network:
47    driver: bridge
48EOF
49
50# 2. Create the .env file
51cat > .env << 'EOF'
52# Keycloak
53POSTGRES_USER=keycloak
54POSTGRES_PASSWORD=secure_postgres_password
55ADMIN_USER=admin
56ADMIN_PASSWORD=secure_admin_password
57EOF
58
59# 3. Start the services
60docker compose up -d
61
62# 4. View logs
63docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/keycloak-complete/run | bash

Troubleshooting

  • Keycloak fails to start with database connection errors: Verify PostgreSQL container is healthy and POSTGRES_USER/POSTGRES_PASSWORD environment variables match between services
  • Admin console shows 'Invalid redirect URI' errors: Add your application's callback URLs to the client configuration in the Keycloak admin console under Client Settings
  • Custom themes not appearing in Keycloak: Ensure theme files are placed in correct directory structure within the keycloak-themes volume and restart the Keycloak container
  • PostgreSQL connection pool exhaustion under load: Increase KC_DB_POOL_MAX_SIZE environment variable and tune PostgreSQL max_connections setting
  • LDAP user federation sync failures: Check LDAP connection settings in Keycloak admin console and verify bind DN has sufficient privileges to read user attributes
  • Token validation errors in applications: Confirm application is using correct realm endpoint URL and client secret, check Keycloak logs for specific JWT validation failures

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

keycloakpostgresql

Tags

#keycloak#sso#identity#oauth2#saml#enterprise

Category

Security & Networking

Related Recipes

Ad Space