Apache Guacamole: Remote Desktop via the Browser

Q: Why is http://my-server:8080 not enough?

The web application is deployed under the /guacamole context, not at the root of the application server. The full address is therefore http://<your_server_ip>:8080/guacamole/, trailing slash included. This is the single most common mistake right after the first docker-compose up -d. If you add a reverse proxy in front, make sure that path is preserved or rewritten correctly.

Q: What does the guacd container do, and why is it separate from the web application?

guacd is the proxy daemon that actually opens the RDP, VNC and SSH connections to the target machines and converts them into a stream the browser can render. The guacamole container only serves the web interface and handles authentication. The two talk to each other through the GUACD_HOSTNAME: guacd variable: if it is wrong, the interface loads fine but no connection will ever open.

Q: How do I secure a Guacamole instance exposed to the Internet?

Three minimum actions: replace CHANGEME_A_STRONG_PASSWORD with a real password across all three services in docker-compose.yml, change the guacadmin account immediately after the first login, and never publish port 8080 in the clear — put a reverse proxy (Nginx Proxy Manager, Traefik, Caddy) in charge of the SSL/TLS certificate. Guacamole can also plug into an existing directory through LDAP, SAML or OpenID, which spares you from managing a separate account database.

Remote-access

Difficulty: Advanced

4 min read 25/07/2026

A tutorial to install and configure Apache Guacamole, a clientless remote desktop gateway, to access your machines through a web browser.

Back to tutorials

Key takeaways

Guacamole translates the RDP, VNC and SSH protocols into HTML5: nothing to install on the client machine, and a single service (HTTPS) exposed to the Internet instead of a spread of ports 3389, 5900 and 22.
The Docker Compose deployment is built from four containers: guacd (the daemon that actually speaks the remote protocols), postgres hosting guacamole_db, db-init which runs /opt/guacamole/bin/initdb.sh --postgresql, and guacamole, the web application published on port 8080.
Access happens at http://<your_server_ip>:8080/guacamole/: the /guacamole/ suffix is part of the application context and is not optional.
Two passwords must be changed: the three occurrences of CHANGEME_A_STRONG_PASSWORD in docker-compose.yml before the first start, and the default guacadmin / guacadmin account right after the first login (Preferences, then Users).
Budget at least 2 GB of RAM. In production, put a reverse proxy (Nginx Proxy Manager, Traefik or Caddy) in front of the instance to handle TLS. Two standout features: session sharing in read-only or full-control mode, and video recording of sessions through the ./data/guacd/record volume.

What is Apache Guacamole?
Apache Guacamole is a clientless remote desktop gateway. It lets you access your computers (Linux, Windows, macOS) from any device with a simple web browser. It translates standard protocols such as VNC, RDP and SSH into an HTML5 protocol that runs in your browser.

Why use Guacamole?

Universal Access: No heavy client to install. A browser is all you need.
Centralization: Manage all your access (SSH, RDP, VNC) from a single web interface.
Security: Expose a single service (HTTPS) to the Internet instead of multiple RDP/VNC/SSH ports. It can integrate with existing authentication systems (LDAP, SAML, OpenID).
Session Sharing: Share a session in read-only or full-control mode, ideal for support or training.
Session Recording: Record RDP/VNC/SSH sessions as video for auditing or training.

Prerequisites

A Linux server with Docker and Docker Compose installed. (This is the simplest and most recommended installation method.)
Root access or sudo privileges.
At least 2 GB of RAM on the server.

Premium Content

This advanced tutorial is reserved for premium members.

9,90€ / month

All advanced tutorials
New content every week
Progress tracking
Cancel anytime

Written by

Morgann Riu

Cybersecurity and Linux administration expert. I share my knowledge through free tutorials and training to help system administrators and developers secure their infrastructures.

My profile LinkedIn GitHub

Frequently asked questions

Why is http://my-server:8080 not enough?

The web application is deployed under the /guacamole context, not at the root of the application server. The full address is therefore http://<your_server_ip>:8080/guacamole/, trailing slash included. This is the single most common mistake right after the first docker-compose up -d. If you add a reverse proxy in front, make sure that path is preserved or rewritten correctly.

What does the guacd container do, and why is it separate from the web application?

guacd is the proxy daemon that actually opens the RDP, VNC and SSH connections to the target machines and converts them into a stream the browser can render. The guacamole container only serves the web interface and handles authentication. The two talk to each other through the GUACD_HOSTNAME: guacd variable: if it is wrong, the interface loads fine but no connection will ever open.

Why a separate db-init container, and why is the first start so slow?

The PostgreSQL database must contain the Guacamole schema (users, connections, permissions tables) before the web application can start. The db-init container runs initdb.sh --postgresql to create that schema and then exits: it is a one-shot job, not a permanent service. That is why the first docker-compose up -d takes a few minutes, between pulling the images and running this initialization.

How do I secure a Guacamole instance exposed to the Internet?

Three minimum actions: replace CHANGEME_A_STRONG_PASSWORD with a real password across all three services in docker-compose.yml, change the guacadmin account immediately after the first login, and never publish port 8080 in the clear — put a reverse proxy (Nginx Proxy Manager, Traefik, Caddy) in charge of the SSL/TLS certificate. Guacamole can also plug into an existing directory through LDAP, SAML or OpenID, which spares you from managing a separate account database.

Can I assist a user live, or keep a record of sessions?

Yes to both. Session sharing lets you hand an existing session to a third party in read-only or full-control mode, which covers support and training without any extra tooling. Separately, session recording captures RDP, VNC and SSH sessions as video for audit purposes; that is the whole point of the ./data/guacd/record volume mounted on the guacd container.

Share this tutorial

X LinkedIn WhatsApp

Did you enjoy this article?

Was this article helpful?

Thanks for your feedback!

Comments

Recommended for you

Blog · Sécurité

In-depth article on the topic

Checklist Sécurité Linux

30 points essentiels pour sécuriser un serveur Linux. Recevez aussi les nouveaux tutoriels par email.

Pas de spam. Désabonnement en 1 clic.