Skip to content

Apache Guacamole

Docker Compose deployment guide for Apache Guacamole on Ubuntu.

Apache Guacamole is a clientless remote desktop gateway that allows access to servers and desktops through a web browser. It supports SSH, RDP, VNC, and Telnet connections without requiring additional client software.

Official project:

What I Use Guacamole For

I primarily use Guacamole to access my homelab servers remotely via SSH.

Typical uses include:

  • Remote server administration
  • Docker maintenance
  • Troubleshooting
  • Checking backups
  • Running updates
  • Accessing systems when travelling

Because everything runs inside a browser, I can securely access my servers from almost any device without needing a dedicated SSH client.

Why I Like Guacamole

Guacamole offers several advantages:

  • Browser-based access
  • No client software required
  • SSH support
  • RDP support
  • VNC support
  • User management
  • Two-factor authentication support
  • Self-hosted
  • Easy Docker deployment

For homelab use, it provides a convenient central portal for managing multiple systems.

Create the Project Folder

mkdir -p /opt/docker/guacamole
cd /opt/docker/guacamole

Create the Docker Compose File

Create:

/opt/docker/guacamole/docker-compose.yml

Paste:

services:
  guacamole:
    image: jwetzell/guacamole
    container_name: guacamole

    ports:
      - "8080:8080"

    volumes:
      - ./guacamole:/config

    restart: unless-stopped

Start Guacamole

From the project directory:

docker compose up -d

Verify the container is running:

docker ps

You should see:

guacamole

Initial Access

Open:

http://SERVER-IP:8562

You will be presented with the Guacamole login screen.

Follow the container documentation to create your initial user account and configure connections.

Enabling Two-Factor Authentication

One of the reasons I use this container image is its built-in support for TOTP-based two-factor authentication.

This is enabled through:

EXTENSIONS: "auth-totp"

After configuration, users must provide:

  • Username
  • Password
  • One-time authentication code

This adds an additional layer of protection when accessing servers remotely.

Creating SSH Connections

After logging in, create a new connection.

Typical SSH connection settings:

Protocol: SSH
Hostname: 192.168.x.x
Port: 22
Username: your_username

You can optionally store credentials within Guacamole or enter them manually during login.

For security reasons, I prefer not to store SSH passwords whenever possible.

Reverse Proxy Configuration

I strongly recommend placing Guacamole behind a reverse proxy such as Caddy.

Example:

guacamole.yourdomain.com {
    reverse_proxy 192.168.1.100:8562
}

If you are new to reverse proxies, see:

What is a Reverse Proxy?

Security Considerations

Because Guacamole provides remote access to your infrastructure, security should be taken seriously.

My recommendations:

  • Use HTTPS
  • Enable two-factor authentication
  • Use strong passwords
  • Keep Docker images updated
  • Restrict access where possible
  • Disable unused accounts

With HTTPS and TOTP enabled, Guacamole can be a secure way to access a homelab remotely.

Updating Guacamole

Pull the latest image:

docker compose pull

Recreate the container:

docker compose up -d

Remove unused images:

docker image prune -f

Backups

The important data is stored in:

/opt/docker/guacamole/guacamole

This contains:

  • User configuration
  • Connection settings
  • Authentication configuration
  • Extension data

Include this folder in your normal backup routine.

For details, see:

How I Backup My Homelab

Folder Structure

My deployment uses:

/opt/docker/guacamole
├── docker-compose.yml
└── guacamole/

This keeps everything contained within a single project folder.

Advanced Example (Reference Only)

This is the configuration I currently use in my own homelab.

services:
  guacamole:
    container_name: guacamole
    stop_grace_period: 60s

    image: jwetzell/guacamole

    restart: unless-stopped

    ports:
      - 8562:8080

    volumes:
      - ./guacamole:/config:rw

    environment:
      TZ: America/Santo_Domingo
      EXTENSIONS: "auth-totp"

This example enables:

  • TOTP two-factor authentication
  • Custom timezone settings
  • Persistent configuration storage

Final Thoughts

Apache Guacamole has become one of the most useful services in my homelab.

It provides a convenient browser-based gateway to multiple systems and allows me to access servers remotely without installing additional client software.

Combined with HTTPS and two-factor authentication, it offers a secure and practical way to manage a homelab from almost anywhere.