1. System requirements

Before installing Keycloak 26.x, make sure the system meets the following requirements:

• Java: JDK 17 or 21 (OpenJDK 21 recommended)

• Database: PostgreSQL 13-16 (recommended), MySQL 8.0+, MariaDB 10.6+

• RAM: Minimum 512MB (recommended 2GB+ for production)

• CPU: Minimum 1 core (recommended 2+ cores for production)

• OS: Linux (Ubuntu 22.04/24.04, CentOS 9, RHEL 9), macOS, Windows

2. Install on Bare Metal (Ubuntu)

2.1. Install Java 21

sudo apt update
sudo apt install -y openjdk-21-jdk
java -version

2.2. Install PostgreSQL

sudo apt install -y postgresql postgresql-contrib
sudo systemctl enable postgresql
sudo systemctl start postgresql
Tạo database và user cho Keycloak
sudo -u postgres psql -c "CREATE USER keycloak WITH PASSWORD 'keycloak_password';"
sudo -u postgres psql -c "CREATE DATABASE keycloak OWNER keycloak;"

2.3. Download and install Keycloak

# Tải Keycloak 26.5.x
cd /opt
wget https://github.com/keycloak/keycloak/releases/download/26.5.6/keycloak-26.5.6.tar.gz
tar -xzf keycloak-26.5.6.tar.gz
ln -s keycloak-26.5.6 keycloak
Cấu hình database
cat > /opt/keycloak/conf/keycloak.conf << 'EOF'
Database
db=postgres
db-url-host=localhost
db-url-port=5432
db-url-database=keycloak
db-username=keycloak
db-password=keycloak_password
Hostname
hostname=keycloak.example.com
HTTP
http-enabled=true
http-port=8080
EOF
Chạy development mode
/opt/keycloak/bin/kc.sh start-dev

2.4. Create Admin User

# Tạo admin user khi start
KEYCLOAK_ADMIN=admin KEYCLOAK_ADMIN_PASSWORD=admin \
  /opt/keycloak/bin/kc.sh start-dev
Hoặc dùng lệnh bootstrap
/opt/keycloak/bin/kc.sh bootstrap-admin user 

--username admin --password admin

3. Install with Docker and Docker Compose

3.1. Simple Docker (Development)

docker run -d --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.5.6 \
  start-dev

3.2. Docker Compose (Production-ready)

# docker-compose.yml
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - keycloak-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U keycloak"]
      interval: 10s
      timeout: 5s
      retries: 5
keycloak:
image: quay.io/keycloak/keycloak:26.5.6
command: start
environment:
KC_DB: postgres
KC_DB_URL_HOST: postgres
KC_DB_URL_PORT: "5432"
KC_DB_URL_DATABASE: keycloak
KC_DB_USERNAME: keycloak
KC_DB_PASSWORD: keycloak_password
KC_HOSTNAME: keycloak.example.com
KC_PROXY_HEADERS: xforwarded
KC_HTTP_ENABLED: "true"
KEYCLOAK_ADMIN: admin
KEYCLOAK_ADMIN_PASSWORD: admin
ports:
- "8080:8080"
depends_on:
postgres:
condition: service_healthy
networks:
- keycloak-network
volumes:
postgres_data:
networks:
keycloak-network:

4. Kubernetes Operator Deployment

4.1. Install Keycloak Operator

# Cài đặt Operator qua OperatorHub hoặc manifests
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.5.6/kubernetes/keycloaks.k8s.keycloak.org-v1.yml
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.5.6/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.yml
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.5.6/kubernetes/kubernetes.yml

4.2. Keycloak Custom Resource

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: keycloak
spec:
  instances: 2
  db:
    vendor: postgres
    host: postgres-service
    usernameSecret:
      name: keycloak-db-secret
      key: username
    passwordSecret:
      name: keycloak-db-secret
      key: password
  hostname:
    hostname: keycloak.example.com
  http:
    httpEnabled: true
  proxy:
    headers: xforwarded
  truststores:
    my-truststore:
      secret:
        name: my-truststore-secret

5. Development Mode vs Production Mode

Criteria	Development (start-dev)	Production (start)
Database	H2 embedded (default)	PostgreSQL/MySQL (required)
HTTPS	Optional	Required (or proxy)
Hostname	localhost (auto)	Must configure hostname
Cache	Local cache	Distributed cache (Infinispan)
Theme cache	Disabled (hot reload)	Enabled
Build	No need to build first	Should run kc.sh build first

6. Configure HTTPS/TLS

# Tạo keystore với self-signed certificate
keytool -genkeypair -storepass password -storetype PKCS12 \
  -keyalg RSA -keysize 2048 -dname "CN=keycloak.example.com" \
  -alias server -ext "SAN:c=DNS:keycloak.example.com" \
  -keystore /opt/keycloak/conf/server.keystore
Cấu hình trong keycloak.conf
https-certificate-file=/path/to/cert.pem
https-certificate-key-file=/path/to/key.pem
Hoặc
https-key-store-file=/opt/keycloak/conf/server.keystore
https-key-store-password=password

7. Configuring Reverse Proxy (Nginx)

upstream keycloak {
    server 127.0.0.1:8080;
}
server {
listen 443 ssl http2;
server_name keycloak.example.com;
ssl_certificate /etc/nginx/ssl/cert.pem;
ssl_certificate_key /etc/nginx/ssl/key.pem;

location / {
    proxy_pass http://keycloak;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;
}

}

8. Create Systemd Service

# /etc/systemd/system/keycloak.service
[Unit]
Description=Keycloak Server
After=network.target postgresql.service
[Service]
Type=exec
User=keycloak
Group=keycloak
ExecStart=/opt/keycloak/bin/kc.sh start --optimized
ExecStop=/bin/kill -TERM $MAINPID
Restart=on-failure
RestartSec=10
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable keycloak
sudo systemctl start keycloak