01-guacamole.md

kstack: book: Centerpoint Home Lab chapter: Utilities page: Apache Guacamole tags: [guacamole, remote-desktop, rdp, vnc, ssh, authentik, postgres]

Overview

Apache Guacamole is a clientless remote desktop gateway. It provides browser-based access to RDP, VNC, SSH, and Telnet sessions with no client software required. Authentication is via Authentik OpenID Connect (native Guacamole extension — not Traefik ForwardAuth). The stack is three containers: the web application, the guacd native protocol daemon, and PostgreSQL 15 for connection and user data.

Access

Type	URL	Auth
External	https://guac.jeeves5454.ddns.net	Authentik OIDC + GeoBlock + CrowdSec
Internal	https://guac.home.local	Authentik OIDC (Step-CA TLS)

Guacamole uses its built-in openid extension with EXTENSION_PRIORITY=openid to handle the Authentik OIDC flow directly. Traefik does not apply authentik-auth@docker ForwardAuth.

Containers

Container	Image	Role
guacamole	guacamole/guacamole:latest	Web application (Tomcat/Java)
guacd	guacamole/guacd:latest	Native protocol daemon (RDP/VNC/SSH)
guacamole_db	postgres:15-alpine	PostgreSQL database

guacamole (application)

Runtime: Apache Tomcat / Java. WEBAPP_CONTEXT=ROOT serves the app at / rather than /guacamole.

Key environment variables:

Variable	Value / Notes
GUACD_HOSTNAME	guacd
POSTGRESQL_HOSTNAME	postgres (internal alias for guacamole_db)
POSTGRESQL_DATABASE	guacamole_db
POSTGRESQL_USER	guacamole_user
POSTGRESQL_PASSWORD	REDACTED
WEBAPP_CONTEXT	ROOT
EXTENSION_PRIORITY	openid
OPENID_ISSUER	https://auth.jeevesconsults.ca/application/o/guacamole/
OPENID_CLIENT_ID	A1l7KFyrugknbC8jtFjPxm520XkcNVjGMfTFtJMt
OPENID_CLIENT_SECRET	REDACTED
OPENID_REDIRECT_URI	https://guac.jeeves5454.ddns.net/
OPENID_AUTHORIZATION_ENDPOINT	https://auth.jeevesconsults.ca/application/o/authorize/
OPENID_JWKS_ENDPOINT	https://auth.jeevesconsults.ca/application/o/guacamole/jwks/
OPENID_SCOPE	openid email profile
OPENID_USERNAME_CLAIM_TYPE	preferred_username

No bind mounts — app state is stored in PostgreSQL.

guacd

The native protocol daemon that handles the actual RDP, VNC, SSH, and Telnet protocol sessions. Guacamole app proxies all protocol traffic through guacd.

Bind mounts:

Host Path	Container Path	Purpose
/home/jeeves/docker/guacamole/drive	/drive	Virtual drive for file transfer
/home/jeeves/docker/guacamole/record	/record	Session recordings

guacamole_db (PostgreSQL 15)

Image: postgres:15-alpine

Variable	Value
POSTGRES_DB	guacamole_db
POSTGRES_USER	guacamole_user
POSTGRES_PASSWORD	REDACTED
PGDATA	/var/lib/postgresql/data/guacamole

Bind mounts:

Host Path	Container Path	Purpose
/home/jeeves/docker/guacamole/db-data	/var/lib/postgresql/data	Database files
/home/jeeves/docker/guacamole/init	/docker-entrypoint-initdb.d	Init SQL scripts

Traefik Labels

traefik.http.routers.guacamole-external.rule: Host(`guac.jeeves5454.ddns.net`)
traefik.http.routers.guacamole-external.entrypoints: websecure
traefik.http.routers.guacamole-external.tls.certresolver: letsencrypt
traefik.http.routers.guacamole-external.middlewares: plex-geoblock@file,crowdsec-bouncer@file
traefik.http.routers.guacamole-external.service: guac-svc

traefik.http.routers.guacamole-internal.rule: Host(`guac.home.local`)
traefik.http.routers.guacamole-internal.entrypoints: websecure
traefik.http.routers.guacamole-internal.tls.certresolver: step-ca
traefik.http.routers.guacamole-internal.service: guac-svc

traefik.http.services.guac-svc.loadbalancer.server.port: 8080
traefik.docker.network: traefik-net

Notes / Gotchas

• EXTENSION_PRIORITY=openid means Guacamole's OpenID extension takes precedence over any local user database. If Authentik is down, Guacamole login is unavailable — there is no local admin fallback while OpenID is primary.
• OPENID_REDIRECT_URI must exactly match the redirect URI registered in Authentik. It points to the external domain (guac.jeeves5454.ddns.net) even when accessing internally — Authentik sends the browser there after authentication.
• WEBAPP_CONTEXT=ROOT removes the /guacamole path prefix. The app responds directly at /. Without this, Traefik would need to strip the prefix or all URLs would be /guacamole/....
• Session recordings are stored in the record bind mount. Manage disk usage if many long sessions are recorded.
• The init bind mount contains the SQL schema initialisation scripts for the database. These run once on first start. Do not remove them if the container has not yet initialised.

---

Last Updated: 2026-06-17