Aannames
Deze keuzes heb ik gemaakt waar de opdracht niets vastlegde. Wil je iets anders, dan is het per punt aan te passen.
Opzet
- Go, net als BlueGit. Eén binary zonder CGO. De enige externe dependency is
gopkg.in/yaml.v3. - Geen webinterface op de backup server. Je bedient hem met een configbestand en de CLI. Archieven bekijken en een rollback starten gebeurt in BlueGit, zoals gevraagd.
- De CLI praat met de draaiende server via
data_dir/admin.token(eenbba_…-token, 0600). Er komt geen tweede inlogsysteem. - Eén backup server hoort bij precies één BlueGit. Dat staat in
data_dir/state.json(0600). Daar staat ook de key in, want die is nodig om op te halen en om meldingen te controleren.
Key en authenticatie
- BlueGit maakt de Backupserver-Key (
bgbk_+ 64 hex) onder Beheer → Backup en toont hem één keer. BlueGit bewaart alleensha256(key). - Er is maar één key tegelijk. Een nieuwe key maken maakt de oude ongeldig. Verwijderen ontkoppelt de server.
- Backup server → BlueGit:
Authorization: Bearer bgbk_…op/api/v1/backup/*. Vijf foute pogingen per minuut per IP-adres geven429. - BlueGit → backup server: BlueGit kent de key zelf niet meer, alleen de hash. Daarom ondertekent BlueGit met een afgeleid geheim,
sha256("bluegit-backup-sign:" + key), dat BlueGit bij het maken van de key bewaart. De handtekening is HMAC-SHA256 overMETHODE\nPAD\nTIJDSTEMPEL\nsha256(body), met hoogstens 5 minuten klokverschil. Zo kan iemand die het netwerk ziet geen rollback starten of meldingen vervalsen. - De koppeling in BlueGit (
<state>/backup.json) zit niet in de backup. Een rollback zet de koppeling dus niet terug naar een oude key. - Je koppelt met
bluegit-backup connect --url …en de key uitBLUEGIT_BACKUP_KEY(of--key). De server meldt BlueGit daarna zijnpublic_url, zodat BlueGit weet waar de meldingen heen moeten.
Wat wordt geback-upt
- Alles wat BlueGit nodig heeft om identiek terug te komen:
- de database (
bluegit.db) als consistente snapshot viaVACUUM INTO secret.key- de SSH-hostkeys
- logo's en avatars
- alle repositories
- releases en CI-artifacts
- Niet:
config.yml. Dat bestand hoort bij de machine (paden, poorten, OAuth-geheimen) en zet je zelf terug.storage_path, caches, lockbestanden, werkmappen (data/work), tijdelijke bestanden, symlinks- de backupkoppeling en het instance-id
- "Configuratie" in de opdracht lees ik als: alle instellingen die BlueGit in zijn database en state-map bewaart, plus de sleutels.
config.ymlvalt daar niet onder.
Meldingen en synchroniseren
- BlueGit meldt een wijziging na elk muterend verzoek: elke niet-GET, behalve de backup-API zelf en
git-upload-pack(clonen en fetchen). Daarnaast meldt BlueGit na elke push (HTTP en SSH) en na elk intern event, zoals CI of releases. - Meldingen worden 2 seconden gebundeld en tot 4 keer opnieuw geprobeerd. Een melding bevat geen data, alleen "er is iets veranderd" (
POST /api/v1/notify). - Na een melding vraagt de backup server een manifest op: een lijst van paden met grootte en mtime, en voor de database een sha256. Hij haalt alleen nieuwe of gewijzigde bestanden op en verwijdert wat in BlueGit weg is.
- Tussen twee syncs na meldingen zit minstens
min_sync_interval(10s). Meldingen die tijdens een sync binnenkomen, geven precies één vervolgsync. - Mist de server een melding (omdat hij uit stond of het netwerk weg was), dan vangt de volledige controle elk
full_sync_interval(1u) dat op, en ook een herstart. - Een bestand dat tijdens het downloaden verandert (grootte klopt niet), wordt bij de volgende sync opnieuw opgehaald.
Gedoseerd downloaden
- Een token bucket begrenst de downloadsnelheid tot
rate_limit_kibKiB/s (standaard 1024, dus 1 MiB/s), over alle downloads samen. - Er is altijd maar één download tegelijk. BlueGit krijgt dus nooit meer dan één verzoek tegelijk van de backup server.
- De database-snapshot kost BlueGit eenmalig een
VACUUM INTOper manifest. Bij een grote database is dat het zwaarste deel, maar het blokkeert schrijvers in WAL-modus niet.
Archieven
- Formaat:
tar.gz(PAX), met de lopende kopie als inhoud (state/…endata/…). Je kunt een archief dus ook met de hand uitpakken. - Naam:
bluegit-YYYYMMDD-HHMMSS.tar.gzin UTC, met-2,-3, … als er in dezelfde seconde meer zijn. - Het eerste archief komt binnen een minuut na de eerste geslaagde sync, daarna elk
archive_interval(standaard 24u). - Er wordt eerst naar een tijdelijk bestand geschreven en daarna hernoemd. Een half archief komt dus nooit in de lijst.
- Opruimen:
- Archieven ouder dan
retention_daysgaan weg. - Is er minder dan
min_free_mbvrij op de schijf vandata_dir, dan gaat het oudste archief weg, net zo lang tot er genoeg vrij is. - Het nieuwste archief blijft altijd staan, ook als het te oud is. Anders zou er geen backup meer zijn.
- Is er vóór een nieuw archief niet genoeg ruimte, dan mogen alle oude archieven weg om plaats te maken. Het nieuwe archief wordt dan het enige.
Rollback
- De beheerder start de rollback in BlueGit onder Beheer → Backup. Daar staat een grote rode waarschuwing: "Dit kan niet ongedaan worden gemaakt". Er moet een vinkje gezet worden en de archiefnaam overgetypt. De API vraagt
"confirm": "<archiefnaam>". - Het verloop:
1. De backup server pakt het archief uit in mirror.rollback. 2. Hij zet dat op de plaats van zijn lopende kopie. 3. Hij stuurt alles als tar.gz naar BlueGit (POST /api/v1/backup/restore). 4. BlueGit zet de data klaar, weigert ondertussen alle wijzigingen (503) en herstart zichzelf (zelfde PID, exec). 5. Bij het opstarten wisselt BlueGit de bestanden om, nog voordat de database opengaat.
- Lukt het versturen niet, dan zet de backup server zijn oude kopie terug. Er gaat dan niets verloren.
- Archieven die nieuwer zijn dan het teruggezette archief blijven bewaard. Een rollback naar een te oud archief is zo nog te herstellen met een nieuwere rollback, maar alleen voor wat er in die archieven zat.
- Het upload-verkeer naar BlueGit bij een rollback is niet gedoseerd. BlueGit staat dan toch al stil, en een snelle terugzet is belangrijker.
Nieuwe instantie
- Een BlueGit wordt herkend aan zijn
instance_id(<state>/instance_id). Een andere URL met hetzelfde instance-id is dezelfde instantie, bijvoorbeeld na een verhuizing. - Koppel je een andere instantie, dan weigert de server (
409) en moet je kiezen: - wissen: de oude kopie en alle archieven gaan weg, en de nieuwe instantie wordt opnieuw opgehaald.
- herstellen: de lopende kopie (de stand van de laatste sync, nieuwer dan elk archief) wordt naar de nieuwe BlueGit gestuurd, net als bij een rollback. Daarna hoort de server bij de nieuwe instantie. De oude archieven blijven staan.
connectvraagt de keuze in de terminal. Zonder keuze (lege invoer) gebeurt er niets. Zonder terminal gebruik je--on-conflict wipe|restore.- De nieuwe BlueGit moet al draaien met een eigen
config.ymlen data-schijf. Het herstel vult alleen de inhoud.
Releases en tests
- "Dezelfde release-opties als BlueGit" betekent:
- een AUR-pakket
bluegit-backupdat vanaf master wordt bijgewerkt - een self-update van een geïnstalleerde server vanuit de pipeline (via een systemd-unit, net als BlueGit)
- binaries bij een tag
- Elke release-job hangt af van de job
integration. Die bouwt een echte BlueGit uittimfa/bluegiten draait alle featuretests. Faalt er één, dan komt er geen release. - Releases vanaf master staan pas aan zodra
.release-enabledin de repository staat. Tim beslist wanneer, en zet ook de geheimen (AUR-sleutel, update-token). Tags zet Tim zelf. - De integratietests bouwen BlueGit van de ref in
.bluegit-ref. Tot de BlueGit-kant gemerged is, is datfeature/backup-server. Daarna wordt hetmaster. - De integratietests draaien nooit tegen een echte BlueGit-installatie. Elke test start een eigen BlueGit in een tijdelijke map, met de dev-login en zonder SSH of CI-runner.
- Het AUR-pakket haalt de broncode van
https://git.timfalken.com/timfa/bluegit-backup/-/archive/<commit>/…. Daarom is de repository openbaar, net alstimfa/bluegit.
Source
| 1 | # Aannames |
| 2 | |
| 3 | Deze keuzes heb ik gemaakt waar de opdracht niets vastlegde. Wil je iets anders, dan is het per punt aan te passen. |
| 4 | |
| 5 | ## Opzet |
| 6 | |
| 7 | - **Go**, net als BlueGit. Eén binary zonder CGO. De enige externe dependency is `gopkg.in/yaml.v3`. |
| 8 | - **Geen webinterface op de backup server.** Je bedient hem met een configbestand en de CLI. Archieven bekijken en een rollback starten gebeurt in BlueGit, zoals gevraagd. |
| 9 | - De CLI praat met de draaiende server via `data_dir/admin.token` (een `bba_…`-token, 0600). Er komt geen tweede inlogsysteem. |
| 10 | - Eén backup server hoort bij precies één BlueGit. Dat staat in `data_dir/state.json` (0600). Daar staat ook de key in, want die is nodig om op te halen en om meldingen te controleren. |
| 11 | |
| 12 | ## Key en authenticatie |
| 13 | |
| 14 | - BlueGit maakt de Backupserver-Key (`bgbk_` + 64 hex) onder *Beheer → Backup* en toont hem één keer. BlueGit bewaart alleen `sha256(key)`. |
| 15 | - Er is maar één key tegelijk. Een nieuwe key maken maakt de oude ongeldig. Verwijderen ontkoppelt de server. |
| 16 | - **Backup server → BlueGit:** `Authorization: Bearer bgbk_…` op `/api/v1/backup/*`. Vijf foute pogingen per minuut per IP-adres geven `429`. |
| 17 | - **BlueGit → backup server:** BlueGit kent de key zelf niet meer, alleen de hash. Daarom ondertekent BlueGit met een afgeleid geheim, `sha256("bluegit-backup-sign:" + key)`, dat BlueGit bij het maken van de key bewaart. De handtekening is HMAC-SHA256 over `METHODE\nPAD\nTIJDSTEMPEL\nsha256(body)`, met hoogstens 5 minuten klokverschil. Zo kan iemand die het netwerk ziet geen rollback starten of meldingen vervalsen. |
| 18 | - De koppeling in BlueGit (`<state>/backup.json`) zit **niet** in de backup. Een rollback zet de koppeling dus niet terug naar een oude key. |
| 19 | - Je koppelt met `bluegit-backup connect --url … ` en de key uit `BLUEGIT_BACKUP_KEY` (of `--key`). De server meldt BlueGit daarna zijn `public_url`, zodat BlueGit weet waar de meldingen heen moeten. |
| 20 | |
| 21 | ## Wat wordt geback-upt |
| 22 | |
| 23 | - Alles wat BlueGit nodig heeft om identiek terug te komen: |
| 24 | - de database (`bluegit.db`) als consistente snapshot via `VACUUM INTO` |
| 25 | - `secret.key` |
| 26 | - de SSH-hostkeys |
| 27 | - logo's en avatars |
| 28 | - alle repositories |
| 29 | - releases en CI-artifacts |
| 30 | - **Niet:** |
| 31 | - `config.yml`. Dat bestand hoort bij de machine (paden, poorten, OAuth-geheimen) en zet je zelf terug. |
| 32 | - `storage_path`, caches, lockbestanden, werkmappen (`data/work`), tijdelijke bestanden, symlinks |
| 33 | - de backupkoppeling en het instance-id |
| 34 | - "Configuratie" in de opdracht lees ik als: alle instellingen die BlueGit in zijn database en state-map bewaart, plus de sleutels. `config.yml` valt daar niet onder. |
| 35 | |
| 36 | ## Meldingen en synchroniseren |
| 37 | |
| 38 | - BlueGit meldt een wijziging na elk muterend verzoek: elke niet-GET, behalve de backup-API zelf en `git-upload-pack` (clonen en fetchen). Daarnaast meldt BlueGit na elke push (HTTP en SSH) en na elk intern event, zoals CI of releases. |
| 39 | - Meldingen worden 2 seconden gebundeld en tot 4 keer opnieuw geprobeerd. Een melding bevat geen data, alleen "er is iets veranderd" (`POST /api/v1/notify`). |
| 40 | - Na een melding vraagt de backup server een manifest op: een lijst van paden met grootte en mtime, en voor de database een sha256. Hij haalt alleen nieuwe of gewijzigde bestanden op en verwijdert wat in BlueGit weg is. |
| 41 | - Tussen twee syncs na meldingen zit minstens `min_sync_interval` (10s). Meldingen die tijdens een sync binnenkomen, geven precies één vervolgsync. |
| 42 | - Mist de server een melding (omdat hij uit stond of het netwerk weg was), dan vangt de volledige controle elk `full_sync_interval` (1u) dat op, en ook een herstart. |
| 43 | - Een bestand dat tijdens het downloaden verandert (grootte klopt niet), wordt bij de volgende sync opnieuw opgehaald. |
| 44 | |
| 45 | ## Gedoseerd downloaden |
| 46 | |
| 47 | - Een token bucket begrenst de downloadsnelheid tot `rate_limit_kib` KiB/s (standaard 1024, dus 1 MiB/s), over alle downloads samen. |
| 48 | - Er is altijd maar één download tegelijk. BlueGit krijgt dus nooit meer dan één verzoek tegelijk van de backup server. |
| 49 | - De database-snapshot kost BlueGit eenmalig een `VACUUM INTO` per manifest. Bij een grote database is dat het zwaarste deel, maar het blokkeert schrijvers in WAL-modus niet. |
| 50 | |
| 51 | ## Archieven |
| 52 | |
| 53 | - Formaat: `tar.gz` (PAX), met de lopende kopie als inhoud (`state/…` en `data/…`). Je kunt een archief dus ook met de hand uitpakken. |
| 54 | - Naam: `bluegit-YYYYMMDD-HHMMSS.tar.gz` in UTC, met `-2`, `-3`, … als er in dezelfde seconde meer zijn. |
| 55 | - Het eerste archief komt binnen een minuut na de eerste geslaagde sync, daarna elk `archive_interval` (standaard 24u). |
| 56 | - Er wordt eerst naar een tijdelijk bestand geschreven en daarna hernoemd. Een half archief komt dus nooit in de lijst. |
| 57 | - **Opruimen:** |
| 58 | - Archieven ouder dan `retention_days` gaan weg. |
| 59 | - Is er minder dan `min_free_mb` vrij op de schijf van `data_dir`, dan gaat het oudste archief weg, net zo lang tot er genoeg vrij is. |
| 60 | - Het nieuwste archief blijft altijd staan, ook als het te oud is. Anders zou er geen backup meer zijn. |
| 61 | - Is er vóór een nieuw archief niet genoeg ruimte, dan mogen alle oude archieven weg om plaats te maken. Het nieuwe archief wordt dan het enige. |
| 62 | |
| 63 | ## Rollback |
| 64 | |
| 65 | - De beheerder start de rollback in BlueGit onder *Beheer → Backup*. Daar staat een grote rode waarschuwing: "Dit kan niet ongedaan worden gemaakt". Er moet een vinkje gezet worden en de archiefnaam overgetypt. De API vraagt `"confirm": "<archiefnaam>"`. |
| 66 | - Het verloop: |
| 67 | 1. De backup server pakt het archief uit in `mirror.rollback`. |
| 68 | 2. Hij zet dat op de plaats van zijn lopende kopie. |
| 69 | 3. Hij stuurt alles als `tar.gz` naar BlueGit (`POST /api/v1/backup/restore`). |
| 70 | 4. BlueGit zet de data klaar, weigert ondertussen alle wijzigingen (503) en herstart zichzelf (zelfde PID, `exec`). |
| 71 | 5. Bij het opstarten wisselt BlueGit de bestanden om, nog voordat de database opengaat. |
| 72 | - Lukt het versturen niet, dan zet de backup server zijn oude kopie terug. Er gaat dan niets verloren. |
| 73 | - Archieven die nieuwer zijn dan het teruggezette archief blijven bewaard. Een rollback naar een te oud archief is zo nog te herstellen met een nieuwere rollback, maar alleen voor wat er in die archieven zat. |
| 74 | - Het upload-verkeer naar BlueGit bij een rollback is **niet** gedoseerd. BlueGit staat dan toch al stil, en een snelle terugzet is belangrijker. |
| 75 | |
| 76 | ## Nieuwe instantie |
| 77 | |
| 78 | - Een BlueGit wordt herkend aan zijn `instance_id` (`<state>/instance_id`). Een andere URL met hetzelfde instance-id is dezelfde instantie, bijvoorbeeld na een verhuizing. |
| 79 | - Koppel je een andere instantie, dan weigert de server (`409`) en moet je kiezen: |
| 80 | - **wissen**: de oude kopie en alle archieven gaan weg, en de nieuwe instantie wordt opnieuw opgehaald. |
| 81 | - **herstellen**: de lopende kopie (de stand van de laatste sync, nieuwer dan elk archief) wordt naar de nieuwe BlueGit gestuurd, net als bij een rollback. Daarna hoort de server bij de nieuwe instantie. De oude archieven blijven staan. |
| 82 | - `connect` vraagt de keuze in de terminal. Zonder keuze (lege invoer) gebeurt er niets. Zonder terminal gebruik je `--on-conflict wipe|restore`. |
| 83 | - De nieuwe BlueGit moet al draaien met een eigen `config.yml` en data-schijf. Het herstel vult alleen de inhoud. |
| 84 | |
| 85 | ## Releases en tests |
| 86 | |
| 87 | - "Dezelfde release-opties als BlueGit" betekent: |
| 88 | - een AUR-pakket `bluegit-backup` dat vanaf master wordt bijgewerkt |
| 89 | - een self-update van een geïnstalleerde server vanuit de pipeline (via een systemd-unit, net als BlueGit) |
| 90 | - binaries bij een tag |
| 91 | - Elke release-job hangt af van de job `integration`. Die bouwt een echte BlueGit uit `timfa/bluegit` en draait alle featuretests. Faalt er één, dan komt er geen release. |
| 92 | - **Releases vanaf master staan pas aan zodra `.release-enabled` in de repository staat.** Tim beslist wanneer, en zet ook de geheimen (AUR-sleutel, update-token). Tags zet Tim zelf. |
| 93 | - De integratietests bouwen BlueGit van de ref in `.bluegit-ref`. Tot de BlueGit-kant gemerged is, is dat `feature/backup-server`. Daarna wordt het `master`. |
| 94 | - De integratietests draaien nooit tegen een echte BlueGit-installatie. Elke test start een eigen BlueGit in een tijdelijke map, met de dev-login en zonder SSH of CI-runner. |
| 95 | - Het AUR-pakket haalt de broncode van `https://git.timfalken.com/timfa/bluegit-backup/-/archive/<commit>/…`. Daarom is de repository openbaar, net als `timfa/bluegit`. |