How to Install Apache Guacamole (Docker) on Ubuntu 24.04

Apache Guacamole is a clientless remote desktop gateway that supports RDP, VNC, and SSH — all accessible through a modern web browser. Because it uses HTML5, no plugins or client software are needed: once deployed, users can securely connect to desktops and servers from anywhere, directly from the browser.

Running Guacamole in Docker simplifies deployment, packaging all required services (Guacamole client, Guacd proxy daemon, and database support) into containers. Combined with Ubuntu 24.04 LTS (Noble Numbat) — which provides systemd 255, modern OpenSSL 3, and up-to-date Docker packages — you get a stable, secure, and long-term supported foundation for remote access infrastructure.

Architecture Overview

Layer	Component	Role
OS	Ubuntu 24.04 LTS	Stable, secure base with long-term support
Runtime	Docker Engine	Runs Guacamole and supporting services in containers
Application	Apache Guacamole (Web UI)	Provides HTML5 remote desktop gateway
Proxy Daemon	guacd (in container)	Handles RDP, VNC, SSH protocols and streams them to the web client
Database	PostgreSQL/MySQL (optional)	Stores users, permissions, and connections (for persistent setups)
Reverse Proxy	Nginx (recommended)	TLS termination, HTTP/2, authentication, and access control
TLS	Let’s Encrypt / PKI	Provides HTTPS for secure browser-based access

Why Use Apache Guacamole?

Clientless access – no agents or plugins; only a browser is needed.
Multi-protocol – supports RDP, VNC, and SSH out-of-the-box.
Centralized access – manage multiple remote servers and desktops from one interface.
Secure by design – HTTPS encryption, user authentication, role-based permissions.
Docker-ready – simple containerized deployment, easy upgrades, and portability.

Guacamole vs Other Remote Access Solutions

Feature/Capability	Apache Guacamole	NoMachine / AnyDesk	VPN-only Access	RDP Client Tools
Client requirements	None (browser-based)	Proprietary client	OS-native VPN client	RDP/VNC client
Protocols supported	RDP, VNC, SSH	RDP/Custom	N/A	RDP/VNC only
Deployment model	Self-hosted, Docker	Proprietary server	Network-level only	Point-to-point
Multi-user management	Yes (RBAC, DB backend)	Limited	No	No
Security	TLS + reverse proxy	Vendor dependent	VPN encryption only	Basic encryption

Guacamole is strongest when you want centralized, browser-based remote access that works across devices without requiring extra software.

Security & Best Practices

Always run Guacamole behind Nginx with HTTPS.
Use Let’s Encrypt or corporate PKI for certificates.
Restrict access with firewall rules; expose only ports 80/443.
Store user accounts and permissions in a PostgreSQL or MySQL database (for persistence).
Enable MFA/SSO if available in your environment.
Keep Docker images up to date (guacamole/guacd and guacamole/guacamole).
Consider fail2ban or rate limiting to prevent brute-force login attempts.

Typical Use Cases

Secure remote desktop gateway for teams and sysadmins.
Centralized SSH access to Linux servers.
Browser-based access to Windows RDP desktops without installing clients.
Lightweight alternative to VPN-based remote access.
Secure remote access for BYOD (Bring Your Own Device) environments.

Deploying Apache Guacamole in Docker on Ubuntu 24.04 with Nginx and SSL gives you a secure, clientless remote access solution that’s modern, lightweight, and enterprise-ready.

1. Create a Shape.Host VPS Instance

Click “Create” → “Instance”.

Select the server location closest to your users.

Shape.host instance form with the data center location selector highlighted.

Choose Ubuntu 24.04 (64-bit) as the operating system.

Select a plan with at least 2 CPUs, 4 GB RAM, and 20 GB SSD.

Shape.host instance form with the operating system image selector highlighted.

Click “Create Instance”.

Shape.host instance form with the Create Instance button highlighted.

Copy your server IP address from the Resources section.

Shape.host Resources dashboard with the server IP address highlighted.

2. Connect to Your VPS

On Linux/macOS

ssh root@your-server-ip

On Windows

On Windows 10/11 PowerShell: ssh root@your-server-ip
On older Windows, download PuTTY and log in as root.

3. Update System and Install Prerequisites

apt update
apt upgrade

Updates the package index and upgrades installed packages.

Terminal showing APT package management commands and output.

apt install apt-transport-https ca-certificates curl gnupg lsb-release

Installs tools for secure package management.

4. Install Docker and Docker Compose

Add Docker’s GPG key:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/trusted.gpg.d/docker.gpg

Add Docker repository:

echo "deb [arch=$(dpkg --print-architecture)] https://download.docker.com/linux/ubuntu noble stable" > /etc/apt/sources.list.d/docker.list

Update repositories and install Docker:

apt update
apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Enable and start Docker:

systemctl enable --now docker

Check versions:

docker --version
docker compose version

Terminal showing the installed Docker Compose version.

5. Create Guacamole Docker Setup

Create a working directory:

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

Create the docker-compose.yml file:

nano docker-compose.yml

Terminal showing container image download progress.

Paste:

services:
  guacamole-db:
    image: postgres:15
    container_name: guac-db
    environment:
      POSTGRES_USER: guacuser
      POSTGRES_PASSWORD: StrongPassword123!
      POSTGRES_DB: guacamole_db
    volumes:
      - db_data:/var/lib/postgresql/data
    restart: unless-stopped

  guacd:
    image: guacamole/guacd:1.5.5
    container_name: guacd
    restart: unless-stopped

  guacamole:
    image: guacamole/guacamole:1.5.5
    container_name: guacamole
    environment:
      POSTGRES_HOSTNAME: guacamole-db
      POSTGRES_DATABASE: guacamole_db
      POSTGRES_USER: guacuser
      POSTGRES_PASSWORD: StrongPassword123!
      GUACD_HOSTNAME: guacd
      GUACD_PORT: 4822
    ports:
      - "8080:8080"
    depends_on:
      - guacamole-db
      - guacd
    restart: unless-stopped

volumes:
  db_data:

Terminal showing the GNU nano editor and configuration text.

6. Initialize PostgreSQL Database for Guacamole

Start the database container:

docker compose up -d guacamole-db

Wait a bit to ensure the database is ready:

sleep 10

Generate SQL schema:

docker run --rm guacamole/guacamole:1.5.5 /opt/guacamole/bin/initdb.sh --postgres > initdb.sql

Import schema into PostgreSQL:

cat initdb.sql | docker exec -i guac-db psql -U guacuser -d guacamole_db

(Optional double-check step):

docker exec -it guac-db psql -U guacuser -d guacamole_db -c "\dt"

7. Start Guacamole Services

docker compose up -d

Check running containers:

docker compose ps

Now Guacamole is available at:

http://your-server-ip:8080/guacamole

Default login:

Username: guacadmin
Password: guacadmin

👉 Change the admin password immediately after first login.

8. Configure Nginx Reverse Proxy

Install Nginx:

apt install nginx

Create a config file:

nano /etc/nginx/sites-available/guacamole.conf

Paste:

server {
    listen 80;
    server_name guac.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080/guacamole/;
        proxy_buffering off;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $http_connection;
        proxy_set_header Host $host;
    }
}

Enable the site and reload:

ln -s /etc/nginx/sites-available/guacamole.conf /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

Terminal showing Nginx configuration test output.

9. Enable SSL with Let’s Encrypt

Install Certbot:

apt install certbot python3-certbot-nginx

Request SSL certificate:

certbot --nginx -d ubuntu-tutorials.shape.host

Terminal showing Certbot certificate commands and messages.

10. Access Guacamole

Now open your browser and visit:

https://guac.example.com

This tutorial was created and tested on a Shape.Host Cloud VPS.

With Shape.Host you can:

Deploy fast VPS servers worldwide
Run popular Linux distros: Ubuntu, Debian, AlmaLinux, Rocky Linux
Scale resources instantly as your project grows
Use built-in snapshots, backups, and monitoring

Start today at https://shape.host and set up Apache Guacamole in minutes.