Uncategorized

Posted on October 11, 2025December 6, 2025 | by Abhishek Singh

Here’s a clean, copy-paste Production Runbook for your current setup (Ubuntu + LAMPP/Apache reverse proxy + Keycloak in /opt/auth.holidaylandmark.com), making sure it starts on boot, auto-recovers, and serves reliably over https://auth.holidaylandmark.com/.

I’ve included all steps end-to-end: prerequisites, config edits, Apache modules, WebSocket support, systemd service, verification, and common fixes.

Keycloak @ `auth.holidaylandmark.com` — Production Runbook

0) Prerequisites (one-time)

# Update system packages
sudo apt update

# Ensure Java 17+ is available (Temurin/OpenJDK). Example for OpenJDK 17:
sudo apt install -y openjdk-17-jre

# Confirm Java
java -version

Keycloak 22+ requires Java 17+. Keep using your existing LAMPP (XAMPP on Linux) for Apache/SSL.

1) Create service user and permissions (one-time)

# Create a dedicated OS user for Keycloak
sudo useradd --system --user-group --home /opt/auth.holidaylandmark.com keycloak

# Give ownership of the Keycloak directory
sudo chown -R keycloak:keycloak /opt/auth.holidaylandmark.com

2) Configure Keycloak (`keycloak.conf`)

Edit: /opt/auth.holidaylandmark.com/conf/keycloak.conf
Use these values (replace credentials if needed):

# ===============================
# Keycloak Production Config (Apache TLS termination)
# Hostname: auth.holidaylandmark.com
# ===============================

# --- Database (MariaDB/MySQL over local socket) ---
db=mariadb
db-url=jdbc:mariadb://localhost:3306/keycloak_db?localSocket=/opt/lampp/var/mysql/mysql.sock
db-username=REPLACE_ME_USER
db-password=REPLACE_ME_PASSWORD

# Pooling (tune with your RAM/traffic)
db-pool-initial-size=5
db-pool-min-idle=5
db-pool-max-size=25
db-pool-prefill=true

# --- HTTP / Proxy (Apache terminates TLS) ---
http-enabled=true
http-port=8080
proxy=edge                 # IMPORTANT: TLS ends at Apache
proxy-headers=xforwarded   # Trust X-Forwarded-*

# --- Hostname ---
hostname=auth.holidaylandmark.com
hostname-strict=true
hostname-strict-backchannel=false  # Avoid 400s on internal callbacks

# If Keycloak is NOT mounted under /auth, leave this commented
# http-relative-path=/auth

# --- Cache / Health / Metrics / Logging ---
cache=local
health-enabled=true
metrics-enabled=true
log-level=INFO
hostname-debug=false

Why proxy=edge? You terminate TLS at Apache and proxy to KC over HTTP:8080. This mode ensures correct URL building and cookie handling.

3) Apache (LAMPP) — enable required modules

Open /opt/lampp/etc/httpd.conf and ensure these lines are present (uncomment/add if needed):

LoadModule headers_module        modules/mod_headers.so
LoadModule proxy_module          modules/mod_proxy.so
LoadModule proxy_http_module     modules/mod_proxy_http.so
LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so
LoadModule ssl_module            modules/mod_ssl.so
LoadModule rewrite_module        modules/mod_rewrite.so

Restart Apache:

sudo /opt/lampp/lampp restart

4) Apache vhosts for `auth.holidaylandmark.com`

:80 → :443 redirect (keep as is)

/opt/lampp/etc/extra/httpd-vhosts.conf or wherever you keep vhosts:

<VirtualHost *:80>
    ServerName auth.holidaylandmark.com
    Redirect permanent / https://auth.holidaylandmark.com/
</VirtualHost>

:443 reverse proxy to Keycloak (with WebSocket support)

Edit your SSL vhost (you showed /opt/lampp/etc/extra/httpd-ssl.conf). Replace backend IP with 127.0.0.1 if Keycloak is on the same host (recommended):

<VirtualHost *:443>
    ServerName auth.holidaylandmark.com

    SSLEngine on
    SSLCertificateFile      /opt/lampp/etc/certs/auth.holidaylandmark.com/auth.holidaylandmark.com.cer
    SSLCertificateKeyFile   /opt/lampp/etc/certs/auth.holidaylandmark.com/auth.holidaylandmark.com.key
    SSLCACertificateFile    /opt/lampp/etc/certs/auth.holidaylandmark.com/fullchain.cer

    ErrorLog  "/opt/lampp/logs/auth.holidaylandmark.com_error_log_"

    # Security hardening
    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"

    ProxyPreserveHost On
    ProxyRequests Off

    # --- Prefer loopback if KC is on same box ---
    # If it's truly remote, replace 127.0.0.1 with that host/IP.
    ProxyPass        / http://127.0.0.1:8080/ retry=0
    ProxyPassReverse / http://127.0.0.1:8080/

    # Fix cookies if Keycloak sets cookie domain = backend host
    ProxyPassReverseCookieDomain 127.0.0.1 auth.holidaylandmark.com

    # Pass original scheme/host/port to Keycloak
    RequestHeader set X-Forwarded-Proto "https"
    RequestHeader set X-Forwarded-Host  "auth.holidaylandmark.com"
    RequestHeader set X-Forwarded-Port  "443"

    # --- WebSocket upgrade for admin console ---
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} =websocket [NC]
    RewriteRule /(.*) ws://127.0.0.1:8080/$1 [P,L]

    ProxyTimeout 120
</VirtualHost>

Restart Apache:

sudo /opt/lampp/lampp restart

If you must keep a public IP backend instead of 127.0.0.1, use it consistently in ProxyPass, ProxyPassReverse, ProxyPassReverseCookieDomain, and the WebSocket RewriteRule.

5) First-time admin bootstrap (only if you don’t have admin)

Choose one method:

A. One-shot start with env vars:

export KC_BOOTSTRAP_ADMIN_USERNAME=admin
export KC_BOOTSTRAP_ADMIN_PASSWORD='Str0ngP@ss!'
sudo -u keycloak /opt/auth.holidaylandmark.com/bin/kc.sh start --optimized
# After confirming admin login works, Ctrl+C to stop (we’ll run as a service next).

B. Bootstrap command (preferred on newer KC):

export KC_BOOTSTRAP_ADMIN_PASSWORD='Str0ngP@ss!'
sudo -u keycloak /opt/auth.holidaylandmark.com/bin/kc.sh bootstrap-admin user \
  --username admin --password:env KC_BOOTSTRAP_ADMIN_PASSWORD

6) (Optional) Build/optimize Keycloak once

sudo -u keycloak /opt/auth.holidaylandmark.com/bin/kc.sh build

This precompiles/optimizes extensions and reduces start time.

7) Create a systemd service (always-on)

Create /etc/systemd/system/keycloak.service:

[Unit]
Description=Keycloak (auth.holidaylandmark.com)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=keycloak
Group=keycloak
WorkingDirectory=/opt/auth.holidaylandmark.com
Environment=JAVA_OPTS=-Xms512m -Xmx2048m
ExecStart=/opt/auth.holidaylandmark.com/bin/kc.sh start --optimized
ExecStop=/bin/kill -TERM $MAINPID
Restart=on-failure
RestartSec=5
TimeoutStartSec=120
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

Enable and start:

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

From now on, Keycloak will start on boot and auto-restart on failure.

8) Firewall (if UFW is enabled)

You’re serving through Apache only:

sudo ufw allow 'Apache Full'
sudo ufw status

9) Verification Checklist

Service running systemctl is-active keycloak # should print: active journalctl -u keycloak -f # tail logs; no errors
Port check (local) ss -lntp | grep 8080 # Keycloak listening on 0.0.0.0:8080 ss -lntp | grep ':443 ' # Apache listening on :443
Browser tests
- Open https://auth.holidaylandmark.com/
- Admin console loads without infinite redirects
- Open page source on login: form/action URLs use https://auth.holidaylandmark.com/ (not 127.0.0.1:8080)
If 400/hostname errors
- Confirm hostname=auth.holidaylandmark.com
- Ensure proxy=edge and proxy-headers=xforwarded
- Keep hostname-strict=true and hostname-strict-backchannel=false (as in the config)
Admin console save/test errors
- Almost always WebSocket/proxy misconfig: re-check Apache mod_proxy_wstunnel and the Upgrade rewrite block.

10) Maintenance Commands

# Watch logs
sudo journalctl -u keycloak -f

# Apply config changes
sudo systemctl restart keycloak

# Show effective config (useful for debugging)
sudo -u keycloak /opt/auth.holidaylandmark.com/bin/kc.sh show-config

# Apache logs
tail -f /opt/lampp/logs/error_log
tail -f /opt/lampp/logs/auth.holidaylandmark.com_error_log_

11) Common Pitfalls (and exact fixes)

Used proxy=reencrypt while Apache terminates TLS
➜ Set proxy=edge in keycloak.conf.
Missing WebSocket support (admin console issues)
➜ Enable mod_proxy_wstunnel and add: RewriteEngine On RewriteCond %{HTTP:Upgrade} =websocket [NC] RewriteRule /(.*) ws://127.0.0.1:8080/$1 [P,L]
Backchannel strictness causes 400 on internal calls
➜ hostname-strict-backchannel=false.
Proxying via public IP while both run on same host
➜ Prefer 127.0.0.1 for ProxyPass/ProxyPassReverse/ProxyPassReverseCookieDomain/WebSocket rule.
Wrong cookie domain in browser
➜ Ensure ProxyPassReverseCookieDomain 127.0.0.1 auth.holidaylandmark.com (or appropriate backend host).

12) Optional Hardening (later)

Move DB credentials to environment variables or secrets manager.
Set stricter JVM heap (-Xms, -Xmx) per RAM.
Consider switching to a managed MariaDB/MySQL or PostgreSQL instance for durability.

You’re done

With the above, Keycloak will (a) always run via systemd, (b) serve HTTPS through Apache with proper proxy/WebSocket handling, and (c) behave correctly with proxy=edge and your hostname settings.

Abhishek Singh

I’m Abhishek, a DevOps, SRE, DevSecOps, and Cloud expert with a passion for sharing knowledge and real-world experiences. I’ve had the opportunity to work with Cotocus and continue to contribute to multiple platforms where I share insights across different domains:

DevOps School – Tech blogs and tutorials
Holiday Landmark – Travel stories and guides
Stocks Mantra – Stock market strategies and tips
My Medic Plus – Health and fitness guidance
TrueReviewNow – Honest product reviews
Wizbrand – SEO and digital tools for businesses

I’m also exploring the fascinating world of Quantum Computing.

Best Cardiac Hospitals Near You

Discover top heart hospitals, cardiology centers & cardiac care services by city.

Advanced Heart Care • Trusted Hospitals • Expert Teams

View Best Hospitals

Best Cosmetic Hospitals Near You

Keycloak Production Deployment on Ubuntu + Apache (LAMPP)

Keycloak @ `auth.holidaylandmark.com` — Production Runbook

0) Prerequisites (one-time)

1) Create service user and permissions (one-time)

2) Configure Keycloak (`keycloak.conf`)

3) Apache (LAMPP) — enable required modules

4) Apache vhosts for `auth.holidaylandmark.com`

:80 → :443 redirect (keep as is)

:443 reverse proxy to Keycloak (with WebSocket support)

5) First-time admin bootstrap (only if you don’t have admin)

6) (Optional) Build/optimize Keycloak once

7) Create a systemd service (always-on)

8) Firewall (if UFW is enabled)

9) Verification Checklist

10) Maintenance Commands

11) Common Pitfalls (and exact fixes)

12) Optional Hardening (later)

You’re done

Best Cardiac Hospitals Near You

Best Cosmetic Hospitals Near You

Keycloak Production Deployment on Ubuntu + Apache (LAMPP)

Keycloak @ auth.holidaylandmark.com — Production Runbook

0) Prerequisites (one-time)

1) Create service user and permissions (one-time)

2) Configure Keycloak (keycloak.conf)

3) Apache (LAMPP) — enable required modules

4) Apache vhosts for auth.holidaylandmark.com

:80 → :443 redirect (keep as is)

:443 reverse proxy to Keycloak (with WebSocket support)

5) First-time admin bootstrap (only if you don’t have admin)

6) (Optional) Build/optimize Keycloak once

7) Create a systemd service (always-on)

8) Firewall (if UFW is enabled)

9) Verification Checklist

10) Maintenance Commands

11) Common Pitfalls (and exact fixes)

12) Optional Hardening (later)

You’re done

Best Cardiac Hospitals Near You

Keycloak @ `auth.holidaylandmark.com` — Production Runbook

2) Configure Keycloak (`keycloak.conf`)

4) Apache vhosts for `auth.holidaylandmark.com`