vh
8a4276d6b5
skaldsong-dev surfaced three contract corrections before the first deploy: - WORLDTREE_TOKEN (outbound HTTP Bearer) was missing — separate code path from SKALDSONG_BIFROST_JWT_KEY (inbound HS256 verify) but same secret value. - WORLDTREE_BASE_URL replaces SKALDSONG_WORLDTREE_API_URL (the former is what the app actually reads). - SKALDSONG_HOST_WIZARD_AGENT_ID was missing entirely — must pin to skaldsong:wizard-v2 to inherit the existing Worldtree agent slot; blank would burn another slot of the 50-per-key Heimdall quota.
125 lines
5.8 KiB
Markdown
125 lines
5.8 KiB
Markdown
# skaldsong
|
|
|
|
Wizard + reader surface for multi-agent storytelling. Single FastAPI
|
|
process serves both the SvelteKit-built SPA (static, baked into the
|
|
image) and the wizard backend. Talks to Worldtree as a Bifrost
|
|
consumer — Worldtree issues per-dispatch JWTs (post-v0.3) that
|
|
skaldsong's `/bifrost` endpoint verifies against the shared HS256
|
|
secret.
|
|
|
|
**Server:** ana-docker
|
|
**URL:** `http://10.250.50.70:8300` (configurable via `.env`)
|
|
**Upstream repo:** [vh/skaldsong](https://gitea.phasefinal.com/vh/skaldsong)
|
|
**Image:** `gitea.phasefinal.com/vh/skaldsong:<sha>` — built + pushed
|
|
by vh/skaldsong's CI on every push to `main` and on tag.
|
|
|
|
## Path layout (on ana-docker)
|
|
|
|
| Host path | Container path | Purpose | Restic? |
|
|
|---|---|---|---|
|
|
| `/opt/docker/compose/skaldsong/` | — | compose.yaml + .env | included (via `/opt/docker`) |
|
|
| `/opt/docker/conf/skaldsong/db/` | `/app/state/db` | SQLite (`skaldsong-ui.db` + WAL/SHM) — wizard state, story rows | **included** |
|
|
| `/opt/docker/conf/skaldsong/runs/` | `/app/state/runs` | Per-story generation pipeline artifacts (spec, state, output, logs, manuscripts) | **included** |
|
|
|
|
## Network model
|
|
|
|
Internal tooling, LAN-only. Container's :8000 published on host
|
|
:8300 (configurable via `SKALDSONG_BIND` / `SKALDSONG_PORT`); access
|
|
direct at `http://10.250.50.70:8300`. No Traefik, no TLS terminator,
|
|
no public hostname.
|
|
|
|
Skaldsong talks to two services on the LAN:
|
|
|
|
- **Worldtree** at `http://10.250.50.152:8080` (corviduo-dev,
|
|
LAN-direct from ana-docker — same subnet).
|
|
- **Kokoro TTS** at `http://10.100.79.3:8193` (irv-ml1, reached via
|
|
the WireGuard tunnel on ana-wg — same path asset-engine uses).
|
|
|
|
Worldtree calls back to skaldsong's `/bifrost` endpoint at
|
|
`http://10.250.50.70:8300` for tool-dispatch — that URL must be in
|
|
Worldtree's `BIFROST_CLIENT_ALLOWED_HOSTS`. Host:port changes
|
|
require a coordinated allowlist update on Worldtree-side (see
|
|
[corviduo-dev README](../../servers/corviduo-dev/README.md) for
|
|
the docker-as-root edit pattern).
|
|
|
|
## Deploy
|
|
|
|
Two paths — automated (preferred) and manual (escape hatch).
|
|
|
|
### Automated (Gitea Actions, push-to-main)
|
|
|
|
vh/skaldsong ships `.gitea/workflows/deploy.yaml`. Push to main +
|
|
manual `workflow_dispatch` triggers:
|
|
|
|
1. Build + push `gitea.phasefinal.com/vh/skaldsong:${{ github.sha }}`
|
|
and `:latest` to the gitea registry.
|
|
2. Checkout this management repo using `MGMT_REPO_TOKEN`.
|
|
3. Run `scripts/elway ana-docker --playbook
|
|
playbooks/deploy-skaldsong.yaml --var ref=${{ github.sha }}` via
|
|
`DEPLOY_SSH_KEY`.
|
|
|
|
Three secrets required on vh/skaldsong's Actions settings:
|
|
- `DEPLOY_SSH_KEY` — private key authorized on ana-docker for lkraven.
|
|
- `MGMT_REPO_TOKEN` — Gitea PAT with `read:repository` on this repo.
|
|
- `REGISTRY_USER` + `REGISTRY_TOKEN` — for the docker login step
|
|
(token needs `write:package` scope).
|
|
|
|
### Manual (elway from a workstation)
|
|
|
|
```bash
|
|
# Deploy a specific SHA (CI just pushed it):
|
|
scripts/elway ana-docker --playbook playbooks/deploy-skaldsong.yaml \
|
|
--var ref=<sha>
|
|
|
|
# Or pin to a release tag:
|
|
scripts/elway ana-docker --playbook playbooks/deploy-skaldsong.yaml \
|
|
--var ref=v0.1.0
|
|
```
|
|
|
|
## Env-var contract
|
|
|
|
| Var | In compose? | In `.env`? | Notes |
|
|
|---|---|---|---|
|
|
| `SKALDSONG_IMAGE` | ✓ (image:) | ✓ | Full image URI; CI passes SHA-pin via elway `--var ref=<sha>` → playbook → this var. |
|
|
| `SKALDSONG_PORT` | ✓ | ✓ | Host-side port (8300 default). Internal always 8000. |
|
|
| `SKALDSONG_BIND` | ✓ | ✓ | Host bind address (0.0.0.0 default). |
|
|
| `SKALDSONG_DB_DIR` | ✓ (mount) | ✓ | Host path for SQLite. |
|
|
| `SKALDSONG_RUNS_DIR_HOST` | ✓ (mount) | ✓ | Host path for generation artifacts. |
|
|
| `SKALDSONG_BIFROST_JWT_KEY` | ✓ (anchor) | ✓ | Shared HS256 secret w/ Worldtree's `WORLDTREE_SKALDSONG_USER_KEY`. Same value as `WORLDTREE_TOKEN`. |
|
|
| `SKALDSONG_HOST_BIFROST_ENDPOINT_URL` | ✓ (anchor) | ✓ | URL Worldtree calls back to (must match allowlist). |
|
|
| `WORLDTREE_TOKEN` | ✓ (anchor) | ✓ | Bearer for outbound HTTP to Worldtree. Same value as `SKALDSONG_BIFROST_JWT_KEY`. |
|
|
| `WORLDTREE_BASE_URL` | ✓ (anchor) | ✓ | URL skaldsong calls Worldtree at. |
|
|
| `SKALDSONG_HOST_WIZARD_AGENT_ID` | ✓ (anchor) | ✓ | Existing agent slot ID (`skaldsong:wizard-v2`). Blank burns a Heimdall quota slot on first boot. |
|
|
| `SKALDSONG_HOST_CORS_ORIGINS` | ✓ (anchor) | ✓ | Comma-separated CORS origins. |
|
|
| `SKALDSONG_TTS_ENGINE` | ✓ (anchor) | ✓ | `kokoro` (only engine in v1). |
|
|
| `SKALDSONG_TTS_BASE_URL` | ✓ (anchor) | ✓ | Kokoro URL (WG-routed). |
|
|
|
|
`&skaldsong-env` anchor declares all `SKALDSONG_*` vars via `${VAR:-}`
|
|
substitution. Same env-anchor pattern as Worldtree's `&worldtree-env`
|
|
(see [Worldtree #175 heuristic](https://gitea.phasefinal.com/vh/worldtree/issues/175));
|
|
new var additions must land in BOTH the `.env` AND the anchor.
|
|
|
|
## Restart semantics
|
|
|
|
Per skaldsong's `INV-006` (host CLAUDE.md): process restart marks any
|
|
`running` generation rows `partial` and never auto-resumes. Deploy
|
|
mid-run is safe — the SPA's reader treats partials like a power
|
|
outage. Cancellation of in-flight runs on deploy is acceptable for
|
|
v1.
|
|
|
|
`docker compose up -d --force-recreate --pull always` is the
|
|
playbook's apply step (or `--pull never` when called with a specific
|
|
`--var ref=<sha>` where the image was pre-pulled). Same kill-signal +
|
|
graceful-shutdown pattern as Worldtree.
|
|
|
|
## Worldtree allowlist coordination
|
|
|
|
The `SKALDSONG_HOST_BIFROST_ENDPOINT_URL` value MUST be in Worldtree's
|
|
`BIFROST_CLIENT_ALLOWED_HOSTS` env var on corviduo-dev. As of
|
|
deploy-time the value is `10.250.50.70:8300`.
|
|
|
|
If you change `SKALDSONG_PORT` or move skaldsong off ana-docker, the
|
|
allowlist needs a paired update on corviduo-dev. Reference: the
|
|
edit-via-docker-as-root pattern in
|
|
[servers/corviduo-dev/README.md](../../servers/corviduo-dev/README.md#permissions-model--the-docker-as-root-pattern).
|