From a2af06f9250a1449bed31904c6cf2c463e4c6532 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 19 Jun 2026 16:03:40 +0000
Subject: [PATCH] Wire guacd sidecar into docker-compose for Remote Desktop
 deployment

Adds a guacamole/guacd service to docker-compose.yml and points the backend at
it (ARCHNEST_GUACD_HOST/PORT) plus passes through ARCHNEST_GUAC_CRYPT_KEY, with
depends_on ordering. Documents ARCHNEST_GUACD_* in backend/.env.example. Closes
the Phase 5 deployment gap. Compose validated via `docker compose config`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BbJV5nm8KPVH1oNJYKpnoF
---
 TERMIX_MIGRATION.md  |  2 +-
 backend/.env.example |  4 ++++
 docker-compose.yml   | 16 ++++++++++++++++
 3 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/TERMIX_MIGRATION.md b/TERMIX_MIGRATION.md
index dd8b263..27bd3b3 100644
--- a/TERMIX_MIGRATION.md
+++ b/TERMIX_MIGRATION.md
@@ -129,7 +129,7 @@ One real bug was caught and fixed during this browser verification: the page ini
 
 **Documented gaps**:
 - Telnet was not verified — no real telnet server could be installed in this sandbox (`telnetd`/`inetutils-telnetd` 404'd against the available `apt` mirror snapshot). RDP was not verified either (no real RDP target was available); only the VNC path has a live, browser-confirmed end-to-end test. The route code path is identical across all three protocols (same `ClientConnection`/`guacd` flow, differing only in the `connection.type` and per-protocol settings), so this is a coverage gap rather than a known defect.
-- `guacd` is not yet added to a `docker-compose.yml` for actual deployment on `racknerd1` — it currently must be run as a sidecar process/container manually, pointed at via `ARCHNEST_GUACD_HOST`/`ARCHNEST_GUACD_PORT`. Wiring that into the real deployment compose file is follow-up work, not done here.
+- ~~`guacd` is not yet added to a `docker-compose.yml`~~ **(now done)**: `docker-compose.yml` gained a `guacd` service (`guacamole/guacd:1.5.5`, no published port — only the backend reaches it on the compose network), the backend service now sets `ARCHNEST_GUACD_HOST=guacd`/`ARCHNEST_GUACD_PORT=4822` + `ARCHNEST_GUAC_CRYPT_KEY` and `depends_on: [guacd]`, and `backend/.env.example` documents the `ARCHNEST_GUACD_*` vars for local dev. Verified the compose file parses cleanly via `docker compose config` (the Docker daemon isn't running in this sandbox, so an actual `up` was not performed).
 - All test artifacts (test `guacd`/`vncserver` processes, test backend instance, test DB, tokens, temp files, Playwright scripts) were cleaned up afterward.
 
 ### Phase 6 — Host Metrics Widgets (DONE, with documented gaps)
diff --git a/backend/.env.example b/backend/.env.example
index 593a1ab..9d12e1d 100644
--- a/backend/.env.example
+++ b/backend/.env.example
@@ -4,3 +4,7 @@ ARCHNEST_JWT_SECRET=change-me-to-a-long-random-string
 ARCHNEST_SECRET_KEY=change-me-to-another-long-random-string
 ARCHNEST_CORS_ORIGIN=http://localhost:5173
 ARCHNEST_GUAC_CRYPT_KEY=change-me-to-a-32-byte-secret!!
+# Where guacd is reachable. In docker-compose this is the "guacd" service name;
+# for local dev run guacd separately and point these at it (default 127.0.0.1:4822).
+ARCHNEST_GUACD_HOST=127.0.0.1
+ARCHNEST_GUACD_PORT=4822
diff --git a/docker-compose.yml b/docker-compose.yml
index 7393402..ffaadfc 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -20,10 +20,26 @@ services:
       - ARCHNEST_JWT_SECRET=${ARCHNEST_JWT_SECRET}
       - ARCHNEST_SECRET_KEY=${ARCHNEST_SECRET_KEY}
       - ARCHNEST_CORS_ORIGIN=${ARCHNEST_CORS_ORIGIN:-https://archnest.snsnetlabs.com}
+      # Remote Desktop (RDP/VNC/Telnet via Guacamole). The crypt key must be exactly
+      # 32 bytes (AES-256-CBC); guacd runs as the sidecar service below.
+      - ARCHNEST_GUAC_CRYPT_KEY=${ARCHNEST_GUAC_CRYPT_KEY}
+      - ARCHNEST_GUACD_HOST=guacd
+      - ARCHNEST_GUACD_PORT=4822
     volumes:
       - archnest-data:/data
     ports:
       - "4000:4000"
+    depends_on:
+      - guacd
+
+  # guacd is the Guacamole proxy daemon that actually speaks RDP/VNC/Telnet to
+  # target hosts; the backend's /api/guacamole websocket route connects to it.
+  guacd:
+    image: guacamole/guacd:1.5.5
+    container_name: archnest-guacd
+    restart: unless-stopped
+    # No published port: only the backend (same compose network) needs to reach
+    # it on 4822. Exposed internally via the service name "guacd".
 
 volumes:
   archnest-data: