# Keycloak - Open-source Identity and Access Management
# https://www.keycloak.org/
#
# DEPLOYMENT INSTRUCTIONS:
# 1. Create directory: mkdir -p ~/docker/keycloak
# 2. Copy this file: cp docker-compose-keycloak.yml ~/docker/keycloak/docker-compose.yml
# 3. IMPORTANT: Update KEYCLOAK_ADMIN_PASSWORD below!
# 4. Start the service: cd ~/docker/keycloak && docker compose up -d
# 5. Access at: http://localhost:8180/admin (admin console)
#
# REVERSE PROXY SETUP (with Caddy):
# Add to your Caddyfile:
#   auth.yourdomain.com {
#       reverse_proxy localhost:8180
#   }
#
# PRODUCTION DEPLOYMENT:
# For production, you should:
# 1. Use a PostgreSQL database (see postgres service below)
# 2. Enable HTTPS via reverse proxy
# 3. Set KC_HOSTNAME to your domain
# 4. Use strong admin password
# 5. Configure proper realm and clients

name: keycloak

services:
  # PostgreSQL database for Keycloak (recommended for production)
  postgres:
    image: postgres:16-alpine
    container_name: keycloak-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak_db_password_CHANGE_THIS
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U keycloak"]
      interval: 10s
      timeout: 5s
      retries: 5

  keycloak:
    image: quay.io/keycloak/keycloak:latest
    container_name: keycloak
    restart: unless-stopped
    command:
      - start-dev  # Use 'start' for production mode
    environment:
      # Admin credentials - CHANGE THESE!
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=CHANGE_THIS_SECURE_PASSWORD

      # Database configuration (PostgreSQL)
      - KC_DB=postgres
      - KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
      - KC_DB_USERNAME=keycloak
      - KC_DB_PASSWORD=keycloak_db_password_CHANGE_THIS

      # Hostname configuration
      # For production, set to your domain:
      # - KC_HOSTNAME=auth.yourdomain.com
      # - KC_HOSTNAME_STRICT=true
      - KC_HOSTNAME_STRICT=false

      # Proxy configuration (required when behind Caddy/nginx)
      - KC_PROXY=edge
      - KC_HTTP_ENABLED=true

      # Logging
      - KC_LOG_LEVEL=INFO

      # Health check
      - KC_HEALTH_ENABLED=true
      - KC_METRICS_ENABLED=true
    ports:
      - "8180:8080"  # HTTP port (use reverse proxy for HTTPS)
      # - "8787:8787"  # Debug port (uncomment if needed)
    volumes:
      # Optional: Custom themes
      # - ./themes:/opt/keycloak/themes
      # Optional: Custom providers/extensions
      # - ./providers:/opt/keycloak/providers
      - ./data:/opt/keycloak/data
    depends_on:
      postgres:
        condition: service_healthy
    labels:
      # Fail2ban support
      - "io.podman.annotations.label/fail2ban.enable=true"
      - "io.podman.annotations.label/fail2ban.filter=caddy-auth"

# NOTES:
# - Admin console: http://localhost:8180/admin
# - Default credentials: admin / CHANGE_THIS_SECURE_PASSWORD
# - Database: PostgreSQL (persistent data in ./postgres-data)
# - For H2 database (dev only), remove postgres service and database env vars
#
# FIRST-TIME SETUP:
# 1. Login to admin console
# 2. Create a realm (e.g., "myrealm")
# 3. Create clients for your applications
# 4. Configure authentication flows
# 5. Add users or configure identity providers (LDAP, SAML, OAuth)
#
# COMMON USE CASES:
# - Single Sign-On (SSO) for multiple applications
# - OAuth2/OIDC provider for custom apps
# - SAML 2.0 identity provider
# - User federation with LDAP/Active Directory
# - Multi-factor authentication (MFA/2FA)
# - Social login (Google, GitHub, etc.)
#
# PRODUCTION CHECKLIST:
# [ ] Change admin password
# [ ] Change database password
# [ ] Set KC_HOSTNAME to your domain
# [ ] Use 'start' instead of 'start-dev' command
# [ ] Configure HTTPS via reverse proxy (Caddy)
# [ ] Enable hostname strict mode
# [ ] Configure backup strategy for PostgreSQL
# [ ] Set up monitoring (metrics on port 9000)
#
# BACKUP:
#   docker compose down
#   tar -czf keycloak-backup-$(date +%Y%m%d).tar.gz postgres-data data
#   docker compose up -d
#
# RESTORE:
#   docker compose down
#   tar -xzf keycloak-backup-YYYYMMDD.tar.gz
#   docker compose up -d
#
# UPDATES:
#   docker compose pull
#   docker compose up -d
#
# DOCUMENTATION:
# - Official docs: https://www.keycloak.org/documentation
# - Getting started: https://www.keycloak.org/getting-started/getting-started-docker
# - Server admin: https://www.keycloak.org/docs/latest/server_admin/