2026-03-16 01:41:16 +01:00
|
|
|
# State Hub Infrastructure
|
|
|
|
|
|
|
|
|
|
## Docker (PostgreSQL)
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# Start postgres (required for API)
|
|
|
|
|
make db
|
|
|
|
|
|
|
|
|
|
# Start postgres + pgadmin
|
|
|
|
|
make db-tools
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The compose file is `infra/docker-compose.yml`. Copy `.env.example` to `.env` and set
|
|
|
|
|
`POSTGRES_PASSWORD` before starting.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
2026-06-22 01:20:59 +02:00
|
|
|
## Periodic Repo Sync — activity-core (Railiance01)
|
2026-05-06 04:04:53 +02:00
|
|
|
|
2026-06-22 01:20:59 +02:00
|
|
|
The **State Hub consistency sync** runs every 15 minutes (`*/15 * * * *` UTC)
|
|
|
|
|
on activity-core (Railiance01). The cluster schedule triggers
|
|
|
|
|
`POST /consistency/sweep/remote-all` on the workstation State Hub via the
|
|
|
|
|
`actcore-state-hub-bridge` tunnel.
|
2026-03-16 01:41:16 +01:00
|
|
|
|
2026-06-22 01:20:59 +02:00
|
|
|
Operator runbook: [`docs/consistency-sweep-runbook.md`](../docs/consistency-sweep-runbook.md).
|
2026-03-16 01:41:16 +01:00
|
|
|
|
2026-06-22 01:20:59 +02:00
|
|
|
**Prerequisites for cluster-triggered sweeps:**
|
2026-03-16 01:41:16 +01:00
|
|
|
|
2026-06-22 01:20:59 +02:00
|
|
|
- Workstation State Hub API running (`make api` or equivalent)
|
|
|
|
|
- `state-hub-railiance01` ops-bridge tunnel `connected`
|
|
|
|
|
- Workstation awake (execution still runs locally; only scheduling moved)
|
2026-03-16 01:41:16 +01:00
|
|
|
|
2026-06-22 01:20:59 +02:00
|
|
|
Per-repo git post-commit hooks remain the immediate consistency path after
|
|
|
|
|
each commit. The 15-minute sweep is belt-and-suspenders across all registered
|
|
|
|
|
repos.
|
2026-03-16 01:41:16 +01:00
|
|
|
|
2026-06-22 01:20:59 +02:00
|
|
|
The all-repo remote sweep has built-in load guards:
|
2026-03-16 01:41:16 +01:00
|
|
|
|
2026-06-22 01:20:59 +02:00
|
|
|
- A nonblocking process lock at `/tmp/custodian-consistency-remote-all.lock`;
|
|
|
|
|
overlapping triggers exit cleanly with `lock_skipped: true`.
|
|
|
|
|
- A wall-clock budget, defaulting to 300 seconds. Remaining repos are skipped
|
|
|
|
|
once the budget is exhausted.
|
2026-03-16 01:41:16 +01:00
|
|
|
|
2026-06-22 01:20:59 +02:00
|
|
|
### Retired local timer
|
2026-03-16 01:41:16 +01:00
|
|
|
|
2026-06-22 01:20:59 +02:00
|
|
|
The legacy `custodian-sync.{service,timer}` systemd units were disabled
|
|
|
|
|
2026-06-21 (`STATE-WP-0064`). Archived templates live in
|
|
|
|
|
[`infra/systemd/archived/`](systemd/archived/). Do not re-enable unless
|
|
|
|
|
debugging a cluster scheduling outage.
|
2026-03-16 01:41:16 +01:00
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Post-commit hooks
|
|
|
|
|
|
|
|
|
|
Each registered repo can have a custodian sync hook installed that triggers
|
|
|
|
|
`fix-consistency` automatically after every commit:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# Install into one repo
|
|
|
|
|
make install-hooks REPO=marki-docx
|
|
|
|
|
|
|
|
|
|
# Install into all active registered repos
|
|
|
|
|
make install-hooks-all
|
|
|
|
|
|
|
|
|
|
# Remove from one repo
|
|
|
|
|
make remove-hooks REPO=marki-docx
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The hook is idempotent (guarded by `# custodian-sync-hook` marker) and runs
|
2026-06-22 01:20:59 +02:00
|
|
|
in the background so it does not block the commit.
|
