Skip to content

Operations

Cursor Agent edited this page Sep 2, 2026 · 5 revisions

Operations

Day-two extras on top of Deployment. Spec: docs/operations.md.

Prometheus metrics

GET /metrics on the HTTP port (outside /api/v1). Open by default; set METRICS_TOKEN to require Authorization: Bearer <token>. Firewall it to your monitoring network.

- job_name: croncompose
  static_configs:
    - targets: ["control-plane:8080"]
  metrics_path: /metrics
Metric Type Reads as
cc_http_requests_total counter REST traffic (method, path template, status)
cc_http_request_duration_seconds histogram
cc_agents_connected gauge Agents with an open stream. First sign of a network problem
cc_runs_total counter status label
cc_run_duration_seconds histogram 0.5s–2h buckets
cc_run_log_bytes_total counter Bytes received, including those the cap dropped
cc_log_subscribers gauge Live SSE viewers
cc_connector_operations_total counter op, status
cc_notifications_total counter kind, outcome. Rising failed means alerts are not arriving
cc_retention_deleted_total counter table. Flat after configuring a window means the pruner is not running
go_*, process_* Go runtime

Alert first on cc_agents_connected dropping below fleet size, and cc_notifications_total{outcome="failed"} rising — that failure hides every other failure.

OIDC SSO

Set the OIDC_* env vars on the control plane:

Variable Purpose
OIDC_ISSUER_URL e.g. https://login.example.com. Discovery at startup
OIDC_CLIENT_ID Client id
OIDC_CLIENT_SECRET Omit for public clients
OIDC_REDIRECT_URL https://cc.example.com/api/v1/auth/oidc/callback
OIDC_DEFAULT_ROLE First SSO login. Default viewer

Flow: /auth/oidc/start → IdP → /auth/oidc/callback (state cookie, code exchange, id_token, email+name claims). Missing users are auto-provisioned with an empty password hash (SSO-only). Session cookie is set; browser redirects to / or saved next.

The login page reads /auth/config and shows “Sign in with SSO” when enabled. Password login keeps working.

Agent packaging

On tag v*, CI builds for linux/amd64 and linux/arm64:

croncompose-agent-linux-amd64
croncompose-agent-linux-arm64
croncompose-agent_<version>_<arch>.deb
croncompose-agent_<version>_<arch>.apk
SHA256SUMS-<arch>.txt

Each package:

  • Installs /usr/local/bin/croncompose-agent
  • Installs systemd unit /lib/systemd/system/croncompose-agent.service
  • Drops /etc/croncompose/agent.env.example
  • Postinstall creates croncompose system user and /var/lib/croncompose (0700)
  • Preremove stops + disables the service

The unit hardens the runtime: NoNewPrivileges, ProtectSystem=full, ProtectHome=true, PrivateTmp=true.

One-off without apt/apk: scripts/install-agent.sh (also writes sudoers for ss/lsof on Linux when missing).

Agent socket inspection (Ports page)

Since v0.0.3, the Ports page needs the agent to run ss or lsof with enough privilege to see process IDs on listen sockets. Unprivileged ss -p often omits them.

Install Agent user What to do
install-agent.sh croncompose Sudoers created at install
Source / pm2 (e.g. Raspberry Pi) pi or your login user Add sudoers manually
# example: source install, agent runs as pi
sudo tee /etc/sudoers.d/croncompose-agent <<'EOF'
pi ALL=(root) NOPASSWD: /usr/bin/ss, /usr/bin/lsof
EOF
sudo chmod 0440 /etc/sudoers.d/croncompose-agent
sudo visudo -c
sudo -n ss -H -lntp | head

Use which ss lsof if paths differ. After upgrading the agent binary, restart it (pm2 restart croncompose-agent or systemctl restart croncompose-agent).

Process management (source install)

ecosystem.config.js is the process list. croncompose-ctl.sh wraps pm2:

./croncompose-ctl.sh status | logs web | restart | stop | start | boot
Process Starts when
croncompose-control-plane always
croncompose-web CC_ENABLE_WEB != 0 and the standalone bundle exists
croncompose-agent CC_ENABLE_AGENT=1 and $CC_RUNTIME_DIR/agent/identity.json exists

Logs: $CC_RUNTIME_DIR/logs/<process>.{out,err}.log (default .run/logs). Add pm2-logrotate for rotation.

Clone this wiki locally