Containr/docs/guides/OPERATIONS.md

# Operations

Day-2 features for running services: scheduled jobs, ad-hoc exec, managed
databases, preview environments, security scans, and high availability.

## Cron jobs

Service detail → **Cron**. Standard 5-field cron expressions (`robfig/cron`
syntax), per-job timezone, enable/disable, manual trigger, and execution
history with captured stdout/stderr.

- The scheduler ticks every minute and runs due jobs via `docker exec`
  (`sh -c <command>`) inside the service's container.
- Executions are retained per-job (`retention` count) and visible in the UI.
- Requires a running container — a stopped service's due job records a
  failure, it does not queue.

```
GET/POST /api/v1/cron-jobs            PUT/DELETE /api/v1/cron-jobs/:id
POST     /api/v1/cron-jobs/:id/trigger
GET      /api/v1/cron-jobs/:id/executions
```

## Exec console

Service detail → **Console**. One-off `sh -c` commands against the running
container: 30s ceiling, 64KB output cap, exit code + captured output shown
per run. Debugging aid — not an interactive shell.

```
POST /api/v1/services/:id/exec  {command}
```

## Managed databases

**/databases** page — provision PostgreSQL/Redis/MySQL/MariaDB/MongoDB/
ClickHouse/Dragonfly as managed containers on the `containr` network.

- Start/stop/restart actions; connection URL with copy.
- **Backups**: manual snapshot now, or set a cron expression
  (`backup_schedule`) — due backups run inside the same scheduler tick as
  cron jobs. Archives live in the `containr-db-backups` volume and are
  downloadable (`GET /databases/:id/backups/:bid/download`) and restorable.
- **Bind to service**: injects `connection_url` into a service's variables
  as a secret (`DATABASE_URL` by default). Redeploy the service afterward —
  variables are read at deploy time.

## Preview environments

Service detail → **Previews**. Create a preview per branch/PR with a TTL,
promote it to production, or delete it.

Current limitation: previews are bookkeeping records — they do not build,
deploy, or route a real container. The generated `*.preview.containr.local`
URL is a placeholder. Real preview runtime is tracked on the roadmap.

## Security scans

**/security** page — pick a project, run a scan (dependency / configuration
/ comprehensive, optionally scoped to one service).

The scanner is heuristic config analysis, not Trivy/Grype: it flags
unpinned image tags, `http://` source/public URLs, `npm install` without
`npm ci`, `pip install` without hashes, `curl|sh` build steps, missing
health checks, and similar smells. Findings get severity badges and can be
resolved or ignored; the page also shows a security score, open/resolved
counts, scan history, and compliance status.

```
POST /api/v1/security/scans     {project_id, service_id?, scan_type}
GET  /api/v1/projects/:id/vulnerabilities
PUT  /api/v1/vulnerabilities/:id          {status: open|resolved|ignored}
GET  /api/v1/projects/:id/security/metrics
GET  /api/v1/projects/:id/security/history
```

## High availability

**/ha** page — manager enable/disable, node/health-check/alert status
cards, manual failover (with confirmation), per-service failover policies
(project → service picker, strategy, min healthy nodes, max failures),
active alerts with resolve, and health check results.

HA state is in-memory like autoscaling — policies and alerts reset on
backend restart.

## Node agents

**/usage** page → *Connect node*: issue a per-node token (`cagt_…`, shown
once), copy the prefilled install command, revoke tokens when done. Agents
register over `POST /api/agents/register` and heartbeat via
`POST /api/agents/heartbeat`.

## Personal access tokens

**Settings → Personal Access Tokens**: issue `cnp_…` bearer tokens for the
CLI, MCP server, and scripts — the same privileges as your account, bounded
by scope. The raw token is shown once at creation; only its SHA-256 hash is
stored.

Scopes:

- `read` — `GET`/`HEAD`/`OPTIONS` only; mutations return `403 SCOPE_INSUFFICIENT`.
- `write` — everything except admin routes.
- `admin` — full access; requires a platform admin account, and the token is
  still capped at the owner's privileges.

A token can never outrank its owner: non-admin scopes report
`is_admin = false` even on admin accounts.

```
GET    /api/v1/user/tokens            list (metadata only, never hashes)
POST   /api/v1/user/tokens            {name, scope?, expires_in_days?} → raw token once
DELETE /api/v1/user/tokens/:id        revoke (owner-scoped)
```

Use as `Authorization: Bearer cnp_…`, or `containr auth login cnp_…`.
Revocation takes effect on the next request; `last_used_at` updates on each
authenticated call.

## Deployment queue

Deployments are serialized per service: a deploy while another is active
lands in `queued` state and promotes when it finishes — deploys, rollbacks,
redeploys, and variable-apply reconciles can never race on the same service.
`POST /deployments/:id/cancel` drops queued work or aborts running builds.
Rows left in-flight by a server restart are marked `failed` on boot.
Webhook-triggered deploys build with `no_cache` by default.

## Secret variables

Variables with `is_secret` are AES-GCM-encrypted at rest (`enc:v1:` prefix).
Key derivation: `SECRETS_KEY` env var if set, else `JWT_SECRET`. Existing
plaintext secrets are encrypted on boot; reads for deploy/exec decrypt
transparently. Rotating the key makes stored secrets unreadable — re-save
them after rotation.