Easy-to-install browser-based remote access plateform for home lab users, built on Apache Guacamole.
138
BetterGuac
BetterGuac is a clientless remote access gateway for SSH, RDP, VNC and Telnet, built on Apache Guacamole 1.6.0. Users open a browser, sign in with their email address and an authenticator code, and see only the servers assigned to them. No VPN client, no browser plugin.
This image runs the whole stack in one container: guacd, Tomcat 10, MariaDB and the BetterGuac web app. It is available for amd64 and arm64.
What's included Two-factor sign-in built in. Users enroll an authenticator app (it shows up as "BetterGuac") at their first sign-in. Email sign-in and a modern midnight-blue interface. Roles. Administrators manage users, servers and assignments. Regular users manage their own profile and see only their assigned servers. YAML as a source of truth. Describe servers and users in one file, preview the exact changes, then apply them by plan ID. SSH keys by path. Private keys stay as files on the gateway, never pasted into a browser or stored as text in the database. RDP fix. guacd ships with a FreeRDP 3 graphics fix.
Quick start (Docker Compose)
Save this as compose.yaml:
services:
betterguac:
image: bondjamesb07/betterguac:1.6.0-bg9
container_name: betterguac
ports:
- "127.0.0.1:8080:8080"
volumes:
- betterguac_db:/var/lib/mysql
- betterguac_conf:/etc/betterguac
- betterguac_state:/var/lib/betterguac
- betterguac_logs:/var/log/betterguac
init: false
stop_grace_period: 2m
restart: unless-stopped
healthcheck:
test: ["CMD", "/usr/local/bin/betterguac-healthcheck"]
interval: 15s
timeout: 5s
retries: 5
start_period: 90s
volumes:
betterguac_db:
betterguac_conf:
betterguac_state:
betterguac_logs:
Then start it:
docker compose up -d
docker compose logs -f betterguac
The first boot takes a minute or two while the database and configuration are created. Later boots skip that step. Open http://127.0.0.1:8080/betterguac/ (the bare address redirects there).
First sign-in A random password is generated for the first administrator on first boot. It is never printed to the logs. Read it with: docker compose exec betterguac cat /etc/betterguac/initial-admin.txt This first account is a setup administrator: it signs in with its password alone, with no authenticator code. Use it to create your own administrator (which enrolls an authenticator at first sign-in), then disable the setup account or keep it as a break-glass login, and delete initial-admin.txt. Locked out? docker compose exec betterguac betterguac-admin reset-password prints a new password and clears that account's two-factor enrollment.
Data and volumes Volume Holds /var/lib/mysql MariaDB database /etc/betterguac Settings, SSH keys, YAML file, secrets /var/lib/betterguac First-run state /var/log/betterguac First-run log Keep all four volumes together. Removing them (docker compose down -v) deletes your users, servers and keys.
Managing servers and users with YAML Edit /etc/betterguac/betterguac.yaml inside the container, then: docker compose exec betterguac betterguac-sync check /etc/betterguac/betterguac.yaml docker compose exec betterguac betterguac-sync plan /etc/betterguac/betterguac.yaml docker compose exec betterguac betterguac-sync apply /etc/betterguac/betterguac.yaml --confirm plan writes nothing and prints a plan ID; apply applies exactly that plan.
Security notes The example publishes port 8080 on the host's loopback only. Put a reverse proxy with TLS (or a private tunnel) in front rather than binding 0.0.0.0 directly. Behind a proxy, forward /betterguac/ unchanged to http://:8080/betterguac/ and enable WebSocket upgrades. MariaDB and guacd listen only inside the container and are not published. SSH private keys go in /etc/betterguac/keys/ and are referenced by full path.
License and credits BetterGuac is based on Apache Guacamole, used under the Apache License 2.0. License and notice files, including those for the bundled MySQL authentication and two-factor extensions, are in /usr/share/doc/betterguac/ inside the image. Apache Guacamole and Guacamole are trademarks of the Apache Software Foundation. BetterGuac is an independent project and is not endorsed by or affiliated with the Apache Software Foundation.
Content type
Image
Digest
sha256:e294dc59a…
Size
849.3 MB
Last updated
about 2 hours ago
docker pull bondjamesb07/betterguac