guacamole-server

What is guacamole-server?

The guacamole-server image packages guacd, the core protocol translation daemon of Apache Guacamole. Guacamole is a clientless remote desktop gateway that allows users to access remote machines through a standard web browser using HTML5, with no plugins or client software required. guacd handles the actual translation between the Guacamole protocol and backend remote desktop protocols such as RDP, VNC, SSH, and Telnet.

It is almost always deployed as part of a multi-container stack alongside the guacamole web application and a supported database (PostgreSQL or MySQL). The image is widely used in enterprise IT, cloud access platforms, and DevOps toolchains wherever browser-based remote access to servers or virtual machines is needed.

How to use this image

guacd listens on port 4822 by default. It is designed to run alongside the guacamole web app container rather than as a standalone service.

Basic usage:

# Start guacd, exposing it on the default port
docker run -d --name guacd -p 4822:4822 guacamole/guacd

Full stack with Compose (guacd + web app + PostgreSQL):

services:
  guacd:
    image: guacamole/guacd
    restart: unless-stopped
  guacamole:
    image: guacamole/guacamole
    environment:
      GUACD_HOSTNAME: guacd
      POSTGRES_HOSTNAME: db
      POSTGRES_DATABASE: guacamole_db
      POSTGRES_USER: guacamole_user
      POSTGRES_PASSWORD: secret
    ports:
      - "8080:8080"
    depends_on:
      - guacd
      - db
  db:
    image: postgres:15
    environment:
      POSTGRES_DB: guacamole_db
      POSTGRES_USER: guacamole_user
      POSTGRES_PASSWORD: secret

Enable TLS termination:

# guacd communicates internally; terminate TLS in front of the guacamole
# web app using a reverse proxy such as nginx or Traefik
docker run -d -p 443:443 \
  -v $(pwd)/nginx.conf:/etc/nginx/nginx.conf:ro nginx

Logging:

guacd writes logs to stdout and stderr by default, making them accessible via docker logs. Log verbosity can be controlled with the -L flag (e.g. -L debug).

Image variants

The guacamole-server image supports the following tags:

guacamole/guacd:latest

The most recent stable release. Recommended for most deployments. Based on a Debian base image.

guacamole/guacd:<version>

Pinned release tags such as guacamole/guacd:1.5.4. Use when you need reproducible builds or want to control upgrade timing. These are available for all stable Apache Guacamole releases.