generated from coulomb/repo-seed
tegwick
5a7a6ef5ee
Expose POST /consistency/sweep/remote-all so activity-core can trigger the workstation ADR-001 remote-all sweep via the bridge tunnel pattern. Records consistency_sweep_remote_all progress events and documents the cutover runbook while the local custodian-sync timer remains interim.
122 lines
3.9 KiB
Markdown
122 lines
3.9 KiB
Markdown
# 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.
|
|
|
|
---
|
|
|
|
## Periodic Repo Sync — systemd user timer
|
|
|
|
The **State Hub consistency sync** timer (legacy unit name `custodian-sync`)
|
|
runs `consistency_check.py --remote --all` every 15 minutes, keeping workplan
|
|
file state in sync with the state-hub DB automatically (belt-and-suspenders
|
|
alongside the per-repo git post-commit hooks).
|
|
|
|
> **Interim local runner (STATE-WP-0063):** units must target the standalone
|
|
> repo at `/home/worsch/state-hub` and invoke consistency via
|
|
> `/home/worsch/.local/bin/uv run python …`. The pre-extraction path
|
|
> `/home/worsch/the-custodian/state-hub` is obsolete.
|
|
>
|
|
> **Cluster runner (STATE-WP-0064):** activity-core on Railiance01 can
|
|
> trigger the same sweep through `POST /consistency/sweep/remote-all` via
|
|
> the `consistency_sweep_remote_all` context query. Keep this local timer
|
|
> enabled during the parallel week; disable it after cutover per
|
|
> [`docs/consistency-sweep-runbook.md`](../docs/consistency-sweep-runbook.md).
|
|
|
|
The all-repo remote sweep has two built-in load guards:
|
|
|
|
- A nonblocking process lock at `/tmp/custodian-consistency-remote-all.lock`;
|
|
if a prior sweep is still active, the next timer run exits cleanly.
|
|
- A wall-clock budget, defaulting to 300 seconds. Remaining repos are skipped
|
|
once the budget is exhausted. Override with `--max-seconds N` or set
|
|
`CONSISTENCY_REMOTE_ALL_MAX_SECONDS`.
|
|
- Warn-only sweeps exit 0 in `--remote --all` mode so the systemd unit only
|
|
goes failed for hard consistency failures.
|
|
|
|
### Unit files
|
|
|
|
| File | Repo template | Installed copy |
|
|
|------|---------------|----------------|
|
|
| `custodian-sync.service` | `infra/systemd/custodian-sync.service` | `~/.config/systemd/user/custodian-sync.service` |
|
|
| `custodian-sync.timer` | `infra/systemd/custodian-sync.timer` | `~/.config/systemd/user/custodian-sync.timer` |
|
|
|
|
Install or refresh from the repo templates:
|
|
|
|
```bash
|
|
mkdir -p ~/.config/systemd/user
|
|
cp ~/state-hub/infra/systemd/custodian-sync.service ~/.config/systemd/user/
|
|
cp ~/state-hub/infra/systemd/custodian-sync.timer ~/.config/systemd/user/
|
|
systemctl --user daemon-reload
|
|
systemctl --user enable --now custodian-sync.timer
|
|
```
|
|
|
|
### Management commands
|
|
|
|
```bash
|
|
# Check status
|
|
systemctl --user status custodian-sync.timer
|
|
systemctl --user list-timers custodian-sync.timer
|
|
|
|
# View recent logs
|
|
journalctl --user -u custodian-sync.service -n 50
|
|
|
|
# Trigger immediately (for testing)
|
|
systemctl --user start custodian-sync.service
|
|
|
|
# Disable
|
|
systemctl --user disable --now custodian-sync.timer
|
|
|
|
# Re-enable
|
|
systemctl --user enable --now custodian-sync.timer
|
|
```
|
|
|
|
### Guard condition
|
|
|
|
The service uses `ExecStartPre` to check the API is reachable before running:
|
|
```
|
|
ExecStartPre=/usr/bin/curl -sf http://127.0.0.1:8000/state/health
|
|
```
|
|
If the API is offline, the service exits cleanly without error (the timer will retry
|
|
in 15 minutes).
|
|
|
|
### WSL2 note
|
|
|
|
systemd user mode works in WSL2 when `systemd=true` is set in `/etc/wsl.conf`.
|
|
If systemd is not available, fall back to crontab:
|
|
|
|
```bash
|
|
# Crontab fallback (run crontab -e and add):
|
|
*/15 * * * * curl -sf http://127.0.0.1:8000/state/health && cd ~/state-hub && /home/worsch/.local/bin/uv run python scripts/consistency_check.py --remote --all >> /tmp/custodian-sync.log 2>&1
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|
|
in the background so it does not block the commit.
|