{"id":3367,"date":"2025-10-11T05:59:18","date_gmt":"2025-10-11T05:59:18","guid":{"rendered":"https:\/\/www.devopsconsulting.in\/blog\/?p=3367"},"modified":"2025-12-06T05:17:12","modified_gmt":"2025-12-06T05:17:12","slug":"keycloak-production-deployment-on-ubuntu-apache-lampp","status":"publish","type":"post","link":"https:\/\/www.devopsconsulting.in\/blog\/keycloak-production-deployment-on-ubuntu-apache-lampp\/","title":{"rendered":"Keycloak Production Deployment on Ubuntu + Apache (LAMPP)"},"content":{"rendered":"\n

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

I\u2019ve included all steps end-to-end: prerequisites, config edits, Apache modules, WebSocket support, systemd service, verification, and common fixes.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n
\n\n\n\n

Keycloak @ auth.holidaylandmark.com<\/code> \u2014 Production Runbook<\/h1>\n\n\n\n

0) Prerequisites (one-time)<\/h2>\n\n\n\n
# Update system packages\nsudo apt update\n\n# Ensure Java 17+ is available (Temurin\/OpenJDK). Example for OpenJDK 17:\nsudo apt install -y openjdk-17-jre\n\n# Confirm Java\njava -version\n<\/code><\/pre>\n\n\n\n
\n
Keycloak 22+ requires Java 17+. Keep using your existing LAMPP (XAMPP on Linux) for Apache\/SSL.<\/p>\n<\/blockquote>\n\n\n\n
\n\n\n\n
1) Create service user and permissions (one-time)<\/h2>\n\n\n\n
# Create a dedicated OS user for Keycloak\nsudo useradd --system --user-group --home \/opt\/auth.holidaylandmark.com keycloak\n\n# Give ownership of the Keycloak directory\nsudo chown -R keycloak:keycloak \/opt\/auth.holidaylandmark.com\n<\/code><\/pre>\n\n\n\n
\n\n\n\n
2) Configure Keycloak (keycloak.conf<\/code>)<\/h2>\n\n\n\n
Edit: \/opt\/auth.holidaylandmark.com\/conf\/keycloak.conf<\/code>
Use these values (replace credentials if needed):<\/p>\n\n\n\n
# ===============================\n# Keycloak Production Config (Apache TLS termination)\n# Hostname: auth.holidaylandmark.com\n# ===============================\n\n# --- Database (MariaDB\/MySQL over local socket) ---\ndb=mariadb\ndb-url=jdbc:mariadb:\/\/localhost:3306\/keycloak_db?localSocket=\/opt\/lampp\/var\/mysql\/mysql.sock\ndb-username=REPLACE_ME_USER\ndb-password=REPLACE_ME_PASSWORD\n\n# Pooling (tune with your RAM\/traffic)\ndb-pool-initial-size=5\ndb-pool-min-idle=5\ndb-pool-max-size=25\ndb-pool-prefill=true\n\n# --- HTTP \/ Proxy (Apache terminates TLS) ---\nhttp-enabled=true\nhttp-port=8080\nproxy=edge                 # IMPORTANT: TLS ends at Apache\nproxy-headers=xforwarded   # Trust X-Forwarded-*\n\n# --- Hostname ---\nhostname=auth.holidaylandmark.com\nhostname-strict=true\nhostname-strict-backchannel=false  # Avoid 400s on internal callbacks\n\n# If Keycloak is NOT mounted under \/auth, leave this commented\n# http-relative-path=\/auth\n\n# --- Cache \/ Health \/ Metrics \/ Logging ---\ncache=local\nhealth-enabled=true\nmetrics-enabled=true\nlog-level=INFO\nhostname-debug=false\n<\/code><\/pre>\n\n\n\n
\n
Why proxy=edge<\/code>?<\/strong> You terminate TLS at Apache and proxy to KC over HTTP:8080. This mode ensures correct URL building and cookie handling.<\/p>\n<\/blockquote>\n\n\n\n
\n\n\n\n
3) Apache (LAMPP) \u2014 enable required modules<\/h2>\n\n\n\n
Open \/opt\/lampp\/etc\/httpd.conf<\/code> and ensure these lines are present (uncomment\/add if needed):<\/p>\n\n\n\n
LoadModule headers_module        modules\/mod_headers.so\nLoadModule proxy_module          modules\/mod_proxy.so\nLoadModule proxy_http_module     modules\/mod_proxy_http.so\nLoadModule proxy_wstunnel_module modules\/mod_proxy_wstunnel.so\nLoadModule ssl_module            modules\/mod_ssl.so\nLoadModule rewrite_module        modules\/mod_rewrite.so\n<\/code><\/pre>\n\n\n\n
Restart Apache:<\/p>\n\n\n\n
sudo \/opt\/lampp\/lampp restart\n<\/code><\/pre>\n\n\n\n
\n\n\n\n
4) Apache vhosts for auth.holidaylandmark.com<\/code><\/h2>\n\n\n\n
:80 \u2192 :443 redirect (keep as is)<\/h3>\n\n\n\n
\/opt\/lampp\/etc\/extra\/httpd-vhosts.conf<\/code> or wherever you keep vhosts:<\/p>\n\n\n\n
<VirtualHost *:80>\n    ServerName auth.holidaylandmark.com\n    Redirect permanent \/ https:\/\/auth.holidaylandmark.com\/\n<\/VirtualHost>\n<\/code><\/pre>\n\n\n\n
:443 reverse proxy to Keycloak (with WebSocket support)<\/h3>\n\n\n\n
Edit your SSL vhost (you showed \/opt\/lampp\/etc\/extra\/httpd-ssl.conf<\/code>). Replace backend IP<\/strong> with 127.0.0.1<\/strong> if Keycloak is on the same host (recommended):<\/p>\n\n\n\n
<VirtualHost *:443>\n    ServerName auth.holidaylandmark.com\n\n    SSLEngine on\n    SSLCertificateFile      \/opt\/lampp\/etc\/certs\/auth.holidaylandmark.com\/auth.holidaylandmark.com.cer\n    SSLCertificateKeyFile   \/opt\/lampp\/etc\/certs\/auth.holidaylandmark.com\/auth.holidaylandmark.com.key\n    SSLCACertificateFile    \/opt\/lampp\/etc\/certs\/auth.holidaylandmark.com\/fullchain.cer\n\n    ErrorLog  \"\/opt\/lampp\/logs\/auth.holidaylandmark.com_error_log_\"\n\n    # Security hardening\n    Header always set Strict-Transport-Security \"max-age=31536000; includeSubDomains; preload\"\n\n    ProxyPreserveHost On\n    ProxyRequests Off\n\n    # --- Prefer loopback if KC is on same box ---\n    # If it's truly remote, replace 127.0.0.1 with that host\/IP.\n    ProxyPass        \/ http:\/\/127.0.0.1:8080\/ retry=0\n    ProxyPassReverse \/ http:\/\/127.0.0.1:8080\/\n\n    # Fix cookies if Keycloak sets cookie domain = backend host\n    ProxyPassReverseCookieDomain 127.0.0.1 auth.holidaylandmark.com\n\n    # Pass original scheme\/host\/port to Keycloak\n    RequestHeader set X-Forwarded-Proto \"https\"\n    RequestHeader set X-Forwarded-Host  \"auth.holidaylandmark.com\"\n    RequestHeader set X-Forwarded-Port  \"443\"\n\n    # --- WebSocket upgrade for admin console ---\n    RewriteEngine On\n    RewriteCond %{HTTP:Upgrade} =websocket [NC]\n    RewriteRule \/(.*) ws:\/\/127.0.0.1:8080\/$1 [P,L]\n\n    ProxyTimeout 120\n<\/VirtualHost>\n<\/code><\/pre>\n\n\n\n
Restart Apache:<\/p>\n\n\n\n
sudo \/opt\/lampp\/lampp restart\n<\/code><\/pre>\n\n\n\n
\n
If you must keep a public IP<\/strong> backend instead of 127.0.0.1, use it consistently in ProxyPass<\/code>, ProxyPassReverse<\/code>, ProxyPassReverseCookieDomain<\/code>, and the WebSocket RewriteRule<\/code>.<\/p>\n<\/blockquote>\n\n\n\n
\n\n\n\n
5) First-time admin bootstrap (only if you don\u2019t have admin)<\/h2>\n\n\n\n
Choose one<\/strong> method:<\/p>\n\n\n\n
A. One-shot start with env vars:<\/strong><\/p>\n\n\n\n
export KC_BOOTSTRAP_ADMIN_USERNAME=admin\nexport KC_BOOTSTRAP_ADMIN_PASSWORD='Str0ngP@ss!'\nsudo -u keycloak \/opt\/auth.holidaylandmark.com\/bin\/kc.sh start --optimized\n# After confirming admin login works, Ctrl+C to stop (we\u2019ll run as a service next).\n<\/code><\/pre>\n\n\n\n
B. Bootstrap command (preferred on newer KC):<\/strong><\/p>\n\n\n\n
export KC_BOOTSTRAP_ADMIN_PASSWORD='Str0ngP@ss!'\nsudo -u keycloak \/opt\/auth.holidaylandmark.com\/bin\/kc.sh bootstrap-admin user \\\n  --username admin --password:env KC_BOOTSTRAP_ADMIN_PASSWORD\n<\/code><\/pre>\n\n\n\n
\n\n\n\n
6) (Optional) Build\/optimize Keycloak once<\/h2>\n\n\n\n
sudo -u keycloak \/opt\/auth.holidaylandmark.com\/bin\/kc.sh build\n<\/code><\/pre>\n\n\n\n
This precompiles\/optimizes extensions and reduces start time.<\/p>\n\n\n\n
\n\n\n\n
7) Create a systemd service (always-on)<\/h2>\n\n\n\n
Create \/etc\/systemd\/system\/keycloak.service<\/code>:<\/p>\n\n\n\n
[Unit]\nDescription=Keycloak (auth.holidaylandmark.com)\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=simple\nUser=keycloak\nGroup=keycloak\nWorkingDirectory=\/opt\/auth.holidaylandmark.com\nEnvironment=JAVA_OPTS=-Xms512m -Xmx2048m\nExecStart=\/opt\/auth.holidaylandmark.com\/bin\/kc.sh start --optimized\nExecStop=\/bin\/kill -TERM $MAINPID\nRestart=on-failure\nRestartSec=5\nTimeoutStartSec=120\nLimitNOFILE=65535\n\n[Install]\nWantedBy=multi-user.target\n<\/code><\/pre>\n\n\n\n
Enable and start:<\/p>\n\n\n\n
sudo systemctl daemon-reload\nsudo systemctl enable --now keycloak\nsudo systemctl start keycloak\nsudo systemctl status keycloak\n<\/code><\/pre>\n\n\n\n
\n
From now on, Keycloak will start on boot and auto-restart on failure.<\/p>\n<\/blockquote>\n\n\n\n
\n\n\n\n
8) Firewall (if UFW is enabled)<\/h2>\n\n\n\n
You\u2019re serving through Apache only:<\/p>\n\n\n\n
sudo ufw allow 'Apache Full'\nsudo ufw status\n<\/code><\/pre>\n\n\n\n
\n\n\n\n
9) Verification Checklist<\/h2>\n\n\n\n
    \n
  1. Service running<\/strong> systemctl is-active keycloak # should print: active journalctl -u keycloak -f # tail logs; no errors<\/code><\/li>\n\n\n\n
  2. Port check (local)<\/strong> ss -lntp | grep 8080 # Keycloak listening on 0.0.0.0:8080 ss -lntp | grep ':443 ' # Apache listening on :443<\/code><\/li>\n\n\n\n
  3. Browser tests<\/strong>\n