Bosun

Diagrams

Diagrams

Editorial diagrams of Bosun's deploy pipeline, architecture, and concurrency model.

Bosun deploy pipeline overview Linear pipeline: a git push is received by Bosun, which clones the repo and decrypts secrets, templates the configs, deploys them to the target, runs docker compose up, and verifies drift. Captain gives orders git push Bosun receives orders webhook / poll Clone & decrypt git + sops/age Template configs go templates + sprig Deploy to target local copy / tar-over-ssh Crew up docker compose up Drift verification declared vs actual LEGEND focal step pipeline step operator input verification
The deploy pipeline, start to finish: push, clone, decrypt, template, deploy, reload, verify.
Bosun system architecture A git push on GitHub reaches Bosun's radio over webhook or poll; inside the server, Bosun fetches orders, decrypts secrets, preps configs, deploys, and brings the crew of containers up, while drift watch periodically verifies them. CAPTAIN · GITHUB YOUR YACHT · SERVER BOSUN · SINGLE BINARY WEBHOOK VERIFY Orders git push Radio webhook / poll Fetch orders git clone/pull Decrypt secrets sops + age Prep configs go templates Deploy tar-over-ssh / local Crew up docker compose Drift watch periodic check Your crew containers LEGEND focal bosun stage containers periodic / async external call
Bosun's place on the yacht: one binary watching git and drift, driving Docker Compose.
Bosun reconcile pipeline, steps 1 to 16 Four phases: the gate phase syncs git and decides whether a deploy is required, exiting early on a clean skip or a tripped circuit breaker; the stage phase decrypts, renders, and backs up; the deploy phase syncs files, runs docker compose up, and applies an optional health gate that rolls back on failure; the finish phase runs hooks, verifies health and drift, and records success before releasing the lock. GATE STAGE DEPLOY VERIFY & FINISH SKIP TRIP YES FAILED HEALTHY 1 · Acquire lock 2 · Git sync 3 · Reload config + state commit / path skips · breaker Deploy required? Clean skip reset · unlock Breaker halt alert · error 4 · Track attempt + decrypt resolve deploy mode 5 · Render staging tree 6 · Extract declared services fail closed if missing 7 · Create + verify backup rollback anchor 8 · Snapshot health mark NeedsRedeploy 9 · Deploy managed files verify writes / transfer 10 · docker compose up signal reload 11 · Health gate optional Rollback full tree fail deploy · retry next cycle 12 · Post-sync hooks 13 · Post-deploy verify health + drift check 14 · Finalize staging 15 · Record success retain verified backups 16 · Release lock LEGEND pipeline step safety gate failure path benign exit
The reconcile engine internals — lock, sync, decrypt, render, backup, deploy, verify.
Bosun locking and single-flight trigger coalescing A trigger arriving during a running reconciliation is queued into a pending batch and answered 202; otherwise the file lock is acquired and reconciliation runs. Afterwards, a queued batch runs as one coalesced reconciliation, re-checking until the queue is empty. YES NO YES RE-CHECK NO Trigger Reconciliation running? Queue the trigger pending batch · source · sticky force Return 202 Accepted caller unblocked Acquire the lock flock LOCK_EX | LOCK_NB Run reconciliation full pipeline, one flight Pending batch queued? One coalesced run sorted sources · sticky force Finish LEGEND coalesced flight step / decision queued state incoming trigger
Single-flight reconciliation: concurrent triggers coalesce into one run, then one follow-up batch.