lazybytez · pascal-zarrad · Jun 5, 2026
@@ -0,0 +1,43 @@
+# Conba Documentation
+
+Conba is a Go CLI that wraps [restic](https://restic.net/) to back up Docker
+container volumes — either as raw volume snapshots or by streaming a command's
+output (e.g. `mysqldump`) straight into a snapshot. It is invoked **on demand**
+(there is no built-in scheduler); run it from cron, a systemd timer, or a CI/CD
+pipeline.
+
+## Start here
+
+- [Installation](installation.md) — build from source or run the container image.
+- [Getting started](guides/getting-started.md) — your first backup, end to end.
+
+## Reference
+
+- [Configuration](configuration.md) — the `conba.yaml` file and `CONBA_*`
+  environment overrides, field by field.
+- [Commands](commands.md) — every subcommand, its flags, and dry-run support.
+- [Container labels](container-labels.md) — per-container filtering, retention,
+  and pre-backup/restore behaviour driven by Docker labels.
+
+## Guides
+
+- [Database dumps (streaming backups)](guides/database-dumps.md) — back up
+  MySQL/PostgreSQL/etc. with a consistent dump instead of raw volume files.
+- [Restoring](guides/restore.md) — restore volume and stream snapshots.
+- [Retention and filtering](guides/retention-and-filtering.md) — choose what
+  gets backed up and how long snapshots are kept.
+
+## Concepts at a glance
+
+| Term | Meaning |
+|------|---------|
+| **Target** | A single container volume mount eligible for backup. |
+| **Volume snapshot** | A restic snapshot of a volume's files (`kind=volume`). |
+| **Stream snapshot** | A restic snapshot of a command's stdout (`kind=stream`), e.g. a `mysqldump`. |
+| **Pre-backup command** | A command run inside a container at backup time whose stdout becomes a stream snapshot. |
+| **Discovery** | Listing running containers and their mounts via the Docker API. |
+| **Filter** | Include/exclude rules (config + labels) deciding which targets are backed up. |
+
+Every snapshot is tagged with `container=`, `volume=` (volume snapshots),
+`hostname=`, and `kind=`, which is how `snapshots`, `restore`, and `forget`
+locate and scope snapshots.
@@ -0,0 +1,178 @@
+# Commands
+
+All commands read configuration as described in [Configuration](configuration.md)
+and accept the global flag `-c, --config <path>` (default `conba.yaml`).
+
+| Command | Purpose | Dry-run |
+|---------|---------|---------|
+| [`init`](#init) | Initialise the restic repository | — |
+| [`backup`](#backup) | Back up all discovered volume targets | ✅ |
+| [`snapshots`](#snapshots) | List snapshots | n/a (read-only) |
+| [`restore`](#restore) | Restore a volume or stream snapshot | ✅ |
+| [`verify`](#verify) | Check repository integrity | n/a (read-only) |
+| [`diff`](#diff) | Show changes between two snapshots | n/a (read-only) |
+| [`forget`](#forget) | Apply retention / prune snapshots | ✅ |
+| [`run`](#run) | One-shot init + backup + forget cycle | ✅ |
+| [`inspect`](#inspect) | Preview which containers/volumes would be backed up | n/a (read-only) |
+| [`status`](#status) | Show repository status | n/a (read-only) |
+| [`unlock`](#unlock) | Remove stale repository locks | — |
+| [`version`](#version) | Print version information | — |
+
+Mutating commands (`backup`, `restore`, `forget`, `run`) support `--dry-run`,
+which prints the planned actions and performs none of them. Read-only commands
+have no dry-run because they never change state.
+
+---
+
+## init
+
+```sh
+conba init
+```
+
+Initialises the configured restic repository. Safe to run against an
+already-initialised repository (reported, not an error).
+
+## backup
+
+```sh
+conba backup [--dry-run]
+```
+
+Discovers running containers, applies discovery filters, and backs up each
+eligible volume mount as a `kind=volume` snapshot. If
+`pre_backup_commands.enabled` is true, containers carrying
+`conba.pre-backup.command` instead (or additionally) produce a `kind=stream`
+snapshot — see [Database dumps](guides/database-dumps.md).
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Print what would be backed up; create no snapshots. |
+
+## snapshots
+
+```sh
+conba snapshots [--container <name>] [--volume <name>] [--hostname <host>]
+```
+
+Lists snapshots, optionally filtered. Filters combine (AND).
+
+| Flag | Description |
+|------|-------------|
+| `--container` | Only snapshots tagged `container=<name>`. |
+| `--volume` | Only snapshots tagged `volume=<name>`. |
+| `--hostname` | Only snapshots tagged `hostname=<host>`. |
+
+## restore
+
+```sh
+conba restore --container <name> [--volume <name>] [--snapshot <id>] \
+              [--to <dir>] [--to-command <cmd>] [--force] [--all-hosts] [--dry-run]
+```
+
+Restores the latest matching snapshot (or `--snapshot <id>`). The mode is
+auto-detected from the snapshot's `kind` tag. See [Restoring](guides/restore.md).
+
+| Flag | Description |
+|------|-------------|
+| `--container` | Container whose snapshot to restore (**required**). |
+| `--volume` | Volume name; required when multiple volume snapshots match. |
+| `--snapshot` | Restore a specific snapshot ID instead of the latest. |
+| `--to` | Host directory to restore a **volume** snapshot into. |
+| `--to-command` | In-container command to pipe a **stream** snapshot into. |
+| `--force` | Overwrite a non-empty restore destination (volume mode). |
+| `--all-hosts` | Consider snapshots from any hostname, not just this host. |
+| `--dry-run` | Print the planned restore; touch nothing. |
+
+## verify
+
+```sh
+conba verify [--read-data]
+```
+
+Wraps `restic check`. Exits non-zero if the repository is corrupt or missing.
+
+| Flag | Description |
+|------|-------------|
+| `--read-data` | Read and verify every data blob (slow, exhaustive). Without it, only repository structure is checked. |
+
+## diff
+
+```sh
+conba diff <snapshot-a> <snapshot-b>
+```
+
+Wraps `restic diff` and prints its output verbatim. Snapshot identifiers may be
+full IDs, short IDs, or the literal `latest`.
+
+## forget
+
+```sh
+conba forget [--dry-run] [--no-prune] [--all-hosts] \
+             [--container <name>] [--volume <name>] [--tag <tag>]...
+```
+
+Applies the configured [retention](guides/retention-and-filtering.md) policy
+(with per-container `conba.retention` overrides) and prunes by default.
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Show what would be forgotten; change nothing. |
+| `--no-prune` | Forget snapshots but skip the (slow) prune step. |
+| `--all-hosts` | Apply across all hostnames, not just this host. |
+| `--container` | Restrict to one container. |
+| `--volume` | Restrict to one volume. |
+| `--tag` | Restrict to snapshots carrying the tag (repeatable). |
+
+## run
+
+```sh
+conba run [--dry-run] [--all-hosts] [--no-forget]
+```
+
+The on-demand "do everything" command, intended for cron/CI: initialises the
+repository if needed, runs a backup, then applies retention. This is the typical
+scheduled entry point.
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Plan the full cycle without changing anything. |
+| `--all-hosts` | Pass through to the forget phase. |
+| `--no-forget` | Skip the retention/forget phase. |
+
+## inspect
+
+```sh
+conba inspect
+```
+
+Read-only preview of discovery: lists containers and volumes that **would** be
+backed up (Included) and those that would not (Excluded, with reasons), plus any
+pre-backup label details. Use it to validate filters before backing up.
+
+## status
+
+```sh
+conba status
+```
+
+Prints repository status (initialised/ready, repository path, snapshot/stats
+summary). Exits 0 even when the repository is uninitialised, printing a friendly
+"run 'conba init'" hint.
+
+## unlock
+
+```sh
+conba unlock
+```
+
+Removes stale locks left behind by an interrupted restic operation.
+
+## version
+
+```sh
+conba version
+```
+
+Prints the conba version plus the Go and bundled restic versions. Requires no
+configuration or repository.
@@ -0,0 +1,127 @@
+# Configuration
+
+Conba reads a YAML config file (default: `conba.yaml` in the working directory;
+override with `-c/--config <path>`). Every value can also be supplied via an
+environment variable.
+
+## Environment overrides
+
+Any config key maps to an environment variable by upper-casing it, replacing
+dots with underscores, and prefixing `CONBA_`:
+
+| Config key | Environment variable |
+|------------|----------------------|
+| `restic.repository` | `CONBA_RESTIC_REPOSITORY` |
+| `restic.password` | `CONBA_RESTIC_PASSWORD` |
+| `logging.level` | `CONBA_LOGGING_LEVEL` |
+| `discovery.opt_in_only` | `CONBA_DISCOVERY_OPT_IN_ONLY` |
+| `pre_backup_commands.enabled` | `CONBA_PRE_BACKUP_COMMANDS_ENABLED` |
+
+Environment variables take precedence over the file. They are convenient for
+secrets (`CONBA_RESTIC_PASSWORD`) and for the container image.
+
+## Full example
+
+```yaml
+restic:
+  repository: "s3:s3.amazonaws.com/my-bucket"
+  password_file: "/run/secrets/restic-password"
+
+runtime:
+  type: docker
+  docker:
+    host: "unix:///var/run/docker.sock"
+
+discovery:
+  opt_in_only: false
+
+retention:
+  keep_daily: 7
+  keep_weekly: 4
+  keep_monthly: 6
+  keep_yearly: 0
+
+pre_backup_commands:
+  enabled: false
+
+logging:
+  level: "info"
+  format: "human"
+```
+
+## Reference
+
+### `restic`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `repository` | string | — (**required**) | restic repository URL (`s3:…`, `/path`, `sftp:…`, etc.). |
+| `password` | string | — | Repository password. Provide this **or** `password_file`. |
+| `password_file` | string | — | Path to a file containing the repository password. |
+| `binary` | string | `restic` | Path/name of the restic binary to invoke. |
+| `extra_args` | list | — | Extra arguments appended to every restic invocation. |
+| `environment` | map | — | Extra environment variables for restic (e.g. cloud credentials, `RESTIC_CACHE_DIR`). |
+
+One of `password` / `password_file` is required, as is `repository`. Missing
+either fails fast at startup.
+
+> Pre-backup (stream) commands require restic to spawn a child process, which
+> needs a cache directory. When using that feature, set `RESTIC_CACHE_DIR` (and
+> `HOME`) under `restic.environment`, and ensure `PATH` is set so restic can
+> find the runtime. See [Database dumps](guides/database-dumps.md).
+
+### `runtime`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `type` | string | `docker` | Container runtime. Docker is the only supported type. |
+| `docker.host` | string | `unix:///var/run/docker.sock` | Docker daemon address. |
+
+### `discovery`
+
+Controls which containers/volumes become backup targets. See
+[Retention and filtering](guides/retention-and-filtering.md) for worked examples.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `opt_in_only` | bool | `false` | When `true`, only containers labelled `conba.enabled=true` are considered. |
+| `include` | filter list | — | Force-include matching containers. |
+| `exclude` | filter list | — | Exclude matching containers. |
+
+A **filter list** has four fields, each a list of strings:
+
+| Field | Matches on |
+|-------|-----------|
+| `names` | exact container name |
+| `name_patterns` | container name (regular expression) |
+| `ids` | exact container ID |
+| `id_patterns` | container ID (regular expression) |
+
+### `retention`
+
+Global retention policy applied by `conba forget` (and the forget phase of
+`conba run`). All default to `0` (= keep, i.e. that dimension is not enforced).
+Per-container overrides are possible with the `conba.retention` label.
+
+| Key | Type | Default |
+|-----|------|---------|
+| `keep_daily` | int | `0` |
+| `keep_weekly` | int | `0` |
+| `keep_monthly` | int | `0` |
+| `keep_yearly` | int | `0` |
+
+### `pre_backup_commands`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `enabled` | bool | `false` | Master switch for label-driven pre-backup/restore commands. **Off by default** because it lets anyone who can set container labels make conba run shell commands inside those containers. |
+
+When disabled (the default), all `conba.pre-backup.*` labels are ignored and
+volume backups proceed as usual.
+
+### `logging`
+
+| Key | Type | Default | Values |
+|-----|------|---------|--------|
+| `level` | string | `info` | `debug`, `info`, `warn`, `error` |
+| `format` | string | `human` | `human`, `json` |