Apache Guacamole Distroless

Minimal, secure Apache Guacamole container images based on Google's distroless base.

Components

This repository provides two container images:

Image	Description	Base
guacd	Guacamole proxy daemon	distroless/base-debian12
guacamole	Guacamole web application	distroless/java21-debian12

Features

• Minimal footprint: Small image size, reduced attack surface
• Multi-architecture: linux/amd64 and linux/arm64
• Distroless base: No shell, no package manager
• Security-first: Runs as non-root (UID 65532)
• glibc-based guacd: Built from source with FreeRDP 2.x support
• Rust entrypoint: Configuration generation for guacamole-client

Quick Start

# docker-compose.yml
services:
  guacd:
    image: git.breis.ch/images/guacamole/guacd:latest
    restart: unless-stopped

  guacamole:
    image: git.breis.ch/images/guacamole/guacamole:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      GUACD_HOSTNAME: guacd
      MYSQL_HOSTNAME: db
      MYSQL_DATABASE: guacamole_db
      MYSQL_USER: guacamole_user
      MYSQL_PASSWORD: your_password
    depends_on:
      - guacd

  db:
    image: mariadb:11
    environment:
      MYSQL_ROOT_PASSWORD: root_password
      MYSQL_DATABASE: guacamole_db
      MYSQL_USER: guacamole_user
      MYSQL_PASSWORD: your_password
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

Available Tags

Tag	Version	Notes
1.6.0, 1.6, latest	1.6.0	Current stable

Environment Variables

guacd

Variable	Default	Description
GUACD_LOG_LEVEL	info	Log level

guacamole

Connection Settings

Variable	Default	Description
GUACD_HOSTNAME	guacd	guacd hostname
GUACD_PORT	4822	guacd port
GUACD_SSL	false	Enable SSL to guacd

MySQL/MariaDB Authentication

Variable	Default	Description
MYSQL_HOSTNAME	-	Database hostname
MYSQL_PORT	3306	Database port
MYSQL_DATABASE	guacamole_db	Database name
MYSQL_USER	guacamole_user	Database user
MYSQL_PASSWORD	-	Database password
MYSQL_PASSWORD_FILE	-	Docker secret for password

PostgreSQL Authentication

Variable	Default	Description
POSTGRESQL_HOSTNAME	-	Database hostname
POSTGRESQL_PORT	5432	Database port
POSTGRESQL_DATABASE	guacamole_db	Database name
POSTGRESQL_USER	guacamole_user	Database user
POSTGRESQL_PASSWORD	-	Database password
POSTGRESQL_PASSWORD_FILE	-	Docker secret for password

LDAP Authentication

Variable	Default	Description
LDAP_HOSTNAME	-	LDAP server hostname
LDAP_PORT	389	LDAP port
LDAP_USER_BASE_DN	-	User base DN
LDAP_GROUP_BASE_DN	-	Group base DN
LDAP_SEARCH_BIND_DN	-	Bind DN for search
LDAP_SEARCH_BIND_PASSWORD	-	Bind password
LDAP_ENCRYPTION_METHOD	-	none, ssl, starttls

TOTP Two-Factor Authentication

Variable	Default	Description
TOTP_ENABLED	-	Enable TOTP 2FA
TOTP_ISSUER	-	TOTP issuer name
TOTP_PERIOD	30	TOTP code validity period

OpenID Connect

Variable	Default	Description
OPENID_AUTHORIZATION_ENDPOINT	-	Authorization endpoint URL
OPENID_JWKS_ENDPOINT	-	JWKS endpoint URL
OPENID_ISSUER	-	Token issuer
OPENID_CLIENT_ID	-	Client ID
OPENID_REDIRECT_URI	-	Redirect URI

SAML

Variable	Default	Description
SAML_IDP_METADATA_URL	-	IdP metadata URL
SAML_ENTITY_ID	-	SP entity ID
SAML_CALLBACK_URL	-	Callback URL

Java Options

Variable	Default	Description
JAVA_OPTS	-Xms256m -Xmx512m	JVM options

Docker Secrets

All password variables support Docker secrets via the _FILE suffix:

services:
  guacamole:
    image: git.breis.ch/images/guacamole/guacamole:latest
    environment:
      MYSQL_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt

Ports

Image	Port	Description
guacd	4822	Guacamole protocol
guacamole	8080	Web interface

Security

File Ownership

All binaries are owned by root and cannot be modified by the runtime user.

Runtime Hardening (Recommended)

services:
  guacd:
    image: git.breis.ch/images/guacamole/guacd:latest
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL

  guacamole:
    image: git.breis.ch/images/guacamole/guacamole:latest
    read_only: true
    tmpfs:
      - /tmp
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL

Kubernetes SecurityContext

securityContext:
  readOnlyRootFilesystem: true
  allowPrivilegeEscalation: false
  capabilities:
    drop: ["ALL"]
  runAsNonRoot: true
  runAsUser: 65532

Healthcheck

Both images include built-in healthchecks:

# guacd
docker inspect --format='{{.State.Health.Status}}' guacd

# guacamole
docker inspect --format='{{.State.Health.Status}}' guacamole

Database Initialization

You need to initialize the database schema before first use. Download the initialization scripts from Apache Guacamole:

# For MySQL/MariaDB
docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --mysql > initdb.sql
mysql -h db -u root -p guacamole_db < initdb.sql

# For PostgreSQL
docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --postgresql > initdb.sql
psql -h db -U postgres -d guacamole_db -f initdb.sql

License

Apache-2.0