Bottom Line: Modern Guacamole Is a Three-Part Service, Not Just One Web Container
Apache Guacamole gives you browser-based RDP, VNC and SSH access without a desktop client. A production-style Docker deployment normally includes the Guacamole web application, guacd, and a database such as PostgreSQL or MySQL/MariaDB. The old 2023 BigBearCasaOS package should be treated as historical convenience, not the architecture reference.
Use the Official Guacamole Containers
The Apache project publishes supported guacamole/guacamole and guacamole/guacd images. The Guacamole Docker stack describes the official layout. The broader Guacamole installation modes explains why database authentication is preferred for real deployments.
Recommended Container Layout
guacamole-web
|
+-- guacd
|
+-- postgres or mariadbKeep all three services on a private Docker network. Only publish the Guacamole web endpoint. Do not publish the database or guacd to the LAN unless another component genuinely requires it.
Initialize the Database Before First Login
Guacamole's database authentication extension needs its schema loaded before the web application can store users and connections. Use the SQL initialization files that match the exact Guacamole version and database type. Keep the database data directory persistent.
Put HTTPS in Front Before Remote Exposure
Guacamole can carry administrator passwords and remote desktop sessions, so exposing it over plain HTTP is a poor boundary. Use a reverse proxy with HTTPS and strong authentication. The ZimaOS HTTPS proxying provides the ZimaOS reverse-proxy pattern.
Use MFA or SSO When Guacamole Is Internet-Facing
Apache Guacamole supports extensions for TOTP, OpenID Connect, SAML and other authentication systems. Remote desktop access is an administrative function; protect it accordingly rather than relying only on a short local password.
When to Run Guacamole in a VM Instead
If you want Guacamole isolated from the NAS Docker engine, or you already have several infrastructure services, a small Debian/Ubuntu VM gives you a clean update and firewall boundary. The ZimaOS VM requirements covers the host resources needed for that split.
The ZimaOS app requirements helps when Guacamole shares the NAS with databases, media servers and monitoring.
Persist the Database and Guacamole Configuration Separately
Do not treat the web container as the stateful part of Guacamole. User accounts, saved connections and authentication data live in the database, while extensions and custom configuration may live in mounted directories. Back up those persistent components before replacing images. A clean container pull should be routine; rebuilding every remote connection from memory should not be.
Reverse Proxy WebSockets Correctly
Guacamole uses long-lived browser connections and WebSocket support for interactive sessions. If login works but remote desktops disconnect, freeze or fall back to poor performance behind a proxy, verify WebSocket forwarding and proxy timeouts before blaming RDP/VNC itself. Keep the Guacamole path or hostname stable so callback and browser-session behavior does not change every update.
Separate Guacamole Access From Target-System Credentials
A Guacamole login controls entry to the gateway; the Windows/Linux target still has its own RDP, VNC or SSH credentials and policies. Avoid reusing one administrator password everywhere. For shared household or team access, create named Guacamole users and grant only the connections each person needs.
Test the Gateway Before Exposing It
Before adding public DNS, test one SSH or RDP connection from the LAN, confirm clipboard and session behavior, restart every Guacamole container, and verify that saved connections still work. Then test a database backup and restore. A gateway that survives container recreation is much closer to a maintainable deployment than one that works only until the next image update.
FAQ
Does Guacamole need a desktop client?
No. Users connect through a web browser while Guacamole translates browser traffic into RDP, VNC or SSH sessions.
Does Guacamole need a database?
For production-style user and connection management, yes. The simple XML authentication method is mainly suitable for basic testing.
Should I expose guacd to the internet?
No. Keep guacd private behind the Guacamole web application.
Can Guacamole replace a VPN?
It can provide browser access to configured remote desktops, but it is not a general private network tunnel for every service.
Can I use MariaDB instead of PostgreSQL?
Yes, supported database authentication options include MySQL-compatible databases and PostgreSQL when configured with the corresponding extension and schema.
