Deployment Overview of Keycloak on Server¶

Prerequisites and Basic Requirements¶

To ensure a successful deployment, the following requirements must be met by the host server:

Operating System: Ubuntu
Privileges: Root or sudo access is required for package installation and directory management.
Docker: Docker engine must be installed to run the application containers.
Ports:
8080: Internal application port (restricted to localhost).
443: External HTTPS port for web traffic.

FQDN of the final panel on the hostkey.in domain¶

The application is accessible via a specific Fully Qualified Domain Name (FQDN) based on the server ID. The template for this domain is provided below:

Parameter	Value
Prefix	`keycloak`
Domain	`hostkey.in`
Full template	`keycloak{Server_ID}.hostkey.in`

File and Directory Structure¶

The deployment utilizes the following directory structure for configuration and data persistence:

/opt/keycloak: Main application directory containing orchestration files.
/root/nginx: Configuration directory for the Nginx reverse proxy.
/data/nginx/user_conf.d: Storage location for Nginx site configurations.
/data/nginx/nginx-certbot.env: Environment file for the SSL management container.

Application installation process¶

The application is deployed using a combination of Docker Compose and manual configuration steps:

Environment Setup: The directory /opt/keycloak is created with restricted permissions (0750).
Orchestration Configuration: A keycloak-compose.yml file is generated in the installation directory to define the application services.
Image Retrieval: The required Docker images are pulled from their respective registries.
Container Deployment: The application containers are started using Docker Compose.
Proxy Setup: An Nginx container is deployed via a separate compose file located in /root/nginx to handle SSL termination and reverse proxying.

Access Rights and Security¶

Firewall: Only the standard web ports (443) should be exposed to the public internet. The application port 8080 is bound specifically to 127.0.0.1 to prevent direct external access.
Permissions: Configuration files in /opt/keycloak are set with restricted permissions (0640) to protect sensitive data.
Proxy Security: Nginx is configured to pass necessary headers (e.g., X-Forwarded-Proto, X-Forwarded-Port) to ensure the application correctly identifies secure connections.

Databases¶

The application uses a PostgreSQL database for persistent storage of Keycloak data.

Component	Detail
Database Engine	`postgres:16`
Database Name	`keycloak`
Username	`keycloak`
Hostname	`keycloak_postgres` (internal Docker network)
Storage Location	Managed via Docker volume `postgres_data`

Docker Containers and Their Deployment¶

The deployment consists of three primary containers:

Keycloak Application Container¶

Image: quay.io/keycloak/keycloak:latest
Container Name: keycloak{Server_ID}.hostkey.in
Ports: 127.0.0.1:8080:8080
Restart Policy: always
Environment Variables:
KC_BOOTSTRAP_ADMIN_USERNAME: root
KC_BOOTSTRAP_ADMIN_PASSWORD: (System generated)
KC_HTTP_ENABLED: true
KC_HOSTNAME: {FQDN}
KC_HOSTNAME_STRICT_HTTPS: false
KC_PROXY_HEADERS: xforwarded
KC_DB: postgres
KC_DB_URL: jdbc:postgresql://keycloak_postgres:5432/keycloak

PostgreSQL Database Container¶

Image: postgres:16
Container Name: keycloak_postgres
Restart Policy: always
Environment Variables:
POSTGRES_DB: keycloak
POSTGRES_USER: keycloak
POSTGRES_PASSWORD: keycloak

Nginx Reverse Proxy Container¶

Image: jonasal/nginx-certbot:latest
Network Mode: host
Restart Policy: unless-stopped
Volumes:
nginx_secrets:/etc/letsencrypt
/data/nginx/user_conf.d:/etc/nginx/user_conf.d

Application Update Instructions¶

To update the Keycloak application, perform the following steps:

Navigate to the application directory:
```
cd /opt/keycloak
```

Pull the latest images and restart the services:

docker compose pull && docker compose up -d