Remote-access
Difficulty: Advanced
4 min read

Apache Guacamole: Remote Desktop via the Browser

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

Back to tutorials
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.

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

Did you enjoy this article?

Comments

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.