docs: record the UI cutover and the archie-ui deployment story
- ui-service-boundary.md: the /api/captures|/mappings|/bindings row is resolved by the cutover; archie-ui composes the store contracts and mounts the captureintake receiver. - event-capture-storage.md HTTP surface: the receiver mounts on the one process serving the dashboard; work intake stays with the daemon. - config.example.toml: [web].listen is the archie-ui process's bind address; [capture] is projected by archie-ui. - deployments: document running archie-ui alongside the other services and add its systemd unit; capabilities comments updated for the single-serving composition.
This commit is contained in:
1 parent
27bc40332f
commit
27bdb53596
8 files changed
+90
-25
No files matched your search
+3
-2
@@ -38,7 +38,7 @@ See `docs/architecture/organisation.md` for the target structure and
|
||||
| `internal/store/` | Task store interface and SQLite implementation; RPC clients proxy it |
|
||||
| `internal/events/` | In-process event bus: publish/subscribe for observability |
|
||||
| `internal/infrastructure/` | Config loading, eventbus transport, model catalog |
|
||||
| `internal/webui/` | SSE dashboard: live event stream, task status |
|
||||
| `internal/webui/` | Shared dashboard HTTP layer served by the archie-ui process |
|
||||
| `internal/gateway/` (18.7k LOC) | Persistent-connection layer between archie and its users (Telegram, web UI, etc.); shared CommandRouter for dispatch |
|
||||
| `internal/tools/` (20.9k LOC) | Central tool subsystem: built-in tool implementations, approval, execution contract |
|
||||
| `internal/memory/` (7k LOC) | Pluggable memory provider architecture |
|
||||
@@ -247,7 +247,8 @@ Daemon-level TOML (`~/.config/archie/config.toml`):
|
||||
- `[nats]` -- embedded or external broker deployment
|
||||
- `[containers]` -- managed `archie-agent` image, limits, storage, and network
|
||||
- `[budgets]` -- max steps, max tokens, wall clock, gate max failures
|
||||
- `[web]` -- dashboard listen address
|
||||
- `[web]` -- dashboard listen address, bound by the standalone archie-ui
|
||||
process (the daemon runs no dashboard listener after the UI cutover)
|
||||
- `[notify]` -- webhook URL for notifications
|
||||
|
||||
Secrets (forge token, provider API keys, channel tokens) are not embedded in
|
||||
|
||||
+12
-2
@@ -196,10 +196,14 @@ class = "ollama"
|
||||
listen = "127.0.0.1:8485"
|
||||
|
||||
# Web dashboard and API: task board, activity stream, chat, config,
|
||||
# logs, memory, SSE events. Served as an embedded SPA with a full REST
|
||||
# memory, SSE events. Served as an embedded SPA with a full REST
|
||||
# and streaming API. Auth is token-based for non-loopback addresses;
|
||||
# loopback binds (127.0.0.1, ::1, localhost) skip auth automatically.
|
||||
# Set to "off" (or leave empty) to disable.
|
||||
#
|
||||
# From the UI cutover (archie-core-8cda.5.4) the dashboard is served by the
|
||||
# standalone archie-ui process, not by archied: this listen address is what
|
||||
# archie-ui binds, and archied runs no dashboard listener at all. Run
|
||||
# `archie-ui -config <same config.toml>` alongside the other services.
|
||||
[web]
|
||||
listen = "127.0.0.1:8484"
|
||||
# Trust X-Forwarded-Proto and X-Forwarded-Host headers when validating Origin
|
||||
@@ -313,6 +317,12 @@ gate_max_failures = 5
|
||||
# fan-out/replay machinery, and SQLite is available in every deployment
|
||||
# shape unconditionally. All fields default when the section is absent;
|
||||
# capture is on by default.
|
||||
#
|
||||
# From the UI cutover (archie-core-8cda.5.4) the receiver is mounted by the
|
||||
# archie-ui process, which projects these same values from this file; the
|
||||
# daemon's binding-dispatch loop consumes captures from the shared State
|
||||
# Store. Leave this section here even if you do not edit it: both processes
|
||||
# read it.
|
||||
# [capture]
|
||||
# retention = "168h" # 7 days; prune-on-write deletes anything older
|
||||
# max_events = 5000 # row cap, pruned on every insert regardless of age
|
||||
|
||||
@@ -35,6 +35,7 @@ Edit API keys in `~/.config/archie/env` or directly in `config.toml`, then launc
|
||||
```bash
|
||||
archie-gateway -config ~/.config/archie/config.toml -listen 127.0.0.1:8585 &
|
||||
archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090 &
|
||||
archie-ui -config ~/.config/archie/config.toml &
|
||||
archied -config ~/.config/archie/config.toml
|
||||
# or via systemd:
|
||||
systemctl --user start archied
|
||||
@@ -55,6 +56,25 @@ Docker bridge gateway address plus a matching bearer token (`target_token` /
|
||||
`--token` / `STATE_STORE_TOKEN`), because a container cannot reach the host's
|
||||
loopback.
|
||||
|
||||
## Running the dashboard
|
||||
|
||||
The dashboard is served by the standalone UI Service (`archie-ui`), not by
|
||||
`archied` (UI cutover, `archie-core-8cda.5.4`; `docs/prds/ui-service-boundary.md`).
|
||||
It reads the same `config.toml`, dials the Gateway and State Store targets
|
||||
already configured there, and binds `[web].listen` (`127.0.0.1:8484` by
|
||||
default). Start it after the Gateway and the State Store:
|
||||
|
||||
```bash
|
||||
archie-ui -config ~/.config/archie/config.toml
|
||||
```
|
||||
|
||||
A non-loopback `[web].listen` requires a dashboard token (`-token`, or
|
||||
`-token-file` to mint and persist one); a loopback bind needs none.
|
||||
`archied` runs no dashboard listener at all, so webhook capture
|
||||
(`POST /webhooks/capture/{source}`) is received by archie-ui and the
|
||||
binding-dispatch loop in `archied` consumes what arrives from the shared
|
||||
State Store.
|
||||
|
||||
```bash
|
||||
# loopback (host-only agent)
|
||||
archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090
|
||||
|
||||
@@ -71,7 +71,33 @@ WantedBy=default.target
|
||||
|
||||
---
|
||||
|
||||
## 2. Enabling User Linger (`loginctl`)
|
||||
## 2. UI Service Unit (`~/.config/systemd/user/archie-ui.service`)
|
||||
|
||||
The dashboard is served by the standalone UI Service, not by `archied`
|
||||
(UI cutover, `archie-core-8cda.5.4`). It reads the same `config.toml`, dials
|
||||
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);
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Archie UI Service
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=%h/.local/bin/archie-ui -config %h/.config/archie/config.toml
|
||||
EnvironmentFile=-%h/.config/archie/env
|
||||
Restart=on-failure
|
||||
RestartSec=5s
|
||||
|
||||
[Install]
|
||||
WantedBy=default.target
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Enabling User Linger (`loginctl`)
|
||||
|
||||
By default, systemd terminates user services when you log out of SSH. Enabling **linger** allows your `archied` service to run continuously 24/7 across reboots and logouts:
|
||||
|
||||
@@ -87,7 +113,7 @@ loginctl show-user "$USER" | grep Linger
|
||||
|
||||
---
|
||||
|
||||
## 3. Service Commands
|
||||
## 4. Service Commands
|
||||
|
||||
Reload systemd daemon files:
|
||||
```bash
|
||||
@@ -96,7 +122,7 @@ systemctl --user daemon-reload
|
||||
|
||||
Enable and start the service immediately:
|
||||
```bash
|
||||
systemctl --user enable --now archie-gateway archied
|
||||
systemctl --user enable --now archie-gateway archie-ui archied
|
||||
```
|
||||
|
||||
Check service status:
|
||||
@@ -117,7 +143,7 @@ systemctl --user stop archied
|
||||
|
||||
---
|
||||
|
||||
## 4. Default: Native Daemon, Embedded NATS, Managed Containers
|
||||
## 5. Default: Native Daemon, Embedded NATS, Managed Containers
|
||||
|
||||
Embedded NATS is the default. The systemd service runs `archied` natively, so
|
||||
interactive chat keeps the host access the operator configured, while every
|
||||
@@ -158,7 +184,7 @@ fall back to a host model loop.
|
||||
|
||||
---
|
||||
|
||||
## 5. Pinning the archie-agent Image
|
||||
## 6. Pinning the archie-agent Image
|
||||
|
||||
`ghcr.io/samcharles93/archie-agent:latest` is a moving target: every push to
|
||||
`main` that touches the runtime's package closure re-publishes it (see
|
||||
@@ -197,7 +223,7 @@ check. A custom image reference is therefore supported directly in
|
||||
`config.toml`; `ARCHIE_AGENT_IMAGE` is only an override for deployments that
|
||||
cannot make that configuration file available to the update command.
|
||||
|
||||
## 5. Optional: External Compose NATS
|
||||
## 7. Optional: External Compose NATS
|
||||
|
||||
External NATS changes only broker deployment. It does not change the worker
|
||||
executor. Start the optional service and configure the pinned Compose gateway:
|
||||
|
||||
@@ -113,6 +113,13 @@ dashboard in a given deployment; no new port/host config surface is added,
|
||||
and no new claim about public reachability is made beyond what already
|
||||
exists for the dashboard.
|
||||
|
||||
Amended 2026-09-10 by the UI cutover (`archie-core-8cda.5.4`): the one
|
||||
process serving the dashboard is now the standalone archie-ui service, so
|
||||
the receiver mounts there, composed from the UI process's own State Store
|
||||
client. The binding-dispatch loop that turns captures into tasks stays in
|
||||
the daemon, consuming the same store, so the HTTP front door moved without
|
||||
moving work intake.
|
||||
|
||||
`GET` listing/inspection endpoints (`t2db.2`) stay behind `requireToken` like
|
||||
every other `/api/*` route -- captured payloads are visible only to an
|
||||
authenticated operator, per the security decision's point 5 visibility rule.
|
||||
|
||||
@@ -66,7 +66,7 @@ cutover.
|
||||
| `/api/tasks/*`, `/api/workflows`, `/api/setup` | State Store read/action contracts plus an explicit execution/admin action contract | State Store adapter exists; UI-facing narrow surface remains |
|
||||
| `/events` | State Store `EventsSince`, polled by one UI-process pump feeding `Server.Broadcast` | RESOLVED (`archie-core-za9f`): see migration-decisions, "Dashboard live event delivery". No new RPC; replay cursor and drop-recovery are the existing `since` watermark in `sse.go` |
|
||||
| `/api/logs`, `/api/logs/stream` | daemon diagnostic feed, host-local | unresolved: `logging.Feed` is in-process on the daemon host and has no contract |
|
||||
| `/api/captures`, `/api/mappings`, `/api/bindings` | State Store contracts, with webhook verification owned by Work Intake/Messaging | local adapter exists; remote UI surface remains to define |
|
||||
| `/api/captures`, `/api/mappings`, `/api/bindings` | State Store contracts, with webhook verification owned by Work Intake/Messaging | RESOLVED (cutover, `archie-core-8cda.5.4`): the UI process composes CaptureStore/MappingStore/BindingStore and mounts the `captureintake.Receiver` from its own State Store client; the daemon's binding-dispatch loop keeps consuming captures from the same store |
|
||||
| `/api/config` (read) | daemon-published `ConfigView` snapshot, read over the State Store contract | RESOLVED (`archie-core-ymut`): see migration-decisions, "Dashboard configuration page" |
|
||||
| `/api/config` (write), `/api/config/reset`, `/api/config/repos/*` | none; descoped for Phase 3 | RESOLVED (`archie-core-ymut`): 503 in the UI process, SPA hides the controls, editing is config.toml plus reload |
|
||||
| `/api/channels`, reload, curators, memory, skills, version/update | owning capability contract or an explicitly removed route | owner and failure semantics remain to define |
|
||||
|
||||
@@ -5,18 +5,18 @@ import "net/http"
|
||||
// handleCapabilities reports which dashboard sections this process can
|
||||
// actually serve.
|
||||
//
|
||||
// The dashboard is served by two different compositions: the daemon, which
|
||||
// holds every runtime handle, and the UI process, which holds two remote
|
||||
// contracts and nothing else. Sections whose capability lives only in the
|
||||
// daemon still answer -- with an empty list, a "disabled" marker, or a 501 --
|
||||
// and the page cannot tell that apart from a deployment where nothing has
|
||||
// happened yet. Rather than have every page guess, the server says which
|
||||
// sections it can back, and the browser hides the rest.
|
||||
// The dashboard is served by the extracted UI process, which holds two remote
|
||||
// contracts (Gateway ChatContract and the State Store) and nothing else.
|
||||
// Sections whose capability lives only in the daemon still answer -- with an
|
||||
// empty list, a "disabled" marker, or a 501 -- and the page cannot tell that
|
||||
// apart from a deployment where nothing has happened yet. Rather than have
|
||||
// every page guess, the server says which sections it can back, and the
|
||||
// browser hides the rest.
|
||||
//
|
||||
// A section is reported available when the handle behind it is wired, which
|
||||
// is the same condition its handler already uses to decide between real data
|
||||
// and its degraded answer. Sections backed by the task store are absent from
|
||||
// this list: the store is mandatory in both compositions.
|
||||
// this list: the store is mandatory.
|
||||
func (s *Server) handleCapabilities(w http.ResponseWriter, _ *http.Request) {
|
||||
writeJSON(w, map[string]any{
|
||||
"sections": map[string]bool{
|
||||
|
||||
@@ -1,11 +1,12 @@
|
||||
// Which dashboard sections the serving process can actually back.
|
||||
//
|
||||
// The dashboard is served by two compositions: the daemon, which holds every
|
||||
// runtime handle, and the extracted UI service, which holds two remote
|
||||
// contracts. A section with nothing behind it still answers -- an empty list,
|
||||
// a "disabled" marker, a 501 -- and the browser cannot tell that from a quiet
|
||||
// deployment. GET /api/capabilities says which sections are backed here, and
|
||||
// the nav drops the rest (archie-core-8cda.5.4).
|
||||
// From the UI cutover the dashboard is served by one composition: the
|
||||
// extracted UI service, which holds two remote contracts (Gateway ChatContract
|
||||
// and the State Store) and no daemon runtime handles. A section with nothing
|
||||
// behind it still answers -- an empty list, a "disabled" marker, a 501 -- and
|
||||
// the browser cannot tell that from a quiet deployment. GET /api/capabilities
|
||||
// says which sections are backed here, and the nav drops the rest
|
||||
// (archie-core-8cda.5.4).
|
||||
|
||||
// hiddenRoutes returns the paths whose section the server reported it cannot
|
||||
// serve. An unreported section stays visible: a page that says "unavailable"
|
||||
|
||||
Reference in new issue
Block a user