# 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. Create .env file with credentials (see .env template below)
# 4. Start the service: cd ~/docker/keycloak && docker compose up -d
# 5. Access at: http://localhost:8180/admin (admin console)
#
# .ENV FILE TEMPLATE:
# Create a file named .env in ~/docker/keycloak/ with:
#   KEYCLOAK_ADMIN=admin
#   KEYCLOAK_ADMIN_PASSWORD=<your-secure-password>
#   POSTGRES_DB=keycloak
#   POSTGRES_USER=keycloak
#   POSTGRES_PASSWORD=<your-db-password>
#   KC_DB=postgres
#   KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
#   KC_DB_USERNAME=keycloak
#   KC_DB_PASSWORD=<your-db-password>
#   KC_PROXY_HEADERS=xforwarded
#   KC_HTTP_ENABLED=true
#   KC_HOSTNAME_STRICT=false
#   KC_LOG_LEVEL=INFO
#   KC_HEALTH_ENABLED=true
#   KC_METRICS_ENABLED=true
#   # KC_HOSTNAME=auth.yourdomain.com  # Uncomment for production
#
# 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
    env_file:
      - .env
    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
    env_file:
      - .env
    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
# - Credentials: Stored in .env file
# - Database: PostgreSQL (persistent data in ./postgres-data)
# - Proxy: Uses KC_PROXY_HEADERS=xforwarded (v2 config, no deprecated warnings)
#
# FIRST-TIME SETUP:
# 1. Create .env file with secure passwords (see template above)
# 2. Start containers: docker compose up -d
# 3. Login to admin console at http://localhost:8180/admin
# 4. Create a realm (e.g., "homelab" or "myrealm")
# 5. Create clients for your applications (OAuth2/OIDC)
# 6. Add users or configure identity providers (LDAP, SAML, Social)
#
# COMMON USE CASES:
# - Single Sign-On (SSO) for multiple applications
# - OAuth2/OIDC provider for custom apps (ActualBudget, etc.)
# - SAML 2.0 identity provider
# - User federation with LDAP/Active Directory
# - Multi-factor authentication (MFA/2FA)
# - Social login (Google, GitHub, Facebook, etc.)
#
# PRODUCTION CHECKLIST:
# [ ] Create .env file with secure passwords (12+ chars, alphanumeric only)
# [ ] Set KC_HOSTNAME in .env to your domain (e.g., auth.yourdomain.com)
# [ ] Use 'start' instead of 'start-dev' command in docker-compose.yml
# [ ] Configure HTTPS via reverse proxy (Caddy/nginx)
# [ ] Set KC_HOSTNAME_STRICT=true in .env for production
# [ ] Configure DNS A record for your hostname
# [ ] Set proper file permissions: chmod 600 .env
# [ ] Configure backup strategy for PostgreSQL
# [ ] Set up monitoring (metrics enabled via KC_METRICS_ENABLED=true)
#
# 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/