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.
This commit is contained in:
1 parent
fa1d3ee27d
commit
dd2d3db1b2
10 files changed
+154
-42
No files matched your search
+15
-6
@@ -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
|
||||
|
||||
+37
-17
@@ -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
|
||||
|
||||
+27
-12
@@ -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:
|
||||
<https://github.com/samcharles93/archie-core/blob/main/deployments/systemd-user-service.md>.
|
||||
@@ -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).
|
||||
@@ -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
|
||||
|
||||
+19
-3
@@ -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"
|
||||
@@ -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.
|
||||
|
||||
@@ -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"
|
||||
|
||||
|
||||
@@ -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`)
|
||||
|
||||
+11
-1
@@ -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"
|
||||
|
||||
+4
-2
@@ -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",
|
||||
|
||||
Reference in new issue
Block a user