Backup engine běží jako autonomní agent (Docker kontejner) na každém KVM VM — součást EP21 golden image. Detekce databázových zdrojů je port-based (konfigurovatelný seznam portů) + Docker container inspection, čímž je OS-agnostická a nezávislá na macOS/Brew. Architektura je záměrně navržena pro budoucí rozšíření na MySQL a jiné DB systémy.
v1.0.0 (accepted, implementováno): Brew PostgreSQL + Docker container inspection. Toto je aktuálně v produkci.
v1.1.0 (tento dokument, draft — zatím neschváleno): Rozšíření na port-based OS-agnostickou detekci, EP21 Backup Agent model a extensibilitu pro další DB systémy. Čeká na design review a implementaci.
---
Původní omezení (v1.0.0)
Původní scope byl příliš úzký — vázal detekci na Brew PostgreSQL (macOS specifické) a Docker kontejnery. Toto neodpovídalo dlouhodobému cílovému prostředí.
Skutečný cílový deployment
EP21 DB Backup Engine není vývojový nástroj — je to backup agent:
Běží jako Docker kontejner na každém KVM VM v EP21 infrastruktuře
Nasazuje se jako součást golden image pro Ubuntu/CentOS VM
Startuje automaticky při startu VM — bez manuální konfigurace per-VM
Cíl: každý VM je pokrytý preventivně, vždy a všude
Požadavky na detekci
Musí detekovat PostgreSQL running na host machine i v Docker kontejnerech
Musí fungovat na jakémkoli OS kde lze spustit Docker (Ubuntu, CentOS, Debian, ...)
Žádná závislost na OS-specifických package managerech (Brew = macOS only)
Konfigurovatelné: správce může explicitně definovat porty a connection parametry
Extensible: budoucí podpora MySQL, MariaDB a dalších DB systémů
Zvažované alternativy
A) Brew + Docker only (původní v1.0.0) — macOS specifické, nepoužitelné na Linux VM
Agent běží jako Docker kontejner na každém VM. Je součástí golden image — po prvním startu VM se agent automaticky spustí a začne zálohovat bez jakékoli manuální intervence.
Detekční mechanismy (v pořadí priorit)
1. Port-based host discovery
Agent prozkouší konfigurovatelný seznam portů na host-gateway (docker network alias pro host)
Default porty: PostgreSQL 5432, případně další explicitně definované
Pro každý otevřený port se pokusí připojit a identifikovat DB typ
Konfigurace v backup.env: PROBE_PORTS=5432,5433 nebo explicitní PG_HOST, PG_PORT
Timeout je krátký — chybějící DB = rychlý skip, ne blokování
2. Docker container inspection
docker ps → filtruje kontejnery s DB image (konfigurovatelný pattern: postgres:*, mysql:*, ...)
Pro každý nalezený kontejner zjistí exposed port a provede dump přes docker exec
Detekce je dynamická — nové kontejnery jsou zachyceny v příštím běhu
3. Brew PostgreSQL (macOS dev only)
pg_isready na lokálním socketu — zůstává pro zachování dev parity
Použitelné pouze na macOS, na Linux VM se přeskočí
Není součástí produkčního golden image scope
Extensibilita
Detekce je navržena jako pluggable:
Přidání MySQL: přidání portu 3306 do PROBE_PORTS + implementace mysql_dump handleru
Přidání MongoDB: port 27017 + mongodump handler
Každý DB typ má svůj dump handler — sdílí pouze detekční a orchestrační infrastrukturu
TBD: formální plugin interface pro custom DB handlers (budoucí ADR)
EP21 Backup Agent — deployment model
Klíčový architektonický princip: jeden agent per VM, automaticky, preventivně.
KVM Hypervisor
├── VM #1 (Ubuntu) → ep21-db-backup agent (Docker) → záloha lokálních DB
├── VM #2 (CentOS) → ep21-db-backup agent (Docker) → záloha lokálních DB
├── VM #3 (Debian) → ep21-db-backup agent (Docker) → záloha lokálních DB
└── ...
Golden image integrace:
Agent je součástí EP21 VM golden image jako Docker Compose service nebo systemd unit
Při prvním startu VM: agent se inicializuje (generuje machine_name_uniq, inicializuje restic repo)
Cron daemon startuje automaticky a začíná zálohovací cyklus
Správce nepotřebuje dělat nic — backup je garantovaný od první minuty
Výsledek: žádné VM v EP21 infrastruktuře není bez zálohy z důvodu opomenutí nebo manuálního kroku.
Důsledky
Pozitivní:
OS-agnostická detekce — funguje na Ubuntu, CentOS, Debian i macOS dev
Preventivní pokrytí — každý VM je automaticky zálohován bez opt-in
Konfigurovatelné porty — správce může přidat nestandardní porty nebo explicitní connection strings
Extensible na další DB systémy — přidání MySQL nevyžaduje změnu detekční architektury
Dynamická Docker detekce — nové DB kontejnery jsou zachyceny bez restartu agenta
Negativní:
Port scanning musí robustně zvládat timeouty — chybějící DB nesmí zpomalovat běh
Docker socket mount zůstává privilegovanou operací — viz ADR-0008
Running Docker kontejner podmínka zůstává — zastaven kontejner není detekován
Brew detection zůstává jako legacy path pro macOS dev — zvyšuje komplexitu kódu
Rizika:
Port probe může detekovat non-DB službu na stejném portu — nutná validace po připojení
Při přidávání nových DB handlerů je nutné zajistit kompatibilitu dump formátů s restic retention modelem
Budoucí rozšíření — další DB systémy
DB systém
Default port
Dump nástroj
Status
PostgreSQL
5432
pg_dump
✓ Implementováno
MySQL / MariaDB
3306
mysqldump
Planned — přidání port + handler
MongoDB
27017
mongodump
Planned — přidání port + handler
Redis
6379
redis-cli SAVE
Idea — TBD, jiný backup model
Další
konfigurovatelný
custom handler
Pluggable architektura — TBD ADR
Changelog
Version
Date
Author
Note
2.0.0
2026-04-09
david.sorf + claude-sonnet-4-6
DRAFT amendment — zatím neschváleno (accepted_version zůstává 1.0.0). Rozšíření vize: EP21 Backup Agent jako součást KVM golden image, port-based OS-agnostická detekce (konfigurovatelné porty), extensible na MySQL a další DB systémy. Přidány sekce: deployment model, future DB systems tabulka. Po schválení a implementaci: povýšit verzi na 2.0.0 a aktualizovat accepted_version.
1.0.0
2026-04-09
david.sorf + claude-sonnet-4-6
Migrace z doc/ADR/ADR-0002-source-detection-scope.md do DAK JSON formátu. Původní scope: Brew + Docker, macOS-centric.