# Aannames Deze keuzes heb ik gemaakt waar de opdracht niets vastlegde. Wil je iets anders, dan is het per punt aan te passen. ## Eén repository en releasepakketten (16-11-2026) - **bluegit-backup in timfa/bluegit**: met history samengevoegd (git filter-repo, daarna een merge). `internal/*` van de backup server staat in `internal/backupserver/*`, de integratietests in `internal/backupserver/integration`, de packaging in `packaging/backup` en `packaging/aur-backup`, de README in `docs/BACKUP-SERVER.md` en het protocol in `docs/BACKUP-PROTOCOL.md`. Deze aannames kwamen ook uit die repository. `scripts/build-bluegit.sh` en `.bluegit-ref` zijn vervallen: de integratietests bouwen BlueGit in `TestMain` uit dezelfde checkout. - De twee protocolpakketten (`internal/backup` aan de BlueGit-kant en `internal/backupserver/protocol`) blijven apart. Zo kunnen de integratietests een oudere of nieuwere kant nabootsen. - **AUR**: `bluegit-backup` gaat vanaf master via `publish_aur_backup` met dezelfde AUR-geheimen als `bluegit` en `bluegit-runner`, en hangt ook af van `backup_integration`. De pkgver blijft de commit-tijd in UTC, dus het versienummer loopt door. - **Pakketten**: nfpm (v2.43.0, vastgezet) maakt .deb, .rpm en .pkg.tar.zst voor amd64 en arm64. Inhoud, unit, gebruiker en config komen uit de PKGBUILDs. Het Arch-pakket heeft net als de AUR `docker` als dependency voor bluegit en bluegit-runner. Bij deb en rpm is docker alleen een aanbeveling, omdat de pakketnaam per distro verschilt (docker.io, docker-ce, moby-engine). De rpm's hangen af van `shadow-utils` voor useradd. - De pakketten maken de gebruiker met systemd-sysusers, of met groupadd/useradd als dat er niet is (kale containers). Ze zetten de service niet aan en herstarten hem alleen als hij al draaide. Verwijderen zet de service uit en laat gebruiker, config en `/var/lib/` staan. - `bluegit-update` (de self-update via makepkg/pacman) en de gebruiker `bluegit-build` zitten alleen in het AUR-pakket. - **Bestandsnamen** in de release hebben geen versie (`bluegit_amd64.deb`, `bluegit.x86_64.rpm`, `bluegit-x86_64.pkg.tar.zst`, `bluegit-windows-amd64.zip`), zodat de artifact-paden vast zijn en `SHA256SUMS` er precies bij past. De versie staat in het pakket zelf: tag `v1.2.3` wordt `1.2.3-1`, en `v1.0.0-rc1` wordt `1.0.0.rc1`, omdat archlinux geen `-` in pkgver toestaat. Builds zonder tag krijgen `0.0.0.git`. - `--version` (ook `version`) toont `main.version` of `server.Version`: de tag bij een release, de korte sha op andere pipelines en `dev` zonder ldflag (AUR en self-update). - De installatietest draait alleen voor amd64. De arm64-pakketten worden wel gebouwd, maar de runner heeft geen arm64. - Package-artifacts blijven 3 dagen bewaard, omdat ze groot zijn (ongeveer 200 MB per pipeline). De release kopieert ze meteen. - **Release**: alleen bij een tag `v*`, via het create-only endpoint `POST …/releases/{tag}/assets`, en alleen als vet, test, frontend_checks, backup_integration, package en alle vijf installatietests slagen. Het tagpatroon `v*` is beschermd. ## Windows-builds (17-11-2026) - De pipeline bouwt `bluegit`, `bluegit-runner` en `bluegit-backup` ook voor `windows/amd64` en `windows/arm64` (cross-compile in de job `binaries`, CGO uit). Dat is tegelijk een compileercheck: `GOOS=windows go build ./...` voor beide architecturen. Een tag-release krijgt extra zips (`-windows-.zip` met daarin `.exe`); die staan in `SHA256SUMS`. Er komt geen Windows-installer, geen service en geen zelfupdate. - Schijfruimte gaat via `internal/diskusage`: op Unix `statfs`, op Windows `GetDiskFreeSpaceEx`. Het werkgeheugen van de runner komt op Linux uit `/proc/meminfo` en op Windows uit `GlobalMemoryStatusEx`. Een herstart na een backup-restore gebruikt op Unix `syscall.Exec` (zelfde PID) en op Windows een kindproces (`internal/reexec`); de PID verandert daar. - Standaardpaden op Windows: `%LOCALAPPDATA%\BlueGit` (state en config), `%LOCALAPPDATA%\BlueGit-runner` en `%LOCALAPPDATA%\BlueGit-backup`. Op Linux blijven `/etc/...` en `/var/lib/...` ongewijzigd. `bluegit example-config` blijft de mini-PC-configuratie printen (Linux-paden). - De runner op Windows is alleen zinvol met Docker Desktop (Linux-engine). Jobs blijven Linux-containers (`#!/bin/sh`, `/workspace`). Systemd na `register` wordt overgeslagen (`Geteuid` is −1). Git-hooks blijven `#!/bin/sh`-scripts; dat werkt met Git for Windows. Unix-modes (`0600`) worden op NTFS niet afgedwongen; dat staat in de README. Geen test-runner voor Windows in de CI: de jobs draaien op Linux en controleren alleen of het kruisbouwen lukt. ## Backup server (uit timfa/bluegit-backup) ### Opzet - **Go**, net als BlueGit. Eén binary zonder CGO. De enige externe dependency is `gopkg.in/yaml.v3`. - 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. ### Webinterface en API - De webinterface draait op hetzelfde adres als de API, standaard `0.0.0.0:8080`. Er komt geen aparte poort voor BlueGit: BlueGit praat met dezelfde server (ondertekend). - **Inloggen gaat met het beheertoken** uit `data_dir/admin.token` (`bba_…`, 0600). Dat token gebruiken ook de API en de CLI. Er komt geen apart gebruikersbeheer: de backup server heeft één beheerder. `bluegit-backup token` toont het token. - Sessies staan alleen in het geheugen. Een herstart logt iedereen uit. - Elke handeling staat in één lijst (`Actions`). De API-routes en de formulieren van de webinterface komen allebei uit die lijst, en een formulier roept dezelfde code aan als de API. Daardoor kan de API alles wat de webinterface kan, en andersom. Een unit-test controleert dat elke wijzigende actie een formulier heeft en elk formulier een actie. De integratietests falen als er een actie bij komt die niet getest wordt. - "Alles instellen" betekent: alle velden uit `config.yml` behalve `data_dir`. In die map staan de instellingen zelf, dus die blijft in `config.yml`. Wat via de webinterface, API of BlueGit is ingesteld, gaat naar `data_dir/settings.yml`. Dat bestand gaat boven `config.yml`, zodat `config.yml` van root kan blijven. `listen` geldt pas na een herstart, de rest meteen (ook de downloadsnelheid tijdens een lopende sync). - In de webinterface kun je ook een rollback starten en een archief downloaden of verwijderen. De rollback heeft dezelfde waarschuwing en bevestiging als in BlueGit. - De webinterface is gewone HTML zonder JavaScript, in het Nederlands. Hij weigert framing (`X-Frame-Options: DENY`). Daarom bedient BlueGit de backup server via de API en niet met een iframe. ### Bediening vanuit BlueGit - Tim gaf de keuze tussen een iframe of een API-koppeling met een vergelijkbare interface. Ik koos de **API-koppeling**: - Een iframe zou een tweede login vragen. - Het werkt niet als de backup server alleen voor BlueGit bereikbaar is en niet voor de browser. - Het opent de deur voor clickjacking. - BlueGit vraagt de lijst met acties op (`GET /api/v1/admin/actions`) en stuurt een gekozen actie ondertekend door. Een nieuwe actie in de backup server werkt daardoor in BlueGit zonder BlueGit aan te passen, zolang hij voor BlueGit is opengezet. - **Niet** vanuit BlueGit: - **koppelen**: dat vraagt de key op de backup server zelf. - **een archief downloaden**: een archief van gigabytes hoort niet door BlueGit heen te lopen. - De instellingen in BlueGit tonen de labels en uitleg van de backup server, dus in het Nederlands. Wat BlueGit er zelf omheen zet, is vertaald (en, nl, de, fr). - Verwijdert een beheerder een backup server in BlueGit, dan vraagt BlueGit de backup server eerst om te ontkoppelen. De kopie en de archieven blijven op de backup server staan. ### Meerdere backup servers - Eén BlueGit kan tot **16** backup servers hebben, elk met een eigen naam en key. Dat zijn er genoeg voor een paar plekken (bijvoorbeeld thuis en offsite), en het begrenst het aantal meldingen per wijziging. - Elke backup server krijgt elke melding, parallel. Een server die niet reageert, houdt de andere niet op. - Een rollback kan vanaf elke gekoppelde backup server. De andere servers zien de teruggezette stand bij hun volgende sync. - Koppelt een tweede backup server met dezelfde key, dan gaat de koppeling (het adres voor meldingen) naar die server. Een key hoort bij één server. Geef een nieuwe server een eigen key. - `backup.json` bevat nu een lijst met servers. De oude vorm met één koppeling wordt bij het lezen omgezet. ### Key en authenticatie - BlueGit maakt per backup server een Backupserver-Key (`bgbk_` + 64 hex) onder *Beheer → Backup* en toont hem één keer. BlueGit bewaart alleen `sha256(key)`. - Een nieuwe key voor een server maakt zijn oude key ongeldig. Verwijderen ontkoppelt die server. - **Backup server → BlueGit:** `Authorization: Bearer bgbk_…` op `/api/v1/backup/*`. Vijf foute pogingen per minuut per IP-adres geven `429`. - **BlueGit → backup server** (meldingen, archieflijst, status, rollback en de beheeracties): 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. Binnen die 5 minuten kan een afgeluisterd verzoek wel opnieuw worden gestuurd. Gebruik TLS als het netwerk tussen BlueGit en de backup server niet te vertrouwen is. - De koppeling in BlueGit (`/backup.json`) zit **niet** in de backup. Een rollback zet de koppeling dus niet terug naar een oude key. - Je koppelt in de webinterface, met de API, of 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. ### Wat wordt geback-upt - Alles wat BlueGit nodig heeft om identiek terug te komen: - de database (`bluegit.db`) als consistente snapshot via `VACUUM 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.yml` valt 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_kib` KiB/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 INTO` per 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/…` en `data/…`). Je kunt een archief dus ook met de hand uitpakken. - Naam: `bluegit-YYYYMMDD-HHMMSS.tar.gz` in 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_days` gaan weg. - 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. - 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": ""`. - 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` (`/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. - `connect` vraagt 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.yml` en data-schijf. Het herstel vult alleen de inhoud. ### Compatibiliteit (t1209u) - Elke kant heeft een **protocolversie** (een geheel getal, wat hij spreekt) en een **minimumversie** (de oudste versie van de andere kant die hij nog ondersteunt). Geen min/max: een nieuwere kant geeft zelf aan tot hoe ver terug hij de ander nog ondersteunt; dat dekt beide richtingen. - Ze passen als de backup server minstens het minimum van BlueGit spreekt en BlueGit minstens het minimum van de backup server. Anders: `backup_too_old` (BlueGit vraagt meer) of `bluegit_too_old` (de backup server vraagt meer). Vraagt allebei meer, dan meldt BlueGit `backup_too_old`. - Nu: BlueGit protocol 1 (minimum 1), bluegit-backup protocol 1 (minimum 1). Wat tot nu toe bestond (BlueGit tot en met de backup-merge, bluegit-backup v0.1.0) stuurt geen protocol en geldt als protocol 1; die blijven dus samenwerken met deze versie. - Het protocol gaat de **volgende keer omhoog** als een wijziging oude tegenpartijen breekt. Het minimum gaat pas omhoog als die oude versie echt niet meer werkt. - **Uitwisseling**: koppen op elk verzoek en antwoord tussen de twee (`X-BlueGit-Protocol`/`-Min-Protocol`/`-Version` van BlueGit, `X-Backup-Protocol`/`-Min-Protocol`/`-Version` van de backup server), en `protocol`/`min_protocol`/`version` in `GET /api/v1/backup/info`. Zo hoort de backup server het bij info, sync en elke melding, en BlueGit bij elk verzoek met de key en elk antwoord op een melding of beheeractie. - BlueGit bewaart het laatst gemelde protocol per backup server in `backup.json`. De banner leest alleen dat bestand (geen netwerkverkeer bij elke pagina). Een nieuwe key wist het, tot de server zich opnieuw meldt. - **Banner**: alleen voor instance-beheerders, bovenaan elke HTML-pagina (onder de kopbalk), per niet-passende backup server één regel: de naam, of BlueGit of de backup server geüpdatet moet worden, beide protocolnummers, en een link naar Beheer → Backup. In het Engels, Nederlands, Duits en Frans (en spijkerschrift via het Engels). - **Weigeren**: BlueGit geeft `426 Upgrade Required` op `manifest`, `file` en `restore`. `info` en `connect` blijven werken, zodat een niet-passende server toch kan koppelen en de beheerder de banner ziet. De backup server vraagt vóór elke sync, rollback en restore `info` op en weigert zelf (`409`); een rollback vanuit BlueGit weigert hij als het laatst gemelde protocol niet past. Archieven bekijken, downloaden, verwijderen en instellingen blijven werken. - De backup server toont het in zijn webinterface (banner bovenaan, regel *Protocol* in het overzicht) en in `GET /api/v1/admin/status` (`protocol`, `min_protocol`, `bluegit_protocol`, `bluegit_min_protocol`, `bluegit_version`, `compat`, `compat_message`). - **Versie**: de backup server meldt `Version` (bij het bouwen gezet). BlueGit heeft geen versienummer en meldt de commit uit de build-info (12 tekens), of `dev`. - **Tests**: "backup te oud" bootsen we na met een test-build van BlueGit met `-ldflags -X …/internal/backup.protocolVersion=99 -X ….minBackupProtocol=99` (`scripts/build-bluegit.sh` bouwt die naast de gewone). "BlueGit te oud" bootsen we na door in de test het protocol van de backup server (die in het testproces draait) op 2 met minimum 2 te zetten. Een gebruiker die geen beheerder is, maken we door dezelfde BlueGit te herstarten met een andere dev-gebruiker. ### Releases en tests Tot 16-11-2026, toen dit nog een aparte repository was. Wat er sindsdien geldt, staat bovenaan. - "Dezelfde release-opties als BlueGit" betekent: - een AUR-pakket `bluegit-backup` dat vanaf master wordt bijgewerkt - binaries bij een tag - Geen self-update (Tim, 2026-11-15, t1209u): gebruikers updaten de backup server zelf (AUR-helper of een nieuwe binary). Er is geen update-endpoint, geen update-unit en geen pipeline-job die een server bijwerkt. - 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. - Releases vanaf master staan aan zodra `.release-enabled` in de repository staat. Zonder dat bestand doen de release-scripts niets. - De integratietests bouwen BlueGit van de ref in `.bluegit-ref` (`master`; tijdens de compatibiliteitswijziging tijdelijk `feature/backup-compat`, tot die in BlueGit gemerged is). - 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//…`. Daarom is de repository openbaar, net als `timfa/bluegit`.