Operations
This is the operational knowledge base behind Fjord. Running managed Forgejo well is our business, so the problems we solve become content here: runbooks, how-tos, and deep dives. Each page is seeded from something we hit and fixed in production, written so you can apply the same pattern even if you run your own forge.
These pages describe how Fjord operates the platform and the patterns we recommend. Where a value is specific to your deployment (budgets, retention, lock keys), treat what you read here as a starting point rather than a setting to copy verbatim.
Runbooks
| Runbook | What it covers |
|---|---|
| Runner autoscaling | How CI compute scales to demand, the cost controls that bound it, and why the autoscaler never holds a forge admin credential. |
| Leader-only background workers | Electing a single active worker with a Postgres advisory lease, and the transaction-pooler trap that silently gives you two leaders. |
| Supply-chain CI gate | Blocking on advisories, licenses, and sources with cargo-audit and cargo-deny, plus safe artifact and cache handling (tar traversal, digest verification). |
| Migrating repositories into a managed forge | Planning a team or bulk cutover, mirror-then-switch, and verifying the move before you point tooling at the new home. |
How we capture a new runbook
The point of this section is not the four pages below; it is the habit. Every operational problem we solve is a candidate doc. The process is deliberately small so it actually happens:
- Trigger on the fix. When an incident, a support thread, or a piece of build-out resolves an operational question, that is the trigger to write.
- Capture while it is fresh. Draft within a few days, before the context evaporates and the “obvious” details stop being obvious.
- Use the same shape. State the problem, explain how the thing works, name the failure mode plainly, give the controls or the fix, then say how to verify. The failure mode is the most valuable part; do not skip it.
- Cross-link. Wire the new page into this index and into the related runbooks so a reader lands in the right neighbourhood.
- Strip secrets. These docs are public. Teach the pattern, not the credentials, hostnames, or exact budget numbers.
A good test for a runbook: would it have saved you the hour you just spent? If yes, it is worth the twenty minutes to write down.
Planned runbooks
The seed set is intentionally bounded. These are the next ones queued, tracked in fjord-docs #20:
- Backups and restore drills: turning the backups model into a rehearsed recovery, not a hope.
- Zero-downtime upgrades: rolling a Forgejo version without dropping jobs or sessions.
- Authentication and session teardown: token lifetimes, refresh, and revoking access cleanly on logout.
- Disaster recovery and region failover: recovery drills, failure decision points, and operator escalation paths.
- Stephen Way