drew
a19b609554
Deployment surface for the controller. Operators copy the unit files
+ env examples to /etc/, customize, and `systemctl enable --now`.
Layout (under tools/controller/deploy/):
- systemd/cleveragents-controller-master.service — master singleton.
One unit per (owner, repo); plan v9 singleton constraint enforced
by deployment.
- systemd/cleveragents-controller-worker@.service — worker template.
`systemctl enable cleveragents-controller-worker@implementer-1`
spins up one instance; scale by adding instances. Per-instance
env override at /etc/cleveragents/worker.<inst>.env (optional)
specialises CLEVERAGENTS_WORKER_ROLES per instance.
- systemd/master.env.example — every env var the master reads,
documented. Copy to /etc/cleveragents/master.env, mode 0640.
- systemd/worker.env.example — every env var the workers read.
- RUNBOOK.md — operator guide:
* Prereqs (Linux + systemd 245+, Python 3.13 + uv, Postgres 14+,
OpenCode server, dedicated cleveragents user).
* First-time setup (7 ordered steps from useradd to first PR).
* Day-to-day ops (where logs live, healthy queries, role pool
sizing, label-based pause, clean restart).
* Incident response (6 named scenarios: STUCK workflows, MERGING
retry exhaustion, no-OpenCode, dequeue starvation, DB loss,
operator-unstick procedure).
* Migration playbook (Phase 2: opt one PR in via label,
monitor controller_events, escalate to full management).
* Tunables cheat sheet covering all 8 env vars + their tradeoffs.
- README.md — index linking the above.
Hardening on both units: NoNewPrivileges, PrivateTmp,
ProtectSystem=strict, ProtectHome, narrow ReadWritePaths, kernel
+ control-group protections. RestartPreventExitStatus=2 prevents
systemd loop-restart on misconfiguration (exit 2 = bad env).
No code changes; verified via `systemd-analyze verify` (unit syntax
parses; only "venv path doesn't exist on dev host" warnings, which
are expected). Test suite: 569/569 pass, 0 regressions.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
46 lines
2.5 KiB
Bash
46 lines
2.5 KiB
Bash
# cleveragents controller — master EnvironmentFile
|
|
# Copy to /etc/cleveragents/master.env (mode 0640, owned by cleveragents:cleveragents)
|
|
# then customize for your deployment.
|
|
|
|
# ─── identity (REQUIRED) ──────────────────────────────────────────
|
|
# The (owner, repo) this master singleton manages. Plan v9 enforces
|
|
# one master process per (owner, repo). Run a second master unit for
|
|
# a second repo.
|
|
OWNER=cleveragents
|
|
REPO=cleveragents-core
|
|
|
|
# ─── infrastructure (REQUIRED) ────────────────────────────────────
|
|
# Postgres URL for the controller DB. The application creates the
|
|
# schema on first run; the DB user must have CREATE on this database.
|
|
# For local dev only: sqlite:///./controller.db (NOT multi-machine
|
|
# safe; production MUST use Postgres).
|
|
CLEVERAGENTS_DB_URL=postgresql+psycopg2://cleveragents:CHANGEME@db.internal:5432/cleveragents_controller
|
|
|
|
# OpenCode server URL. Master doesn't actually invoke OpenCode (the
|
|
# workers do); this is logged at startup for operator visibility.
|
|
CONTROLLER_OPENCODE_URL=http://opencode.internal:4096
|
|
|
|
# Forgejo connection — read by ForgejoCfg in tools/_mcp_common.py
|
|
# (the existing pipeline shares this config; reuse it here for now).
|
|
FORGEJO_URL=https://git.cleverthis.com
|
|
FORGEJO_TOKEN=CHANGEME-forgejo-pat
|
|
FORGEJO_USER=cleveragents-bot
|
|
|
|
# ─── opt-in label (Phase 1k) ──────────────────────────────────────
|
|
# Only PRs/issues carrying this label are managed by the controller.
|
|
# Default is 'controller-managed'. To disable the gate entirely, add
|
|
# --no-opt-in-label to the ExecStart line in the unit file.
|
|
CONTROLLER_OPT_IN_LABEL=controller-managed
|
|
|
|
# ─── cadences ─────────────────────────────────────────────────────
|
|
# Tick interval — how often the state-machine + scheduler run.
|
|
CONTROLLER_MASTER_TICK_INTERVAL_S=30
|
|
# Reaper interval — how often stale-heartbeat in_progress attempts
|
|
# are reset to pending.
|
|
CONTROLLER_REAPER_INTERVAL_S=60
|
|
# Reconciliation interval — how often the DB ↔ Forgejo sync runs.
|
|
CONTROLLER_RECONCILIATION_INTERVAL_S=300
|
|
|
|
# ─── logging ──────────────────────────────────────────────────────
|
|
CONTROLLER_LOG_LEVEL=INFO
|