BlueGit

timfa bluegit

Files

bluegit / docs / ASSUMPTIONS.md

ASSUMPTIONS.md

ASSUMPTIONS.md 21.9 KiB Download Raw

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/<naam> 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<sha>.
  • --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 (<naam>-windows-<arch>.zip met daarin <naam>.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 (in deze repository, voorheen 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 instelbare staat in de webinterface en de API (dezelfde velden). Dat gaat naar data_dir/settings.yml. Er is geen config.yml meer nodig. Bestaat /etc/bluegit-backup/config.yml (of een bij upgrade bewaarde legacy-config.yml) nog, dan wordt die één keer overgenomen; daarna wint de webinterface. De dienst logt dat config.yml niet meer nodig is.
  • data_dir is een opstartinstelling (standaard /var/lib/bluegit-backup, of %LOCALAPPDATA%\BlueGit-backup op Windows), te zetten met --data-dir of BLUEGIT_BACKUP_DATA_DIR. In die map staat settings.yml zelf, dus dit pad kan niet zinvol vanuit de UI veranderen. De UI toont het alleen-lezen, met die uitleg.
  • listen is in de UI te wijzigen en geldt meteen: de server probeert het nieuwe adres te binden. Lukt dat niet, dan blijft de oude listener staan, wordt er niets bewaard, en zegt de UI waar hij nog luistert. Lukt het wel, dan staat in de melding het nieuwe adres.
  • public_url mag een domein of een IP-adres zijn (http://192.168.1.50:8080, IPv6 als http://[2001:db8::1]:8080). Validatie eist alleen http:// of https:// en een host. BlueGit praat met de backup server via een gewone http.Client (niet de SSRF-client van webhooks), dus een IP-URL werkte al; dat is nu met tests vastgelegd.
  • Wat niet in de webinterface kan (en waarom):
  • data_dir — zie hierboven; de instellingen staan in die map.
  • Het proces starten (serve) en de eerste aanmaak van admin.token — je moet ergens inloggen. Het token-commando staat in het installatiebericht en op de loginpagina; na het inloggen toont de UI het token (voor de API en opnieuw inloggen).
  • Een eenmalige import van een oude config.yml (achterwaartse compatibiliteit, geen dagelijkse instelling).
  • Koppelen (URL, Backupserver-Key, en bij een andere BlueGit de keuze wissen of herstellen) kan volledig in de webinterface, sectie Koppeling. De CLI blijft een alternatief.
  • De voortgang van de synchronisatie is het aandeel van de BlueGit-dataset (bytes van bestanden uit het laatste manifest die aanwezig en actueel zijn) dat al in de kopie staat. 100% alleen als alle bestanden kloppen. Die waarde staat in status.sync (optioneel, protocol 2, minimum blijft 1 zodat oude peers geen banner krijgen) en gaat ook naar BlueGit (POST /api/v1/backup/progress). Beide webinterfaces tonen een balk; onbekend/offline/niet-compatibel worden als tekst getoond, geen misleidende 100%. Op de BlueGit-lijst ververst de pagina periodiek zolang een server nog niet op 100% zit.
  • 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 (<state>/backup.json) zit niet in de backup. Een rollback zet de koppeling dus niet terug naar een oude key.
  • Je koppelt in de webinterface (of via de API). De CLI bluegit-backup connect --url … met de key uit BLUEGIT_BACKUP_KEY (of --key) is een alternatief. 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. Naast de bestanden bevat het voor elke bare repository de mappen refs/, refs/heads/, refs/tags/, objects/, objects/info/ en objects/pack/, ook als ze leeg zijn. Staan alle refs in packed-refs (na git gc of git pack-refs --all), dan is refs/ leeg; zonder die map is de map na uitpakken geen git-repository.
  • 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": "<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.
  • 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 bluegit-backup haalt de broncode uit het archief van timfa/bluegit (dezelfde repository), net als bluegit en bluegit-runner.
Source
1# Aannames
2
3Deze keuzes heb ik gemaakt waar de opdracht niets vastlegde. Wil je iets anders, dan is het per punt aan te passen.
4
5## Eén repository en releasepakketten (16-11-2026)
6
7- **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.
8- 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.
9- **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.
10- **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.
11- 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/<naam>` staan.
12- `bluegit-update` (de self-update via makepkg/pacman) en de gebruiker `bluegit-build` zitten alleen in het AUR-pakket.
13- **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<sha>`.
14- `--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).
15- De installatietest draait alleen voor amd64. De arm64-pakketten worden wel gebouwd, maar de runner heeft geen arm64.
16- Package-artifacts blijven 3 dagen bewaard, omdat ze groot zijn (ongeveer 200 MB per pipeline). De release kopieert ze meteen.
17- **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.
18
19
20## Windows-builds (17-11-2026)
21
22- 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 (`<naam>-windows-<arch>.zip` met daarin `<naam>.exe`); die staan in `SHA256SUMS`. Er komt geen Windows-installer, geen service en geen zelfupdate.
23- 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.
24- 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).
25- 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.
26
27## Backup server (in deze repository, voorheen timfa/bluegit-backup)
28
29### Opzet
30
31- **Go**, net als BlueGit. Eén binary zonder CGO. De enige externe dependency is `gopkg.in/yaml.v3`.
32- 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.
33
34### Webinterface en API
35
36- 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).
37- **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.
38- Sessies staan alleen in het geheugen. Een herstart logt iedereen uit.
39- 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.
40- Alles instelbare staat in de webinterface en de API (dezelfde velden). Dat gaat naar `data_dir/settings.yml`. Er is geen `config.yml` meer nodig. Bestaat `/etc/bluegit-backup/config.yml` (of een bij upgrade bewaarde `legacy-config.yml`) nog, dan wordt die **één keer** overgenomen; daarna wint de webinterface. De dienst logt dat `config.yml` niet meer nodig is.
41- `data_dir` is een opstartinstelling (standaard `/var/lib/bluegit-backup`, of `%LOCALAPPDATA%\BlueGit-backup` op Windows), te zetten met `--data-dir` of `BLUEGIT_BACKUP_DATA_DIR`. In die map staat `settings.yml` zelf, dus dit pad kan niet zinvol vanuit de UI veranderen. De UI toont het alleen-lezen, met die uitleg.
42- `listen` is in de UI te wijzigen en geldt **meteen**: de server probeert het nieuwe adres te binden. Lukt dat niet, dan blijft de oude listener staan, wordt er niets bewaard, en zegt de UI waar hij nog luistert. Lukt het wel, dan staat in de melding het nieuwe adres.
43- `public_url` mag een domein of een IP-adres zijn (`http://192.168.1.50:8080`, IPv6 als `http://[2001:db8::1]:8080`). Validatie eist alleen `http://` of `https://` en een host. BlueGit praat met de backup server via een gewone `http.Client` (niet de SSRF-client van webhooks), dus een IP-URL werkte al; dat is nu met tests vastgelegd.
44- Wat **niet** in de webinterface kan (en waarom):
45 - `data_dir` — zie hierboven; de instellingen staan in die map.
46 - Het proces starten (`serve`) en de eerste aanmaak van `admin.token` — je moet ergens inloggen. Het token-commando staat in het installatiebericht en op de loginpagina; na het inloggen toont de UI het token (voor de API en opnieuw inloggen).
47 - Een eenmalige import van een oude `config.yml` (achterwaartse compatibiliteit, geen dagelijkse instelling).
48- Koppelen (URL, Backupserver-Key, en bij een andere BlueGit de keuze wissen of herstellen) kan volledig in de webinterface, sectie *Koppeling*. De CLI blijft een alternatief.
49- De voortgang van de synchronisatie is het aandeel van de BlueGit-dataset (bytes van bestanden uit het laatste manifest die aanwezig en actueel zijn) dat al in de kopie staat. 100% alleen als alle bestanden kloppen. Die waarde staat in `status.sync` (optioneel, protocol 2, minimum blijft 1 zodat oude peers geen banner krijgen) en gaat ook naar BlueGit (`POST /api/v1/backup/progress`). Beide webinterfaces tonen een balk; onbekend/offline/niet-compatibel worden als tekst getoond, geen misleidende 100%. Op de BlueGit-lijst ververst de pagina periodiek zolang een server nog niet op 100% zit.
50- 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.
51- 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.
52
53### Bediening vanuit BlueGit
54
55- Tim gaf de keuze tussen een iframe of een API-koppeling met een vergelijkbare interface. Ik koos de **API-koppeling**:
56 - Een iframe zou een tweede login vragen.
57 - Het werkt niet als de backup server alleen voor BlueGit bereikbaar is en niet voor de browser.
58 - Het opent de deur voor clickjacking.
59- 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.
60- **Niet** vanuit BlueGit:
61 - **koppelen**: dat vraagt de key op de backup server zelf.
62 - **een archief downloaden**: een archief van gigabytes hoort niet door BlueGit heen te lopen.
63- 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).
64- 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.
65
66### Meerdere backup servers
67
68- 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.
69- Elke backup server krijgt elke melding, parallel. Een server die niet reageert, houdt de andere niet op.
70- Een rollback kan vanaf elke gekoppelde backup server. De andere servers zien de teruggezette stand bij hun volgende sync.
71- 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.
72- `backup.json` bevat nu een lijst met servers. De oude vorm met één koppeling wordt bij het lezen omgezet.
73
74### Key en authenticatie
75
76- BlueGit maakt per backup server een Backupserver-Key (`bgbk_` + 64 hex) onder *Beheer → Backup* en toont hem één keer. BlueGit bewaart alleen `sha256(key)`.
77- Een nieuwe key voor een server maakt zijn oude key ongeldig. Verwijderen ontkoppelt die server.
78- **Backup server → BlueGit:** `Authorization: Bearer bgbk_…` op `/api/v1/backup/*`. Vijf foute pogingen per minuut per IP-adres geven `429`.
79- **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.
80- De koppeling in BlueGit (`<state>/backup.json`) zit **niet** in de backup. Een rollback zet de koppeling dus niet terug naar een oude key.
81- Je koppelt in de webinterface (of via de API). De CLI `bluegit-backup connect --url …` met de key uit `BLUEGIT_BACKUP_KEY` (of `--key`) is een alternatief. De server meldt BlueGit daarna zijn `public_url`, zodat BlueGit weet waar de meldingen heen moeten.
82
83### Wat wordt geback-upt
84
85- Alles wat BlueGit nodig heeft om identiek terug te komen:
86 - de database (`bluegit.db`) als consistente snapshot via `VACUUM INTO`
87 - `secret.key`
88 - de SSH-hostkeys
89 - logo's en avatars
90 - alle repositories
91 - releases en CI-artifacts
92- **Niet:**
93 - `config.yml`. Dat bestand hoort bij de machine (paden, poorten, OAuth-geheimen) en zet je zelf terug.
94 - `storage_path`, caches, lockbestanden, werkmappen (`data/work`), tijdelijke bestanden, symlinks
95 - de backupkoppeling en het instance-id
96- "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.
97
98### Meldingen en synchroniseren
99
100- 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.
101- 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`).
102- 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.
103- Tussen twee syncs na meldingen zit minstens `min_sync_interval` (10s). Meldingen die tijdens een sync binnenkomen, geven precies één vervolgsync.
104- 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.
105- Een bestand dat tijdens het downloaden verandert (grootte klopt niet), wordt bij de volgende sync opnieuw opgehaald.
106
107### Gedoseerd downloaden
108
109- Een token bucket begrenst de downloadsnelheid tot `rate_limit_kib` KiB/s (standaard 1024, dus 1 MiB/s), over alle downloads samen.
110- Er is altijd maar één download tegelijk. BlueGit krijgt dus nooit meer dan één verzoek tegelijk van de backup server.
111- 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.
112
113### Archieven
114
115- Formaat: `tar.gz` (PAX), met de lopende kopie als inhoud (`state/…` en `data/…`). Je kunt een archief dus ook met de hand uitpakken. Naast de bestanden bevat het voor elke bare repository de mappen `refs/`, `refs/heads/`, `refs/tags/`, `objects/`, `objects/info/` en `objects/pack/`, ook als ze leeg zijn. Staan alle refs in `packed-refs` (na `git gc` of `git pack-refs --all`), dan is `refs/` leeg; zonder die map is de map na uitpakken geen git-repository.
116- Naam: `bluegit-YYYYMMDD-HHMMSS.tar.gz` in UTC, met `-2`, `-3`, … als er in dezelfde seconde meer zijn.
117- Het eerste archief komt binnen een minuut na de eerste geslaagde sync, daarna elk `archive_interval` (standaard 24u).
118- Er wordt eerst naar een tijdelijk bestand geschreven en daarna hernoemd. Een half archief komt dus nooit in de lijst.
119- **Opruimen:**
120 - Archieven ouder dan `retention_days` gaan weg.
121 - 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.
122 - Het nieuwste archief blijft altijd staan, ook als het te oud is. Anders zou er geen backup meer zijn.
123 - 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.
124
125### Rollback
126
127- 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>"`.
128- Het verloop:
129 1. De backup server pakt het archief uit in `mirror.rollback`.
130 2. Hij zet dat op de plaats van zijn lopende kopie.
131 3. Hij stuurt alles als `tar.gz` naar BlueGit (`POST /api/v1/backup/restore`).
132 4. BlueGit zet de data klaar, weigert ondertussen alle wijzigingen (503) en herstart zichzelf (zelfde PID, `exec`).
133 5. Bij het opstarten wisselt BlueGit de bestanden om, nog voordat de database opengaat.
134- Lukt het versturen niet, dan zet de backup server zijn oude kopie terug. Er gaat dan niets verloren.
135- 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.
136- Het upload-verkeer naar BlueGit bij een rollback is **niet** gedoseerd. BlueGit staat dan toch al stil, en een snelle terugzet is belangrijker.
137
138### Nieuwe instantie
139
140- 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.
141- Koppel je een andere instantie, dan weigert de server (`409`) en moet je kiezen:
142 - **wissen**: de oude kopie en alle archieven gaan weg, en de nieuwe instantie wordt opnieuw opgehaald.
143 - **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.
144- `connect` vraagt de keuze in de terminal. Zonder keuze (lege invoer) gebeurt er niets. Zonder terminal gebruik je `--on-conflict wipe|restore`.
145- De nieuwe BlueGit moet al draaien met een eigen `config.yml` en data-schijf. Het herstel vult alleen de inhoud.
146
147### Compatibiliteit (t1209u)
148
149- 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.
150- 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`.
151- 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.
152- 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.
153- **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.
154- 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.
155- **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).
156- **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.
157- 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`).
158- **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`.
159- **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.
160
161### Releases en tests
162
163Tot 16-11-2026, toen dit nog een aparte repository was. Wat er sindsdien geldt, staat bovenaan.
164
165- "Dezelfde release-opties als BlueGit" betekent:
166 - een AUR-pakket `bluegit-backup` dat vanaf master wordt bijgewerkt
167 - binaries bij een tag
168- 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.
169- 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.
170- Releases vanaf master staan aan zodra `.release-enabled` in de repository staat. Zonder dat bestand doen de release-scripts niets.
171- De integratietests bouwen BlueGit van de ref in `.bluegit-ref` (`master`; tijdens de compatibiliteitswijziging tijdelijk `feature/backup-compat`, tot die in BlueGit gemerged is).
172- 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.
173- Het AUR-pakket `bluegit-backup` haalt de broncode uit het archief van `timfa/bluegit` (dezelfde repository), net als `bluegit` en `bluegit-runner`.