1. Yêu cầu hệ thống

Trước khi cài đặt Keycloak 26.x, hãy đảm bảo hệ thống đáp ứng các yêu cầu sau:

• Java: JDK 17 hoặc 21 (khuyến nghị OpenJDK 21)

• Database: PostgreSQL 13-16 (khuyến nghị), MySQL 8.0+, MariaDB 10.6+

• RAM: Tối thiểu 512MB (khuyến nghị 2GB+ cho production)

• CPU: 1 core tối thiểu (khuyến nghị 2+ cores cho production)

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

2. Cài đặt trên Bare Metal (Ubuntu)

2.1. Cài đặt Java 21

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

2.2. Cài đặt 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. Tải và cài đặt 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. Tạo 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. Cài đặt với Docker và Docker Compose

3.1. Docker đơn giản (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. Cài đặt 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

Tiêu chí	Development (start-dev)	Production (start)
Database	H2 embedded (default)	PostgreSQL/MySQL (bắt buộc)
HTTPS	Không bắt buộc	Bắt buộc (hoặc proxy)
Hostname	localhost (auto)	Phải cấu hình hostname
Cache	Local cache	Distributed cache (Infinispan)
Theme cache	Disabled (hot reload)	Enabled
Build	Không cần build trước	Nên chạy kc.sh build trước

6. Cấu hình 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. Cấu hình 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. Tạo 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