System Overview — EP21 DB Backup Engine

System Context Diagram

flowchart TB
    admin(["👤 Admin / DevOps"])
    cron(["⏰ Cron"])

    subgraph sys ["EP21 DB Backup Engine"]
        engine["🐳 Backup Container\n(scheduler, pg_dump, restic)"]
    end

    brew["🍺 Brew PostgreSQL\n(host)"]
    docker_pg["🐳 Docker PostgreSQL\n(kontejnery na hostu)"]
    docker_daemon["🐳 Docker Daemon\n(/var/run/docker.sock)"]
    contabo["☁️ Contabo S3\n(remote object storage)"]
    local_fs["💾 VM Filesystem\nbkup_data/, restic-repo/"]

    cron -->|"spouští daily run"| engine
    admin -->|"wrapper skripty\n(start, status, logs...)"| engine
    engine -->|"pg_dump přes host-gateway"| brew
    engine -->|"docker exec pg_dump"| docker_pg
    docker_daemon -->|"docker ps / inspect"| engine
    engine -->|"restic backup"| contabo
    engine -->|"SQL dumpy + snapshoty"| local_fs

Architecture Overview Diagram

flowchart TD
    subgraph orch ["Orchestration Layer"]
        sched["scheduler.sh\n(cron entry point)"]
        lock["Lock Manager\n(daily.lock)"]
        daily["daily.sh"]
    end

    subgraph primary ["Primary Layer"]
        detect["Source Detection\n(Brew PG + Docker PG)"]
        dump["pg_dump\n(per DB)"]
        naming["Artifact Naming\nSHA256 dedup"]
    end

    subgraph secondary ["Secondary Layer"]
        restic["restic backup\n(encrypted snapshot)"]
        posthook["restic post-hook\n(prune remote)"]
    end

    subgraph lifecycle ["Lifecycle Layer"]
        retention["Retention Engine\n(prune local dumps)"]
        meta["Metadata Writer\n(run.json, inventory)"]
    end

    subgraph storage ["Storage"]
        bkup["bkup_data/\n(SQL dumpy)"]
        repo["restic-repo/\n(šifrované snapshoty)"]
        metadir["meta/\n(JSON inventář)"]
        logs["logs/"]
        s3["☁️ Contabo S3"]
    end

    sched --> lock --> daily
    daily --> detect --> dump --> naming --> bkup
    naming --> meta --> metadir
    daily --> restic --> repo
    restic --> posthook --> s3
    daily --> retention --> bkup
    daily --> meta
    daily --> logs

System Context

Problém

PostgreSQL databáze na VM prostředí potřebují pravidelné, auditovatelné zálohy s:

• odolností vůči selhání jednotlivé vrstvy (lokální disk vs. vzdálené úložiště)
• detekcí beze-změnových běhů (neukládat duplicitní dump)
• čitelnou historií co, kdy a proč bylo zálohováno
• šifrováním na úrovni zálohovacího repozitáře

Odpověď

EP21 DB Backup Engine nasadí jako Docker kontejner na každý VM. Kontejner:

1. detekuje lokální PostgreSQL zdroje (Brew + Docker containers)

2. provede dump každé databáze s metadaty a checksumem

3. snapshot dumpů uloží do restic repozitáře (lokální nebo remote S3)

4. prune staré lokální dumpy po ověření v restic

Hranice systému

• Uvnitř scope: dump, metadata, retention, restic snapshot, Docker packaging, cron orchestrace, machine identity
• Mimo scope: centrální monitoring konzola, alerting integrace (Slack/email), centrální správa machine ID (roadmap), obnova dat (restore je manuální proces)

Aktéři a systémy

Architektura — čtyři vrstvy

Systém je organizován do čtyř explicitně oddělených vrstev. Každá vrstva má vlastní skript, vlastní exit kód a vlastní metadata výstup.

Vrstva 1 — Primary (db_bkup.sh)

detect → plan → backup → metadata

• Detekuje PostgreSQL zdroje (Brew + Docker kontejnery)
• Sestaví zálohovací plán (seznam DB per source)
• Provede pg_dump každé DB s SHA256 checksumem a SQL logickým fingerprinte
• Zapíše metadata (sources.json, plan.json, run.json, per-DB meta)
• Přeskočí dump pokud SHA256 nebo fingerprint beze-změny (ADR-0005, ADR-0006)

Vrstva 2 — Secondary (db_bkup_posthook_restic.sh)

restic snapshot → retention enforce → tag

• Provede restic backup adresářů bkup_data, meta, logs
• Přiřadí tagy: ep21, db-bkup, <machine_name_uniq>
• Enforce retention policy: keep_daily=30 / keep_monthly=12 / keep_yearly=7
• Zapiše restic_run.json metadata

Vrstva 3 — Lifecycle (db_bkup_prune_local_after_restic.sh)

verify restic snapshot → prune local dumps

• Prune lokálních dumpů pouze pokud restic vrstva uspěla
• Default: dry-run; produkční apply je explicitní
• Řídí se keep_local z conf/retention.db_bkup.json (nebo env override)
• Zapiše local_prune.json metadata

Vrstva 4 — Orchestration (db_bkup_daily.sh)

lock → layer1 → layer2 → layer3 → unlock

• Concurrency lock (PID + timeout, stale lock recovery — ADR-0009)
• Spouští vrstvy 1→2→3 v pořadí
• Každá vrstva má vlastní exit kód (db_exit, restic_exit, prune_exit)
• overall_exit není maskován — fail v kterékoli vrstvě je viditelný cronu

Data Flow

PostgreSQL (Brew/Docker)
        │
        │ pg_dump
        ▼
  bkup_data/<machine>/<source>/<db>/<YYYY-MM>/
    ├── <timestamp>.dump          ← SQL dump
    ├── <timestamp>.sha256        ← SHA256 artefaktu
    ├── <timestamp>.meta.json     ← metadata per dump
    ├── latest.dump               ← symlink na poslední dump
    └── meta.latest.json          ← symlink na poslední meta
        │
        │ restic backup
        ▼
  restic repository (lokální nebo Contabo S3)
    └── snapshot tagged: ep21, db-bkup, <machine_name_uniq>
        │
        │ po úspěšném restic
        ▼
  prune lokálních dumpů
    └── zachovat keep_local=2 (konfigurovatelné)

Metadata tok:

meta/inventory/
  ├── sources.<timestamp>.json    ← detekované zdroje
  ├── plan.<timestamp>.json       ← zálohovací plán
  ├── run.<timestamp>.json        ← výsledek primary vrstvy
  ├── restic_run.<timestamp>.json ← výsledek secondary vrstvy
  └── local_prune.<timestamp>.json← výsledek lifecycle vrstvy

meta/db/<source_id>/<db>/<timestamp>.json ← per-DB metadata

Adresářová struktura (runtime)

conf/
  machine.json                    ← machine_name_uniq (generováno, persistováno)
  retention.db_bkup.json          ← local retention policy (keep_local=2)
  retention.restic.json           ← restic retention policy (30/12/7)

meta/inventory/
  run.*.json                      ← výsledek každého denního běhu
  sources.*.json                  ← detekované zdroje
  plan.*.json                     ← zálohovací plán
  restic_run.*.json               ← výsledek restic vrstvy
  local_prune.*.json              ← výsledek prune vrstvy
  *.latest.json                   ← symlinky na poslední verzi

meta/db/<source_id>/<db>/<timestamp>.json

bkup_data/<machine_name_uniq>/db_data/<source_id>/<db>/<YYYY-MM>/
  <timestamp>.dump
  <timestamp>.sha256
  <timestamp>.meta.json
  latest.dump
  meta.latest.json

logs/
  machine/
  source/
  db/
  scheduler/
  restic/

Deployment model

Systém běží jako jeden Docker kontejner na každém cílovém VM.

Image: registry.gitlab.com/<org>/ep21-db-bkup:<version>

Povinné volume mounty:

• DB_BKUP_ROOT volume → /bkup (data + meta + logs)
• Restic repo volume → /restic-repo
• RESTIC_PASSWORD_FILE → /run/secrets/restic-password
• /var/run/docker.sock → /var/run/docker.sock (Docker source detection)
• /etc/localtime → /etc/localtime:ro (timezone)

Entrypoint příkazy:

daily | backup | report | retention-report | storage-report | restic-posthook | prune-local | cron-daemon | shell

Cron daemon mode: kontejner startuje s cron-daemon, interní cron spouští daily podle DAILY_CRON env (default: 0 2 * * *).

Docker packaging detail: viz ADR-0007 (Docker packaging) a ADR-0008 (container runtime connectivity).

Retention model

Integrita a detekce změn

Každý dump má dvě úrovně integrity:

SHA256 artefaktu (artifact.sha256)

• Binární hash SQL dump souboru
• Pokud shodný s předchozím: dump se nepřepíše (ADR-0005)
• Detekuje změny v exportovaném binárním obsahu

SQL Logical Fingerprint (fingerprint.sql_v1)

• Hash odvozený z logické struktury SQL (nikoliv binárního exportu)
• Odolný vůči pg_dump version bumps, změnám pořadí komentářů apod.
• Doplňuje SHA256 pro přesnější detekci skutečných datových změn (ADR-0006)

Change tracking:

• run.changed: true/false — zda byl dump v tomto běhu jiný
• run.changed_reason — SHA256 / fingerprint / nový_db / první_run

Failure semantics

Orchestrace (db_bkup_daily.sh) vede separátní exit kódy pro každou vrstvu:

• db_exit — výsledek primary vrstvy (dump)
• restic_exit — výsledek secondary vrstvy (restic snapshot)
• prune_exit — výsledek lifecycle vrstvy (local prune)

overall_exit je bitový OR všech tří — fail v kterékoli vrstvě je viditelný cronu a neblokuje ostatní vrstvy.

Princip: partial success je lepší než žádný backup. Pokud restic selže, local dumpy zůstanou. Pokud prune selže, data nejsou ztracena — jen se nezrušily staré dumpy.

Security model

• Restic repozitář je šifrován heslem z RESTIC_PASSWORD_FILE (nikdy z env proměnné přímo)

• Heslo se nikdy neprintuje do logů — logy obsahují path/status, ne hodnotu

• Docker socket mount je privilegovaná operace — kontejner musí běžet s oprávněním číst socket

• Dump soubory jsou chráněny oprávněními file systému (pouze root/backup user čte)

• Contabo S3 přihlašovací údaje jsou předávány jako env proměnné (RESTIC_AWS_ACCESS_KEY_ID, RESTIC_AWS_SECRET_ACCESS_KEY) — doporučeno použít Docker secrets nebo Vault

• Trivy security scan: výsledky a CVE analýza v SECURITY_FINDINGS.md

Operační observability

• meta/inventory/run.latest.json — výsledek posledního primary backup běhu

• meta/inventory/restic_run.latest.json — výsledek posledního restic snapshotu

• meta/inventory/local_prune.latest.json — výsledek posledního prune

• logs/scheduler/daily.*.log — kompletní log denního orchestračního běhu

• logs/restic/restic.*.log — restic operace (snapshot, forget, check)

• Wrapper skript scripts/backup-container-status.sh — rychlý přehled stavu

• Wrapper skript scripts/backup-container-report.sh — report detekce a zálohovacího plánu

Machine identity

Každý VM má jedinečný identifikátor machine_name_uniq uložený v conf/machine.json. Identifikátor je:

• generován při prvním spuštění (UUID nebo hostname-based)
• persistován v conf/machine.json
• použit pro restic snapshot tagging (tag: <machine_name_uniq>)
• použit jako prefix v adresářové struktuře bkup_data/<machine_name_uniq>/

Roadmap: centrální API pro ověření uniqueness machine ID při bootstrapu VM; při detekci duplicity alert pro SOC.

Roadmap a známá omezení

• [Planned] Centrální API pro machine ID uniqueness check (ADR-0010 — deferred sharding placeholder)

• [Planned] Alerting integrace — email/Slack/webhook notifikace při selhání backup běhu

• [Planned] Restore testing skript — pravidelný automated restore smoke test pro ověření integrity

• [Planned] Restic integrity check v cronu — restic check jako scheduled job s reportingem

• [Planned] Sharding pro velká prostředí s mnoha VM (ADR-0010 — deferred)

• [Omezení] Restore je manuální proces — žádný automated restore workflow neexistuje

• [Omezení] Monitoring konzola chybí — status je dostupný jen přes wrapper skripty nebo čtením JSON meta souborů

ADR Index