server-up/docs/backups.md

Backups

Server Up maakt backups van je stacks: handmatig, automatisch vóór risicovolle acties, of op een schema. Terugzetten kan met één klik.

---

⚠️ Lees dit eerst: wat zit er wél en niet in

Een backup is een .tar.gz van de stackmap in je library. Daar zitten in:

• het compose-bestand
• het .env-bestand (met je wachtwoorden en tokens)
• eventuele configuratiebestanden die naast de compose staan
• .serverup.json met de metadata van de installatie

Wat er niet in zit: de Docker-volumes met de eigenlijke gegevens van de app.

Voorbeeld	In de backup?
De compose van Vaultwarden	✅
Je ADMIN_TOKEN uit .env	✅
De wachtwoordkluis van Vaultwarden zelf	❌
De database van Paperless	❌
Je foto's in Immich	❌

Je kunt hiermee dus een stack terugzetten zoals hij geconfigureerd stond, maar niet de inhoud ervan herstellen. Wil je dat ook, dan zijn er twee routes:

1. Bind mounts in plaats van named volumes. Staat je data in /opt/serverup/appdata/<app> en zit die map binnen je stackmap, dan gaat hij wél mee. De meeste templates in apps/ gebruiken data_dir daarvoor.
2. Een aparte volume-backup met bijvoorbeeld restic of borg naast Server Up. Voor grote datasets is dat sowieso beter dan een tar per keer.

Omdat een backup je .env bevat, staan er wachtwoorden in. BACKUP_DIR hoort dus dezelfde bescherming te hebben als de rest van /data.

---

Een backup maken

Per stack — de archiefknop op de stackkaart maakt er direct een. De geschiedenisknop ernaast toont alle backups van die stack, met de mogelijkheid om terug te zetten of te verwijderen.

Automatisch vóór risicovolle acties — standaard aan voor:

• bijwerken van een stack (compose pull + up), want een nieuwe image-versie kan een compose-wijziging nodig hebben;
• verwijderen van een stack, maar alleen als je "verwijder ook de bestanden" kiest — bij het enkel stoppen van containers valt er niets te verliezen.

Uit te zetten onder Instellingen → Backups. Mislukt zo'n automatische backup, dan gaat de actie alsnog door: anders zou je een kapotte stack niet meer kunnen opruimen. De melding komt wel in het joblog.

Gepland — dagelijks of wekelijks, rond een uur dat je zelf kiest. De planner draait in de applicatie zelf (geen cron nodig) en onthoudt in config.json wanneer hij voor het laatst gelopen heeft. Stond de server uit op het geplande moment, dan loopt de backup bij de eerstvolgende gelegenheid alsnog.

---

Bewaarbeleid

Twee regels, die allebei tegelijk gelden:

Instelling	Betekenis
BACKUP_KEEP	Hoeveel backups per stack je bewaart. 0 = onbeperkt.
BACKUP_MAX_AGE_DAYS	Alles ouder dan dit aantal dagen gaat weg. 0 = geen limiet.

De nieuwste backup van een stack blijft altijd staan, ook als hij ouder is dan de maximale leeftijd. Anders sta je na een lange vakantie met lege handen.

Opruimen gebeurt na elke nieuwe backup van die stack, en na een geplande ronde.

---

Terugzetten

De geschiedenisknop op de stackkaart → Terugzetten. Wat er dan gebeurt:

1. docker compose down          stack stoppen
2. huidige map opzij zetten     als <stack>.restore-<tijdstempel>
3. archief uitpakken
4. opzijgezette map weggooien
5. docker compose up -d         stack starten

Gaat stap 3 mis — een beschadigd archief, of een archief dat buiten de stackmap probeert te schrijven — dan wordt de opzijgezette map teruggeplaatst. Je raakt je stack dus niet kwijt aan een kapotte backup.

Een backup van stack A kun je niet over stack B heen zetten; dat wordt geweigerd op basis van de metadata.

Veiligheid

Archieven worden uitgepakt met Pythons tarfile en filter="data". Dat weigert absolute paden, ..-ingangen, symlinks die buiten de map wijzen en apparaatbestanden. Met een kaal tar xzf zou een geprepareerd archief bestanden elders op de host kunnen neerzetten.

---

Instellingen

Sleutel	Standaard	Betekenis
BACKUP_DIR	/opt/serverup/backups	Waar de archieven komen
BACKUP_KEEP	5	Aantal per stack
BACKUP_MAX_AGE_DAYS	0	Maximale leeftijd in dagen
BACKUP_SCHEDULE	off	off / daily / weekly
BACKUP_SCHEDULE_HOUR	3	Rond welk uur de geplande ronde draait
BACKUP_BEFORE_UPDATE	true	Backup vóór het bijwerken van een stack
BACKUP_BEFORE_REMOVE	true	Backup vóór het verwijderen van bestanden

---

Handmatig

De archieven zijn gewone tarballs — je hebt Server Up niet nodig om erbij te kunnen:

# Bekijken wat erin zit
tar tzf /opt/serverup/backups/vaultwarden_20260726_030000.tar.gz

# Ergens anders uitpakken
tar xzf /opt/serverup/backups/vaultwarden_20260726_030000.tar.gz -C /tmp/herstel

Naast elk archief staat een .json met de stacknaam, het tijdstip, de grootte en de reden (handmatig, gepland, voor-update, voor-remove). Ontbreekt dat bestand, dan leidt Server Up de gegevens af uit de bestandsnaam.