From dd2d3db1b227252e7bf561cfeed37796e55e87b4 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 10 Sep 2026 01:13:46 +1000 Subject: [PATCH] docs(deploy): UI Service deployment, auth, and operations profiles Bead archie-core-8cda.5.5: - task dev now runs archie-ui (dev:dashboard) on :8484 -- after the cutover archied binds no dashboard listener, and Vite's /api,/events proxy needs a live receiver there. dev:mobile starts archie-ui with a LAN bind and -token-file (reusing the pre-cutover token path) instead of a mobile archied overlay; dev:ui's summary points at archie-ui. - deployments/dev.toml documents itself as the archie-ui overlay and states the [services.gateway] target explicitly. - systemd-user-service.md: the auth gap is now the documented posture -- archie-ui has no secret registry, resolves GATEWAY_TOKEN/ STATE_STORE_TOKEN from its process environment only, so the starter (EnvironmentFile) exports them; worked env-file example added, plus /healthz as the token-free liveness probe. - INSTRUCTIONS.md ships five binaries with archie-ui in the quickstart and the token story; README.md carries the auth note; the docker-nats-stack profile notes archie-ui binds [web] and dials the same [services.*] targets. - release tooling: archied's component closure extends with cmd/archie-ui and internal/app/archieui, so a UI-process-only commit can no longer fall between the two changelogs; RELEASING.md documents that the UI Service ships inside the archied release. --- RELEASING.md | 21 +++++++---- Taskfile.yml | 54 +++++++++++++++++++--------- deployments/INSTRUCTIONS.md | 39 +++++++++++++------- deployments/README.md | 6 ++++ deployments/dev.toml | 22 ++++++++++-- deployments/docker-nats-stack.toml | 3 ++ deployments/single-forge-github.toml | 3 +- deployments/systemd-user-service.md | 30 ++++++++++++++++ tools/release.sh | 12 ++++++- ui/vite.config.js | 6 ++-- 10 files changed, 154 insertions(+), 42 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 74a22b0ee..72adc62d6 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -5,6 +5,14 @@ Two components, independently versioned: `archied` (gateway/daemon) and `CHANGELOG.md` / `CHANGELOG.archied.md` / `CHANGELOG.archie.md` document the split — see those for what each component actually is. +The UI Service (`archie-ui`) is not a third component: it ships inside the +`archied` release, versioned by the same `archied/vX.Y.Z` tag. It shares +`internal/webui` (dashboard HTTP layer, embedded SPA) with the daemon, so the +two move together; `tools/release.sh` extends archied's `go list -deps` +closure with `cmd/archie-ui` and `internal/app/archieui` for exactly this +reason — without them a commit touching only the UI process would land in +neither changelog. + ## The standing rule **Only version a component that actually has unreleased commits touching its @@ -18,12 +26,13 @@ just because the other one moved, and do not bundle a large unrelated backlog into a release "because it's due" — that's a separate release, on its own review pass, not a rider on this one. -In practice: most sessions touch `archied` (webui, gateway, daemon, chat) and -leave `archie-agent` (the per-task sandboxed runtime) untouched, so most -releases are gateway-only with `RUNTIME=skip`. Don't ask whether to skip an -untouched component — skip it, and say so in the handoff. Only ask when the -runtime genuinely has unreleased changes and there's a real judgment call -about whether to bundle a large pre-existing backlog in or cut it separately. +In practice: most sessions touch `archied` (webui, gateway, daemon, chat, +archieui) and leave `archie-agent` (the per-task sandboxed runtime) +untouched, so most releases are gateway-only with `RUNTIME=skip`. Don't ask +whether to skip an untouched component — skip it, and say so in the handoff. +Only ask when the runtime genuinely has unreleased changes and there's a +real judgment call about whether to bundle a large pre-existing backlog in +or cut it separately. Note that a runtime code change (e.g. something in `internal/app/agentworker`) being *merged to `main`* is not the same as it being *in production* — the diff --git a/Taskfile.yml b/Taskfile.yml index bd7768501..b655086e7 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -89,32 +89,42 @@ tasks: - npm test dev: - desc: "Develop: archied live-reload + archie-gateway + archie-state-store + Vite HMR together. Open http://localhost:5173" + desc: "Develop: archied live-reload + archie-gateway + archie-state-store + archie-ui + Vite HMR together. Open http://localhost:5173" summary: | Runs the dev loop in one terminal: * air rebuilds and restarts archied on Go changes * archie-gateway serves ChatContract on 127.0.0.1:8585 (archied - dials it for chat; it does not embed a gateway) + and archie-ui dial it; neither embeds a gateway) * archie-state-store owns archie.db on 127.0.0.1:9090, loopback, - no token (deployments/dev.toml); both archied and - archie-gateway dial it -- neither owns the DB - in-process (docs/prds/state-store-contract.md §12 - step 7) + no token (deployments/dev.toml); archied, + archie-gateway and archie-ui dial it -- none owns + the DB in-process + (docs/prds/state-store-contract.md §12 step 7) + * archie-ui serves the dashboard on 127.0.0.1:8484 from the + embedded dist (deployments/dev.toml). After the + UI cutover (archie-core-8cda.5.4) archied runs no + dashboard listener: this is what :8484 is. * vite serves the dashboard with hot reload on :5173, - proxying /api and /events through to archied on :8484 + proxying /api and /events through to archie-ui + on :8484 Open http://localhost:5173 -- not :8484. The Vite server is the one with hot reload; :8484 serves the last built dist/ and will look stale. - Ctrl-C stops all four. - deps: [dev:daemon, dev:gateway, dev:state-store, dev:ui] + Ctrl-C stops all five. + deps: [dev:daemon, dev:gateway, dev:state-store, dev:dashboard, dev:ui] dev:daemon: desc: archied only, live-reloading via air (prefer `task dev`) cmds: - air -build.args_bin="-config-overlay,deployments/dev.toml" + dev:dashboard: + desc: archie-ui only, no live-reload (prefer `task dev`) + cmds: + - go run ./cmd/archie-ui -config-overlay deployments/dev.toml + dev:state-store: desc: archie-state-store only, no live-reload (prefer `task dev`) cmds: @@ -126,7 +136,7 @@ tasks: - go run ./cmd/archie-gateway dev:ui: - desc: Vite dev server only, expects archied already running (prefer `task dev`) + desc: Vite dev server only, expects archie-ui already running (prefer `task dev`) dir: ui cmds: - npm install --no-audit --no-fund @@ -135,21 +145,31 @@ tasks: dev:mobile: desc: Serve the dashboard on your LAN (token-protected) for phone viewing summary: | - Starts archied with the [web] bind on 0.0.0.0 so the dashboard is - reachable from your phone, printing the URL (LAN IP + token) and a QR - code to scan. Stop `task dev` first: both use port 8484, and two daemons - sharing the bot identity would double-poll the forge. Frontend served is - the embedded dist, so run `task ui` if you changed the frontend. + Starts archie-ui with a LAN-reachable [web] bind and a minted dashboard + token, printing the URL (LAN IP + token) and a QR code to scan. After + the UI cutover the dashboard is archie-ui's process: this task starts + archie-ui only. Run the daemon separately (task dev, or archied) for + actual archie operation -- two daemons sharing the bot identity would + double-poll the forge. + + The frontend served is the embedded dist, so run `task ui` if you + changed the frontend. The token file is the path archied used to mint + before the cutover, so an existing phone setup keeps its token. deps: - ui cmds: - cmd: | IP=$(hostname -I | awk '{print $1}') - TOKEN=$(cat "${XDG_DATA_HOME:-$HOME/.local/share}/archie/web-token" 2>/dev/null) + TOKEN_FILE="${XDG_DATA_HOME:-$HOME/.local/share}/archie/web-token" + go run ./cmd/archie-ui -listen 0.0.0.0:8484 -token-file "$TOKEN_FILE" & + UI_PID=$! + sleep 2 + TOKEN=$(cat "$TOKEN_FILE" 2>/dev/null) URL="http://$IP:8484/?t=$TOKEN" echo "Phone URL: $URL" echo "$URL" | qrencode -t ANSIUTF8 - - go run ./cmd/archied -config-overlay ~/.config/archie/mobile.toml + trap "kill $UI_PID 2>/dev/null" EXIT + wait $UI_PID build: desc: Build archie services and agent binaries diff --git a/deployments/INSTRUCTIONS.md b/deployments/INSTRUCTIONS.md index 76005e31d..d86a4f804 100644 --- a/deployments/INSTRUCTIONS.md +++ b/deployments/INSTRUCTIONS.md @@ -1,12 +1,17 @@ # Running this distribution -This archive contains four linux/amd64 binaries: +This archive contains five linux/amd64 binaries: - **`archied`** — the resident daemon: polls your forge for assigned issues - and dispatches them into sandboxed `archie-agent` containers. + and dispatches them into sandboxed `archie-agent` containers. It serves no + dashboard: the web UI is `archie-ui`'s process (UI cutover, + `archie-core-8cda.5.4`). +- **`archie-ui`** — serves the operator dashboard and the webhook capture + receiver, dialing the Gateway and State Store gRPC contracts. Reads only + `[services.*]`, `[web]` and `[capture]` from the shared `config.toml`. - **`archie-gateway`** — serves the chat (`ChatContract`) surface `archied` - dials for Telegram/webhook chat. Runs as its own process; `archied` never - embeds a gateway. + and `archie-ui` dial for Telegram/webhook chat. Runs as its own process; + `archied` never embeds a gateway. - **`archie-state-store`** — owns the single `archie.db` SQLite file behind a gRPC contract. `archied` and `archie-gateway` are gRPC clients of it, not owners of the database. @@ -35,15 +40,25 @@ as a host binary. Pull it from GHCR: `ghcr.io/samcharles93/archie-agent`. providers) and place any secrets in `~/.config/archie/env` or referenced `secret://` locations. -3. Start the three processes, in order (`archie-state-store` and - `archie-gateway` first — `archied` dials both at startup): +3. Start the four processes, in order (`archie-state-store` and + `archie-gateway` first — `archied` and `archie-ui` dial both at startup): ```bash ./archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090 & - ./archie-gateway -config ~/.config/archie/config.toml -listen 127.0.0.1:8585 & - ./archied -config ~/.config/archie/config.toml + ./archie-gateway -config ~/.config/archie/config.toml -listen 127.0.0.1:8585 & + ./archie-ui -config ~/.config/archie/config.toml & + ./archied -config ~/.config/archie/config.toml ``` + Dashboard reachability comes from `[web].listen` (default + `127.0.0.1:8484`, which needs no dashboard token). For a non-loopback + bind pass `-listen` with `-token` or `-token-file` to mint and persist + one. `archie-ui` reads `GATEWAY_TOKEN` / `STATE_STORE_TOKEN` from its + process environment only — it has no secret registry, so when those + tokens live in a secret manager, whatever starts `archie-ui` must export + them into its environment (the `[services.*].target_token` values in + `config.toml` are the other supported source). + 4. For a persistent, 24/7 deployment instead of a foreground run, follow the systemd user-unit runbook: . @@ -57,7 +72,7 @@ playbooks directory before pointing `archied` at it. ## Version This archive's binaries are built from the `archied` release tag in its -filename; `archie-gateway`, `archie-state-store`, and `archie-playbooks` -ship at that same version rather than being independently tagged (see -`RELEASING.md` in the source repository for why only `archied` and -`archie-agent` are independently versioned). +filename; `archie-ui`, `archie-gateway`, `archie-state-store`, and +`archie-playbooks` ship at that same version rather than being independently +tagged (see `RELEASING.md` in the source repository for why only `archied` +and `archie-agent` are independently versioned). diff --git a/deployments/README.md b/deployments/README.md index f19f188e6..2783b6446 100644 --- a/deployments/README.md +++ b/deployments/README.md @@ -75,6 +75,12 @@ A non-loopback `[web].listen` requires a dashboard token (`-token`, or binding-dispatch loop in `archied` consumes what arrives from the shared State Store. +Auth note: unlike `archied`, archie-ui has no secret registry -- +`GATEWAY_TOKEN`/`STATE_STORE_TOKEN` resolve from its process environment +only (or from `[services.*].target_token` in `config.toml`), so whatever +starts archie-ui must export those tokens into its environment. See the UI +Service unit in `systemd-user-service.md` for the worked example. + ```bash # loopback (host-only agent) archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090 diff --git a/deployments/dev.toml b/deployments/dev.toml index 41b006050..0e21a71e6 100644 --- a/deployments/dev.toml +++ b/deployments/dev.toml @@ -1,10 +1,26 @@ +# Development overlay for `task dev` and `task dev:dashboard`. +# # Match Vite's API/event proxy without changing the installed configuration. +# After the UI cutover (archie-core-8cda.5.4) the dashboard on :8484 is the +# archie-ui process's listener, not archied's; this overlay is what both +# `go run ./cmd/archied -config-overlay deployments/dev.toml` and +# `go run ./cmd/archie-ui -config-overlay deployments/dev.toml` read. Only +# [web], [services.*] and [capture] land in archie-ui; the daemon ignores +# [web] entirely. + [web] listen = "127.0.0.1:8484" # `task dev` also runs archie-state-store on its -listen default -# (127.0.0.1:9090, loopback, no token) via dev:state-store -- point archied -# and archie-gateway at it so a fresh dev checkout works without hand-editing -# the installed config.toml (docs/prds/state-store-contract.md §12 step 7). +# (127.0.0.1:9090, loopback, no token) via dev:state-store -- point archied, +# archie-gateway and archie-ui at it so a fresh dev checkout works without +# hand-editing the installed config.toml +# (docs/prds/state-store-contract.md §12 step 7). [services.state] target = "127.0.0.1:9090" + +# `task dev` runs archie-gateway on its -listen default (127.0.0.1:8585, +# loopback, no token). Stated explicitly so the value archie-ui dials is +# visible next to the State Store one. +[services.gateway] +target = "127.0.0.1:8585" \ No newline at end of file diff --git a/deployments/docker-nats-stack.toml b/deployments/docker-nats-stack.toml index d640086ed..4f286540c 100644 --- a/deployments/docker-nats-stack.toml +++ b/deployments/docker-nats-stack.toml @@ -74,6 +74,9 @@ max_uptime = "60m" pull_policy = "missing" [web] +# Bound by the archie-ui process (the host-run dashboard after the UI +# cutover, archie-core-8cda.5.4); it dials the [services.*] targets above -- +# the bridge-gateway State Store address works from the host too. listen = "127.0.0.1:8484" # Trust X-Forwarded-Proto when fronted by a reverse proxy (e.g. Traefik) # terminating TLS so dashboard mutations succeed with external HTTPS Origin. diff --git a/deployments/single-forge-github.toml b/deployments/single-forge-github.toml index a2fadf06a..ce12a1ab9 100644 --- a/deployments/single-forge-github.toml +++ b/deployments/single-forge-github.toml @@ -14,7 +14,8 @@ bot_email = "archie-bot@users.noreply.github.com" diff_cap_lines = 400 # The Gateway Service owns conversational state and serves ChatContract over -# gRPC. Run archie-gateway alongside archied with this address. +# gRPC. Run archie-gateway alongside archied and archie-ui (the dashboard +# process dials it too) with this address. [services.gateway] target = "127.0.0.1:8585" diff --git a/deployments/systemd-user-service.md b/deployments/systemd-user-service.md index 967a9728a..e8e94515b 100644 --- a/deployments/systemd-user-service.md +++ b/deployments/systemd-user-service.md @@ -79,6 +79,21 @@ the Gateway and State Store targets already in it, and binds `[web].listen`. A non-loopback bind requires a dashboard token (`-token`, or `-token-file` to mint and persist one); +**Auth note (deliberate design, `archie-core-8cda.5.5`):** unlike `archied`, +`archie-ui` has no secret registry — it resolves `GATEWAY_TOKEN` and +`STATE_STORE_TOKEN` from its **process environment only** (or from the +`target_token` values in `config.toml`). Whatever starts `archie-ui` is +therefore responsible for exporting those tokens into its environment: keep +them in `~/.config/archie/env` (loaded by the `EnvironmentFile` line below), +not only in a secret manager. A deployment that authenticates `archied` +through bws/Vault but exports nothing for `archie-ui` leaves the dashboard +unable to dial its dependencies. + +For supervision, `GET /healthz` on `[web].listen` is the process's liveness +probe (token-free by design); the authenticated readiness surface lives at +the dashboard's health endpoint behind the token. A watchdog can curl +`/healthz` without credentials. + ```ini [Unit] Description=Archie UI Service @@ -95,6 +110,21 @@ RestartSec=5s WantedBy=default.target ``` +Concretely, for a deployment whose dependency tokens live outside +`config.toml`, `~/.config/archie/env` carries the two names and the unit +loads it; the dashboard token itself comes from `-token-file` (there is no +environment variable for it): + +```bash +# ~/.config/archie/env +GATEWAY_TOKEN=... # presented to archie-gateway +STATE_STORE_TOKEN=... # presented to archie-state-store +``` + +```ini +ExecStart=%h/.local/bin/archie-ui -config %h/.config/archie/config.toml -token-file %h/.local/share/archie/web-token +``` + --- ## 3. Enabling User Linger (`loginctl`) diff --git a/tools/release.sh b/tools/release.sh index 674e06118..5ab660a60 100755 --- a/tools/release.sh +++ b/tools/release.sh @@ -145,7 +145,17 @@ release_component() { } release_component "archied" "$GATEWAY_VERSION" "archied" \ - "CHANGELOG.archied.md" "./cmd/archied" "cmd/archied" "Dockerfile.archied" + "CHANGELOG.archied.md" "./cmd/archied" "cmd/archied" "Dockerfile.archied" \ + "cmd/archie-ui" "internal/app/archieui" + +# The UI Service ships with the archied release on purpose: archie-ui shares +# internal/webui (the dashboard HTTP layer and the embedded SPA assets) with +# archied, so the two are versioned together -- an archied/vX.Y.Z tag carries +# the dashboard and the daemon that publishes its configuration snapshot. +# The two lines above extend archied's component closure with archie-ui's +# own packages, so a commit touching only archieui cannot fall between +# changelogs; it would otherwise land in neither (go list -deps from +# ./cmd/archied does not include internal/app/archieui). release_component "archie-agent" "$RUNTIME_VERSION" "archie" \ "CHANGELOG.archie.md" "./cmd/archie-agent" "cmd/archie-agent" "Dockerfile" diff --git a/ui/vite.config.js b/ui/vite.config.js index 5d0c57785..8801326c2 100644 --- a/ui/vite.config.js +++ b/ui/vite.config.js @@ -1,7 +1,8 @@ import { defineConfig } from "vite"; import preact from "@preact/preset-vite"; -// The dashboard is served from the archied binary, so the build output is a +// The dashboard is served from the archie-ui binary (and, for the snapshot +// renderer only, still linked by archied), so the build output is a // committed dist/ that ui/embed.go embeds. Hashed asset names are avoided: // dist/ lives in git, and hashed filenames would leave a new orphan on every // rebuild rather than overwriting the previous one. @@ -20,7 +21,8 @@ export default defineConfig({ }, }, server: { - // `npm run dev` proxies the API to a locally running archied so the + // `npm run dev` proxies the API to a locally running archie-ui (the + // process that serves the dashboard after the UI cutover) so the // dashboard can be developed without rebuilding the Go binary. proxy: { "/api": "http://127.0.0.1:8484",