ADR · ADR-0013 · v1.0.0

Backup Storage Tool — Restic

accepted v1.0.0 Authors: david.sorf Created: 2026-04-10 Updated: 2026-04-10

restic storage dedup encryption architecture s3

EP21 Backup Agent používá restic jako backup storage engine. Restic poskytuje blokovou deduplikaci (content-defined chunking), nativní AES-256 šifrování a přímou podporu S3 backendu (Contabo Object Storage). Alternativy borg a tar/zip/gpg byly zvažovány a zamítnuty.

Related docs:

Related tasks:

Kontext

EP21 Backup Agent spouští denní pg_dump na PostgreSQL databáze a výstupy ukládá lokálně i do remote object storage (Contabo S3). Klíčové požadavky na storage vrstvu:

Deduplikace — DB dumpy jsou den za dnem podobné; ukládání plných kopií každý den je neekonomické
Šifrování — data v klidovém stavu (S3) musí být šifrována
S3 backend — přímá podpora Contabo Object Storage bez extra vrstev
Docker-friendly — binární distribuce bez systémových závislostí
Jednoduchost operací — restore, prune, snapshots přes jednoduché CLI

Kontext diskuse s infra týmem

Infra tým diskutoval, zda by DB dumpy měly být komprimovány přes zip nebo tar před uložením. Argument pro: menší objem přenosu. Argument proti: restic deduplikace pracuje na úrovni bloků — ZIP/TAR by dedup znemožnil (komprimovaný soubor je kryptograficky odlišný i při malé změně vstupních dat).

Rozhodnutí

✓ Chosen: Restic — jako jediný backup storage engine pro lokální i remote (Contabo S3) úložiště

Porovnání alternativ

Nástroj	Dedup	Encryption	S3 backend	Docker-friendly	Zralost
restic	blokový CDC	AES-256 nativní	ano (nativní)	ano (single binary)	vysoká
borg	blokový CDC	ano	jen přes rclone	horší (Python dep)	vysoká
tar + gpg	ne	ruční pipeline	ruční	ano	legacy
zip	ne	volitelná	ruční	ano	nevhodný pro backup

Proč restic

Blokový CDC dedup — restic dělí soubory na proměnně velké bloky (512 KB–8 MB, content-defined chunking). Identické bloky se ukládají jen jednou napříč všemi snapshoty. DB dump mění typicky jen malou část dat den za dnem → efektivita dedup 60–90 %.

Proč ne zip/tar před restic — komprese/archivace před restic dedup je kontraproduktivní. Komprimovaný soubor je z pohledu restic zcela jiná sekvence bajtů i při minimální změně vstupních dat → dedup přestane fungovat. restic komprimuje interně volitelně (od v0.14), ale i bez toho dedup výrazně dominuje nad kompresí pro opakující se obsah.

Proč ne borg — borg vyžaduje Python runtime, horší Docker integrace, S3 jen přes rclone wrapper. Pro EP21 scale výhody oproti restic neexistují.

Proč ne tar + gpg — žádná deduplikace, správa šifrování je ruční a chybová, žádný snapshot model, žádné prune, žádný S3. Vhodné pro jednorázové archivy, ne pro denní provoz.

Důsledky

Pozitivní:

Denní storage overhead: typicky 5–15 % velikosti jednoho dumpu místo 100 %
Šifrování je automatické — žádný extra krok před S3 uploádem
restic snapshots, restic stats, restic ls — přehled co je kde uloženo
Prune politika přes restic forget --keep-* řídí retention bez ručního mazání
Přímý restore: restic restore <snapshot> --target /

Negativní / omezení:

Restic repo nelze číst bez restic (ne plain files) — vyžaduje knowledge transfer
Heslo (RESTIC_PASSWORD_FILE) je kritický secret — bez něj jsou data nedostupná navždy
Init repo jen jednou — přemigrace na jiný nástroj by vyžadovala full re-dump

Dopad na ostatní ADR

ADR-0003: naming a SHA strategie navazuje na restic snapshot model
ADR-0010: remote object storage = Contabo S3 přes restic S3 backend
ADR-0007: restic je bundlován přímo v Docker image (single binary, žádné systémové závislosti)

Changelog

Version	Date	Author	Note
1.0.0	2026-04-10	david.sorf + claude-sonnet-4-6	Vytvořeno a přijato. Kontext: diskuse s infra týmem o zip/tar vs. dedup. Restic potvrzen jako jediný storage engine. Alternativy borg a tar/zip/gpg dokumentovány a zamítnuty.