From 043d5a3b6e949613904f25198dbaa9ce7abb5c9a Mon Sep 17 00:00:00 2001
From: Mikei386 <44135113+Mikei386@users.noreply.github.com>
Date: Tue, 29 Sep 2026 19:35:55 +0200
Subject: [PATCH] Document and configure isolated Athena frontend deployment

---
 README.md                  |  2 ++
 deploy/compose.athena.yaml | 13 ++++++++
 docs/ATHENA_DEPLOYMENT.md  | 61 ++++++++++++++++++++++++++++++++++++++
 docs/VALIDATION.md         | 12 ++++++++
 4 files changed, 88 insertions(+)
 create mode 100644 deploy/compose.athena.yaml
 create mode 100644 docs/ATHENA_DEPLOYMENT.md

diff --git a/README.md b/README.md
index 87481a0..c40539e 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,8 @@ CUDA, model downloads on startup, GPU access or Docker socket.**
 
 This is the first web preview. Real Athena generation still needs an integration
 check; it is not yet a fully equivalent replacement for every desktop feature.
+Athena installation and operation: [deployment guide](docs/ATHENA_DEPLOYMENT.md).
+
 See [limitations and architecture](docs/ARCHITECTURE.md) and [provenance](docs/PROVENANCE.md).
 
 ## Debian / Docker deployment
diff --git a/deploy/compose.athena.yaml b/deploy/compose.athena.yaml
new file mode 100644
index 0000000..cc843f8
--- /dev/null
+++ b/deploy/compose.athena.yaml
@@ -0,0 +1,13 @@
+# Optional Athena override: host loopback reaches Deck without changing its networks.
+# This GUI alone uses host networking and binds exclusively to 127.0.0.1.
+services:
+  ltx-deskweb:
+    container_name: ltx-deskweb
+    network_mode: host
+    ports: !reset []
+    extra_hosts: !reset []
+    environment:
+      HOST: 127.0.0.1
+      LTX_BACKEND_URL: http://127.0.0.1:8120
+    cpus: 2
+    mem_limit: 1g
diff --git a/docs/ATHENA_DEPLOYMENT.md b/docs/ATHENA_DEPLOYMENT.md
new file mode 100644
index 0000000..32cab41
--- /dev/null
+++ b/docs/ATHENA_DEPLOYMENT.md
@@ -0,0 +1,61 @@
+# Athena deployment
+
+Deployment directory: `/opt/ltx-deskweb/source` on `192.168.1.212`.
+Container: `ltx-deskweb`. Image: `ltx-deskweb:0.1.0`.
+
+The additional `deploy/compose.athena.yaml` uses host networking **only for this
+frontend**, binds its web server to `127.0.0.1:8118`, and connects to Deck at
+`http://127.0.0.1:8120`. This avoids changing Deck's existing network or relying on
+its current Docker IP. No Docker socket, GPU devices or inference packages are
+mounted into the GUI. CPU and RAM limits: 2 CPUs / 1 GiB.
+
+Filtered Deck inventory labels:
+
+- `io.athena-deck.managed=true`
+- `io.athena-deck.role=application`
+
+Media mounts:
+
+- `/data/video/ltx-desktop/LTXDesktop/remote-inputs/deskweb` → writable inputs.
+  A new isolated directory owned by UID/GID 1000; no recursive permission changes.
+- `/data/video/ltx-desktop/LTXDesktop/outputs` → read-only outputs.
+
+Backend-visible input path: `/data/LTXDesktop/remote-inputs/deskweb`.
+The GUI and LTX backend see the same files through different bind mounts.
+
+Credentials are outside Git in `source/secrets`. The Deck token is the existing
+configured client token; it was not changed. GUI password is independently
+randomized. Host secret files are readable only by UID 1000/root. If the Deck token
+is rotated later, replace `secrets/ltx-token` and restart only the GUI container.
+Never place secret contents in commands, Git, logs or screenshots.
+
+## Access
+
+From the Mac:
+
+```sh
+ssh -i /Users/mike_i386/.ssh/athena_key -o BatchMode=yes \
+  -o ExitOnForwardFailure=yes -N -L 8118:127.0.0.1:8118 root@192.168.1.212
+```
+
+Open `http://127.0.0.1:8118`. This is a tunnel to the container on Athena, not a Mac
+application instance. PUBLIC_ORIGIN is set to this exact URL. For a different URL,
+configure the origin accordingly. No WireGuard or firewall changes were made.
+
+Local private copy of the GUI password:
+`LTX-DeskWEB/secrets/web-password` (ignored by Git, mode 0600).
+
+## Operation on Athena
+
+```sh
+cd /opt/ltx-deskweb/source
+docker compose -p ltx-deskweb -f compose.yaml -f deploy/compose.athena.yaml up -d --no-deps ltx-deskweb
+# Stop only this UI:
+docker compose -p ltx-deskweb -f compose.yaml -f deploy/compose.athena.yaml stop ltx-deskweb
+# Restart only this UI after changing its private configuration:
+docker compose -p ltx-deskweb -f compose.yaml -f deploy/compose.athena.yaml restart ltx-deskweb
+```
+
+The GUI is available in LLM mode but reports that LTX is not ready. Activate Video
+mode in Athena Deck when you want to generate. Deploying or starting this GUI does
+not switch GPU mode or start the LTX model/backend.
diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md
index 19a1331..8d03ce7 100644
--- a/docs/VALIDATION.md
+++ b/docs/VALIDATION.md
@@ -21,3 +21,15 @@ No Athena service was started, stopped or reconfigured during this port.
 The synthetic fixture uses a fixed public test password and isolated temporary
 media storage on loopback port 18118. Never deploy that fixture as the real service.
 Production start (`server/index.mjs`) requires an operator-provided password file.
+
+## Athena deployment — 2026-09-29
+
+Docker image built successfully on Athena (Debian), including TypeScript and Vite
+checks. `ltx-deskweb` starts with UID 1000, read-only root filesystem, no GPU or
+Docker socket, 2 CPUs / 1 GiB limit, host-loopback binding on 8118.
+
+Verified: GUI HTTP 200; login/session/logout; forwarding to Deck's health endpoint;
+synthetic text upload and readback through shared input storage (test file removed);
+Deck's actual Unix-socket helper inventory returns `ltx-deskweb` as `running`.
+Existing Medium, TTS, WireGuard and Deck remain running; LTX remains stopped.
+Real video generation was not requested or tested in this deployment.