# Concelier Alpine SecDB Connector - Operations Runbook

_Last updated: 2025-12-22_

## 1. Overview
The Alpine connector pulls JSON secdb feeds (main/community) for configured
releases and maps CVE identifiers to APK version ranges. It preserves native
APK versions and emits `rangeKind: apk` so downstream consumers keep distro
semantics intact.

## 2. Configuration knobs (`concelier.yaml`)
```yaml
concelier:
  sources:
    alpine:
      baseUri: "https://secdb.alpinelinux.org/"
      releases:
        - "v3.18"
        - "v3.19"
        - "v3.20"
      repositories:
        - "main"
        - "community"
      maxDocumentsPerFetch: 20
      fetchTimeout: "00:00:45"
      requestDelay: "00:00:00"
      userAgent: "StellaOps.Concelier.Alpine/0.1 (+https://stella-ops.org)"
```

### Recommendations
- Keep `releases` to supported Alpine branches only; avoid stale branches in
  production unless you maintain a mirror.
- Use `requestDelay` when running multiple source connectors on shared egress.

## 3. Default job schedule

| Job kind | Cron | Timeout | Lease |
|----------|------|---------|-------|
| `source:alpine:fetch` | `*/30 * * * *` | 5 minutes | 4 minutes |
| `source:alpine:parse` | `7,37 * * * *` | 6 minutes | 4 minutes |
| `source:alpine:map` | `12,42 * * * *` | 8 minutes | 4 minutes |

The cadence staggers fetch, parse, and map so each stage has a clean window to
complete. Override via `concelier.jobs.definitions[...]` when coordinating
multiple sources on the same scheduler.

## 4. Offline and air-gapped deployments
- Mirror `secdb` JSON files into a local repository and point `baseUri` to the
  mirror host.
- The connector allowlists only the `baseUri` host; update it to match the
  internal mirror host.
- Keep fixtures and exported bundles deterministic by leaving the order of
  releases and repositories stable.