Deploy Keycloak via Docker Compose: Step-by-Step SSO Setup

Environment Preparation Checklist

Operating System: CentOS 7.9 (recommended)

Docker: 26.1.4

Docker Compose: v2.34.0

Keycloak: quay.io/keycloak/keycloak:latest, port 18080, no config file (environment variables), optional persistent storage (dev mode)

Detailed Deployment Steps

1. Create Working Directory

mkdir -p /data/keycloak
cd /data/keycloak

2. Write Docker Compose File

cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    container_name: keycloak
    restart: unless-stopped
    command: start-dev
    environment:
      - KC_BOOTSTRAP_ADMIN_USERNAME=admin
      - KC_BOOTSTRAP_ADMIN_PASSWORD=Admin@123456
      - TZ=Asia/Shanghai
    ports:
      - "18080:8080"
EOF

3. Start Keycloak Service

# Start service in background
docker compose up -d

# Check container status
docker inspect -f '{{.State.Running}}' keycloak

4. Service Verification

Access Console : Open http://SERVER_IP:18080 Login to Admin Console : Username: admin, Password: Admin@123456 Health Check (Optional) : Run

curl http://127.0.0.1:18080

Key Configuration Details

Startup Command : start-dev is the official recommended development/testing mode; simple to start but not recommended for production.

Admin Initialization : Uses KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD to initialize the admin user.

Port Mapping : Host uses 18080 to avoid conflicts with other services on 8080.

Common Issues

Container Keeps Restarting

Check if command: start-dev was accidentally removed, or if there is a port conflict.

Slow First Launch

Keycloak initializes components on first startup, typically taking tens of seconds to several minutes.

Can This Configuration Be Used Directly in Production?

Not recommended. For production, use start mode and configure HTTPS, external database, and hostname.

Following these steps, you can deploy a local Keycloak authentication service in 5 minutes, facilitating SSO/OIDC integration testing.