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>
59 lines
2.0 KiB
Desktop File
59 lines
2.0 KiB
Desktop File
[Unit]
|
|
Description=cleveragents controller — worker instance %i
|
|
Documentation=file:///etc/cleveragents/RUNBOOK.md
|
|
After=network-online.target postgresql.service opencode.service
|
|
Wants=network-online.target
|
|
# Template unit. Enable per-instance via:
|
|
# systemctl enable --now cleveragents-controller-worker@implementer-1
|
|
# systemctl enable --now cleveragents-controller-worker@reviewer-1
|
|
# %i becomes the worker's role-pool identifier. The same env file
|
|
# (with CLEVERAGENTS_WORKER_ROLES_%i override) configures which roles
|
|
# this instance dequeues.
|
|
|
|
[Service]
|
|
Type=simple
|
|
User=cleveragents
|
|
Group=cleveragents
|
|
WorkingDirectory=/opt/cleveragents-core
|
|
EnvironmentFile=/etc/cleveragents/worker.env
|
|
# Per-instance override file (optional): /etc/cleveragents/worker.%i.env
|
|
# overrides anything in worker.env for this specific instance.
|
|
EnvironmentFile=-/etc/cleveragents/worker.%i.env
|
|
|
|
# CLEVERAGENTS_WORKER_ROLES is read from env (default = all 5 roles).
|
|
# Per-instance env files override it to specialize pools — e.g. for
|
|
# instance "implementer-1" set CLEVERAGENTS_WORKER_ROLES=implementer
|
|
# in /etc/cleveragents/worker.implementer-1.env.
|
|
ExecStart=/opt/cleveragents-core/.venv/bin/python -m tools.controller.worker \
|
|
--opencode-url=${CONTROLLER_OPENCODE_URL} \
|
|
--log-level=${CONTROLLER_LOG_LEVEL}
|
|
|
|
KillSignal=SIGTERM
|
|
TimeoutStopSec=60s
|
|
# Longer than master because in-flight attempts get a graceful
|
|
# heartbeat-driven stop (worker waits for current attempt to finish
|
|
# OR for its TTL to pass).
|
|
Restart=always
|
|
RestartSec=10s
|
|
RestartPreventExitStatus=2
|
|
|
|
LimitNOFILE=8192
|
|
|
|
# Hardening
|
|
NoNewPrivileges=true
|
|
PrivateTmp=true
|
|
ProtectSystem=strict
|
|
ProtectHome=true
|
|
ReadWritePaths=/var/lib/cleveragents /var/log/cleveragents /tmp
|
|
# Workers spawn per-attempt MCP subprocesses; need /tmp writable.
|
|
ProtectKernelTunables=true
|
|
ProtectKernelModules=true
|
|
ProtectControlGroups=true
|
|
|
|
StandardOutput=journal
|
|
StandardError=journal
|
|
SyslogIdentifier=cleveragents-worker-%i
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|