Architecture

One Go process with four jobs: watch Docker, store what it sees, serve it, and snapshot crashes. There is no external service — state lives in one SQLite file plus small in-memory ring buffers.

Docker Engine  →  CapScope (one Go binary)  →  SQLite (one file)
                    │
                    ├─ collector: follows logs + stats per container
                    ├─ hub: SSE fan-out to the browser
                    ├─ store: WAL mode, batched inserts, retention
                    └─ api: REST + SSE + embedded single-page UI

Components

Log ingestion

Crash snapshot sequence

Docker            eventLoop             Manager                     store
  | oom event --->  | setOOM() on tracker, or remember the flag        |
  | kill (sig) -->  | setSignal() on tracker, or remember the flag     |
  | die (exit=137)->| detach tracker from map (synchronous)            |
  |                 | go finishDie():                                  |
  |                 |   tracked: mark exited, wait <=2s for logLoop    |
  |                 |            to drain, cancel stats follower       |
  |                 |   no tracker: rebuild from inspect + SQLite tail |
  |                 |   inspect (OOMKilled, RestartCount, limits)      |
  |                 |   classify -> oom | crash | killed | clean_exit  |
  |                 |   skip when (container, die_ts) already stored   |
  |                 |   count deaths in the restart-loop window        |
  |                 |   build snapshot from ring logs + ring metrics   |
  |                 |   summarize() rule-based text ------------------> INSERT snapshots
  |                 |   save event cursor (die/oom force a write) -----> state

Design points

• The tracker is detached from the map inside the event goroutine before any async work. With a restart policy Docker reuses the container id, so the next start must create a fresh tracker.
• Evidence comes from in-memory ring buffers, not SQLite — the database write is batched and can lag the final lines by up to 250 ms.
• A die with no tracker (CapScope was down, or the container started and died between reconciles) is rebuilt from inspect, with last lines from SQLite when available, otherwise from the tail of Docker's own log file, which still holds a stopped container's final lines.
• Catch-up after downtime: the newest processed event time is persisted in state. On startup the stream resumes from that cursor (up to 24 h back), so deaths that happened while CapScope was off are replayed. (container_id, die_ts) deduplication makes a replay harmless.
• Classification: OOM wins, exit 0 is clean_exit, a seen kill/stop signal makes it killed, everything else is crash.
• Summaries are rule-based, not diagnoses: they state what the data shows and what the exit code usually means (137, 139, 143, 126, 127, 1).
• The stored inspect is trimmed — environment variables and labels are deliberately left out because they often hold secrets.

App naming

CapRover runs each app as a Swarm service named srv-captain--<app>, with tasks srv-captain--<app>.<slot>.<taskid>. The app name comes from the label com.docker.swarm.service.name and the replica from the task name. Fallbacks: Docker Compose labels, then the container name. Replicas of one app appear together in the UI.

Storage

SQLite in WAL mode, synchronous=NORMAL, busy_timeout=5000. A single writer serializes all writes; a read-only pool of 4 serves the UI, so dashboard queries never wait for ingestion. auto_vacuum=INCREMENTAL is set before the first table exists so retention can return space to the OS.

Measured throughput: about 156,000 rows/second inserted in a store-level micro benchmark (2 vCPUs, batches of 1000, WAL). That excludes stream decoding, redaction and level detection — treat it as an upper bound.

Concurrency model

Security model

Failure modes

Decisions and trade-offs