Operations

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

The default installer does not ask for SSO. Use --advanced (or edit .env after install):

./install/install.sh --advanced

Put the application client id and secret in when prompted (or set the env vars below and restart).

Variable	Purpose
OIDC_ISSUER_URL	e.g. https://gitlab.com or https://login.example.com. Discovery at startup
OIDC_CLIENT_ID	Application / client id
OIDC_CLIENT_SECRET	Application secret. Omit for public clients
OIDC_REDIRECT_URL	Register https://<host>/api/v1/auth/oidc/callback with the IdP. Derived from PUBLIC_BASE_URL if unset
OIDC_DEFAULT_ROLE	First SSO login. Default viewer

GitLab Applications work as OIDC. GitHub OAuth Apps / GitHub Apps do not.

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. Installers configure this automatically via install/lib/agent_sudoers.sh:

Install	Agent user	Sudoers
./install/install.sh	user running pm2	prompted during install
sudo ./install/systemd-setup.sh	service unit user	at setup
scripts/install-agent.sh	croncompose	at install
.deb / .apk	croncompose	postinstall
./update.sh	pm2 user when CC_ENABLE_AGENT=1	after restart

Refresh manually:

sudo ./install/lib/agent_sudoers.sh <agent-user>

Verify: sudo -n ss -H -lntp | head should show users:(("name",pid=...)) on listen lines.

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.