Apache Guacamole¶

name: guacamole

services:
  guacamole:
    image: guacamole/guacamole:1.6.0@sha256:f344085e618bb05e22b964b0208dbd06d3468275bac70206f93805245e067b40
    container_name: guacamole
    restart: unless-stopped
    environment:
      # 1.6.0: every guacamole.properties key can be set as an env var (upper-case, '-' -> '_')
      GUACD_HOSTNAME: guacd
      GUACD_PORT: "4822"
      POSTGRESQL_ENABLED: "true"
      POSTGRESQL_HOSTNAME: guacamole-db
      POSTGRESQL_DATABASE: guacamole_db
      POSTGRESQL_USERNAME: guacamole_user
      POSTGRESQL_PASSWORD: ${POSTGRES_PASSWORD}
      # Users must exist in the DB (no auto-provisioning) and need a strong password
      POSTGRESQL_AUTO_CREATE_ACCOUNTS: "false"
      POSTGRESQL_USER_PASSWORD_MIN_LENGTH: "14"
      POSTGRESQL_USER_PASSWORD_PROHIBIT_REUSE: "5"
      # TOTP enforced for every user, enrolled on first login
      TOTP_ENABLED: "true"
      TOTP_ISSUER: "Guacamole"
      # Brute-force protection (auth-ban, bundled and on by default; explicit here)
      BAN_ENABLED: "true"
      BAN_MAX_INVALID_ATTEMPTS: "5"
      BAN_ADDRESS_DURATION: "900"
      # Behind a reverse proxy: take the client IP from X-Forwarded-For, but only from the proxy network.
      # Regex for the proxy network's subnet (docker network inspect tunnel-net).
      REMOTE_IP_VALVE_ENABLED: "true"
      REMOTE_IP_VALVE_INTERNAL_PROXIES: '172\.24\.\d{1,3}\.\d{1,3}'
      # Serve at / instead of /guacamole/
      WEBAPP_CONTEXT: ROOT
      LOG_LEVEL: info
      TZ: <TZ>
    depends_on:
      guacd:
        condition: service_healthy
      guacamole-db:
        condition: service_healthy
    networks:
      - tunnel-net      # reverse proxy -> guacamole:8080
      - guac-backend    # -> guacd
      - guac-db         # -> postgres
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    mem_limit: 1g
    # curl is in the image (Tomcat base)
    healthcheck:
      test: ["CMD", "curl", "-fsS", "-o", "/dev/null", "http://localhost:8080/"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s

  guacd:
    # Built locally (./guacd/Dockerfile, see below). `pull_policy: build` = never pulled; rebuilt on deploy.
    # If the official image works with your targets, use `image: guacamole/guacd:1.6.0` instead.
    build:
      context: ./guacd
    image: local/guacd:1.6.0-trixie
    pull_policy: build
    container_name: guacd
    restart: unless-stopped
    environment:
      LOG_LEVEL: info
    read_only: true
    tmpfs:
      - /tmp:size=64m
      - /home/guacd:size=16m,uid=999,gid=999   # FreeRDP writes ~/.config/freerdp at connect time
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    mem_limit: 1g
    cpus: '4.0'   # decoding H.264 + re-encoding the browser stream is the CPU-heavy part
    # Not `internal: true`: guacd has to reach the LAN targets
    networks:
      - guac-backend
    healthcheck:
      test: ["CMD-SHELL", "nc -z localhost 4822 || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 10s

  guacamole-db:
    image: postgres:17.11-alpine@sha256:1bcc18d81671b02906296aad470ec9778a6b71016ce953092024b680bad007b0
    container_name: guacamole-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: guacamole_db
      POSTGRES_USER: guacamole_user
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      TZ: <TZ>
    volumes:
      - /mnt/appdata/guacamole/postgres:/var/lib/postgresql/data
      - /mnt/appdata/guacamole/initdb:/docker-entrypoint-initdb.d:ro
    networks:
      - guac-db
    security_opt:
      - no-new-privileges:true
    mem_limit: 512m
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U guacamole_user -d guacamole_db"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

networks:
  tunnel-net:
    external: true      # shared with the reverse proxy
  guac-backend:
  guac-db:
    internal: true      # Postgres has no route out