Infrastructure project · DigitalOcean · Linux · Remote access

A Linux desktop, delivered through a browser.

I wanted a way to access a full Ubuntu desktop without having to install a remote-desktop client on every machine. The idea was to open a browser, sign in, and land in an XFCE session running on a small DigitalOcean server. Getting that experience working was the project; making the connection private and dependable was the real engineering work.

Ubuntu Server 24.04.5 LTSApache Guacamole 1.5.5XRDP + XFCEDocker ComposePostgreSQL 16

What I was building

Think of it as a Linux workstation that lives on a server, with the browser acting as the screen and keyboard. Guacamole provides the browser-based interface. Its proxy service, guacd, speaks RDP to XRDP on the Ubuntu host. XRDP starts the XFCE desktop for the xmldesktop account, while PostgreSQL keeps Guacamole's authentication and connection details.

I kept the deployment deliberately lightweight: the observed DigitalOcean droplet had 2 GiB of RAM and a 48 GB disk. Docker Compose ran the Guacamole web application, guacd, and PostgreSQL; XRDP and XFCE ran directly on Ubuntu.

My browserlocalhost:8080
SSH tunnelEncrypted entry
GuacamoleWeb client
guacdRDP proxy
XRDP + XFCELinux desktop

PostgreSQL sits alongside Guacamole inside the Docker network and stores its authentication and connection configuration. The diagram shows the user-facing session path, not every internal service connection.

First, I prepared the Ubuntu host

I started with a clean Ubuntu Server 24.04.5 LTS droplet and connected over SSH using a key from my Windows workstation. Before touching the remote desktop pieces, I updated the host and installed the packages needed for XFCE, XRDP, session management, firewalling and ACLs.

apt update
apt upgrade -y
apt install -y xfce4 xfce4-session xrdp dbus-x11 acl ufw curl ca-certificates openssl

Docker and the Compose plugin were installed on the host as the container runtime. The versions observed during the work were Docker 29.1.3 and Docker Compose 2.40.3. I also created or verified the dedicated Linux account, xmldesktop, and added it to the sudo group because I needed to perform administrative tasks from the desktop session.

id xmldesktop || adduser xmldesktop
usermod -aG sudo xmldesktop
runuser -u xmldesktop -- sh -c 'printf "%s\\n" xfce4-session > /home/xmldesktop/.xsession'
chown xmldesktop:xmldesktop /home/xmldesktop/.xsession
chmod 600 /home/xmldesktop/.xsession

That .xsession file is a small but important detail: it tells XRDP which desktop session to launch. In this case, it launches xfce4-session. I learned to fully log out and reconnect after changing group membership; an already-running session does not automatically pick up new groups.

The networking decision that mattered

This is where I was careful about the design. I did not want to expose the Guacamole portal, the RDP service, the proxy or the database directly to the internet. The public-facing administrative entry remained SSH. Guacamole was bound to the server's loopback address on 127.0.0.1:8080, and XRDP listened on the Docker bridge gateway at 172.28.0.1:8933.

I created or verified a dedicated Docker bridge called desktop-net, using 172.28.0.0/24 with gateway 172.28.0.1. That gave the Guacamole proxy a private route to XRDP without making RDP a public service.

docker network inspect desktop-net

# For a fresh deployment only, if the network does not exist:
docker network create --driver bridge --subnet 172.28.0.0/24 --gateway 172.28.0.1 desktop-net

Then I configured XRDP to listen on 172.28.0.1:8933 and restricted the UFW rule so only traffic from the Docker subnet, arriving on the Docker bridge interface, could reach it. During troubleshooting I briefly had a broad allow rule for port 8933; I removed it. The lesson is simple: don't solve a connectivity problem by opening a service to the whole internet.

# In /etc/xrdp/xrdp.ini, under [Globals]:
port=tcp://172.28.0.1:8933

# Allow only the Docker subnet on the actual bridge interface:
ufw allow in on br-<actual-bridge-name> from 172.28.0.0/24 to 172.28.0.1 port 8933 proto tcp

# Verify the listener and firewall:
ss -lntp | grep ':8933'
ufw status verbose
Security principle: I kept TCP 8933 (XRDP), 4822 (guacd), 5432 (PostgreSQL), and the Guacamole web port 8080 off the public interface. The current access method is SSH plus a local tunnel—not a publicly exposed web portal.

Then I brought up Guacamole and its database

With the host and private network ready, I created /opt/guacamole for the Compose deployment. PostgreSQL ran as a container with a persistent volume, while the Guacamole web app and guacd shared the same Docker network. The web port was published only on host loopback.

I kept the database password in a protected .env file rather than putting it in the Compose file or source control. The database was named guac_db, the database role was guac_user, and the PostgreSQL container was named guac-postgres.

mkdir -p /opt/guacamole
cd /opt/guacamole
chmod 700 /opt/guacamole
printf "DB_PASSWORD=%s\\n" "$(openssl rand -hex 32)" > .env
chmod 600 .env

For a new database, Guacamole needs its PostgreSQL schema initialized using the same application version that will run. In this deployment, the final observed Guacamole and guacd versions were both 1.5.5, so the schema-generation step was aligned to 1.5.5 as well. I treated schema initialization as a one-time setup step—not something to rerun as a generic fix on an existing database.

docker compose up -d postgres

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

docker exec -i guac-postgres psql -v ON_ERROR_STOP=1 \
  -U guac_user -d guac_db < /opt/guacamole/initdb.sql

Once the stack was configured, I validated the Compose file, started the services and checked the container states and logs. I also tested the actual HTTP endpoint; a container showing “Up” by itself was not enough to prove the web application had finished starting.

docker compose config -q
docker compose pull
docker compose up -d
docker compose ps -a
docker compose logs --tail=60 guacamole
docker compose logs --tail=40 guacd
curl -I --max-time 10 http://127.0.0.1:8080/guacamole/

Making the browser connection work

From Windows PowerShell, I opened an SSH local port forward and left that terminal running. It carried my browser traffic securely to the Guacamole service listening on the Ubuntu server's loopback interface. I then opened the local URL in the browser.

ssh -N -L 8080:127.0.0.1:8080 root@<YOUR_SERVER_IP>
http://127.0.0.1:8080/guacamole/

Inside Guacamole, I configured an RDP connection to host 172.28.0.1, port 8933, using the xmldesktop Linux account. XRDP was using its default self-signed certificate, which caused certificate validation warnings during the first connection attempts. The connection eventually authenticated successfully; the certificate exception was a workaround for this private bridge setup, not the ideal long-term certificate posture.

The initial Guacamole administrator login used the default guacadmin credentials. The runbook correctly flags password rotation as something that must be confirmed; it does not claim that this was completed. If the default password is still in use, it must be changed before the system is treated as secure.

The troubleshooting was the real project

Things did not work perfectly on the first attempt. I had to trace each failure through the layer responsible for it rather than changing several things at once.

ConnectivityGuacamole could not reach XRDP

The RDP target was not reachable through the Docker bridge and host firewall. I checked the bridge, bound XRDP to the gateway address, and narrowed the firewall rule to the Docker subnet.

TLSXRDP certificate validation failed

XRDP was presenting its default self-signed certificate. The TLS handshake later succeeded using the connection's certificate-handling option, while keeping the RDP target private.

Application stabilityRDP sessions closed after login

With Guacamole/guacd 1.6.0, logs showed a display-layer assertion failure after XRDP had authenticated the user. The observed signature matched a reported Guacamole issue, so I rolled both components back together to 1.5.5.

Version mismatchGuacamole container kept restarting

The Compose configuration used POSTGRESQL_USERNAME, but the 1.5.5 image expected POSTGRESQL_USER. Correcting the version-specific variable allowed the web container to start.

Linux permissionsDesktop user was not in sudoers

The user had been added to the sudo group, but the existing session had not refreshed its group membership. A full logout and reconnect, followed by sudo whoami, was the right test.

One important lesson came from the version rollback. The 1.6.0 documentation used a different PostgreSQL environment variable name from 1.5.5. Those settings are not interchangeable. I had to align the web and proxy image versions and use the configuration expected by the actual image. I also kept the PostgreSQL data volume intact; changing application tags is not the same thing as safely rolling back a database schema.

How I checked the result

I considered the deployment successful when the browser could reach Guacamole through the SSH tunnel, Guacamole could authenticate against PostgreSQL, and the RDP connection opened an XFCE session for xmldesktop. The last observed state in the runbook recorded Guacamole 1.5.5 and guacd 1.5.5 running, PostgreSQL healthy, the portal bound to 127.0.0.1:8080, and a successful desktop connection after troubleshooting.

Last observed deployment state

I would still run a sustained 10–15 minute session and reconnect test before calling the deployment production-ready. I would also verify the admin password rotation, confirm the exact shared-folder path and ACLs, review the unexplained UFW rule for TCP 14344, and test an encrypted off-server database backup and restore.

What I took away from it

This project reminded me that a remote desktop is not just an application you install. It is a chain of services, network boundaries, authentication, certificates, Linux sessions and persistent data. When one link fails, the useful skill is knowing where to look: container logs for application startup, XRDP logs for desktop authentication, socket listeners for binding issues, and firewall rules for reachability.

The outcome was a working browser-based Linux desktop with a deliberately private access path. Just as importantly, I documented the rough edges and the items still needing verification instead of presenting a successful login as proof that every production control was finished.

Production boundary: Direct public HTTPS access was not implemented in the documented deployment. Do not expose port 8080 or change the binding to 0.0.0.0 as a shortcut. A public portal would need a separate, tested HTTPS reverse-proxy design, certificate renewal, authentication and access controls.
Project narrative based on the deployment and operations runbook prepared 25 October 2026. Sensitive server addressing and credentials are intentionally not published.