# bluegit-backup Een losse backup server voor één [BlueGit](https://git.timfalken.com/timfa/bluegit)-instantie. - Koppelt met een **Backupserver-Key** die een BlueGit-beheerder in BlueGit maakt (*Beheer → Backup*). - Haalt alle data en configuratie van BlueGit binnen: database, sleutels, SSH-hostkeys, logo's, avatars, repositories, releases en artifacts. Dat gaat **gedoseerd** (`rate_limit_kib`), zodat BlueGit er geen last van heeft. - BlueGit **meldt elke wijziging**. De backup server haalt dan alleen op wat veranderd is. Daarnaast loopt hij elk `full_sync_interval` alles na. - Elk `archive_interval` (standaard dagelijks) gaat de hele kopie gecomprimeerd in een archief (`tar.gz`). - Archieven ouder dan `retention_days` gaan weg. Is de schijf vol (minder dan `min_free_mb` vrij), dan gaat het oudste archief weg. Het nieuwste archief blijft altijd staan. - In BlueGit ziet de beheerder de archieven en kan hij een **rollback** starten, met een grote waarschuwing dat die niet terug te draaien is. De backup server pakt het archief uit, vervangt zijn kopie en stuurt alles naar BlueGit. BlueGit zet de data terug en herstart. - Eén backup server hoort bij één BlueGit. Koppel je een andere instantie, dan kies je: **oude backups wissen** of **de nieuwe instantie herstellen** met de backupdata. Eén BlueGit kan wel meerdere backup servers hebben, elk met een eigen key. - Een **webinterface** (standaard op poort 8080) waarin alles in te stellen en te bedienen is, en een **API** die precies hetzelfde kan. Beide lopen via één lijst met acties (`GET /api/v1/admin/actions`). - Vanuit **BlueGit** (*Beheer → Backup → server*) is de backup server ook te bedienen: status, instellingen, sync, archiveren, opruimen, archieven verwijderen en rollback. BlueGit vraagt de acties op bij de backup server en stuurt ze ondertekend door. Het protocol staat in [docs/PROTOCOL.md](docs/PROTOCOL.md). De aannames staan in [docs/ASSUMPTIONS.md](docs/ASSUMPTIONS.md). ## Installeren ### Arch Linux (AUR) ```sh yay -S bluegit-backup ``` Het pakket zet de binary in `/usr/bin/bluegit-backup`, de config in `/etc/bluegit-backup/config.yml`, de data in `/var/lib/bluegit-backup` en een systemd-unit `bluegit-backup.service` (gebruiker `bluegit-backup`). ### Binary Bij een release staan `bluegit-backup-linux-amd64`, `bluegit-backup-linux-arm64` en `SHA256SUMS`. Zelf bouwen: ```sh go build -o bluegit-backup ./cmd/bluegit-backup ./bluegit-backup example-config > config.yml ./bluegit-backup serve --config config.yml ``` ## Koppelen 1. Zet in `config.yml` `public_url` op het adres waarop BlueGit deze server bereikt. 2. Start de server: `systemctl enable --now bluegit-backup`. 3. Voeg in BlueGit onder *Beheer → Backup* een backup server toe. De Backupserver-Key wordt één keer getoond. 4. Koppel in de webinterface (`http://:8080`, sectie *Koppeling*), of met de CLI: ```sh BLUEGIT_BACKUP_KEY=bgbk_… bluegit-backup connect --url https://git.example.com ``` Had deze server al backups van een andere BlueGit, dan vraagt `connect`: ``` 1) oude backups wissen en opnieuw beginnen 2) de nieuwe BlueGit herstellen met de laatste backupdata ``` Zonder terminal kies je met `--on-conflict wipe` of `--on-conflict restore`. Daarna haalt de server meteen een volledige kopie op en maakt hij een eerste archief. ## Webinterface Open `http://:8080` en log in met het beheertoken uit `data_dir/admin.token`: ```sh sudo -u bluegit-backup bluegit-backup token ``` Daar staan: - **Overzicht**: koppeling, laatste sync, kopie, archieven en de laatste rollback, met *Nu synchroniseren*, *Nu archiveren* en *Nu opruimen*. - **Koppeling**: koppelen (met de keuze wissen of herstellen bij een andere BlueGit) en ontkoppelen. - **Instellingen**: elk veld uit de tabel hieronder. Ze gaan naar `data_dir/settings.yml`, dat boven `config.yml` gaat. `listen` geldt pas na een herstart, de rest meteen. - **Archieven**: downloaden, verwijderen en een rollback (met waarschuwing, vinkje en de archiefnaam overtypen). - **API**: de lijst met alle acties. Passen BlueGit en deze backup server niet bij elkaar (een van de twee is verouderd), dan staat er bovenaan een waarschuwing die zegt wie er geüpdatet moet worden. De server synchroniseert en zet dan niets terug tot dat gebeurd is. Zie [Compatibiliteit](#compatibiliteit). De sessie is een HttpOnly-cookie (SameSite=Strict, 12 uur), elk formulier heeft een CSRF-token, en vijf foute logins per minuut per IP-adres geven `429`. De interface mag niet in een frame van een andere site. Gebruik een TLS-proxy als de server buiten je eigen netwerk bereikbaar is. ## API Elke actie uit de webinterface is ook een API-aanroep, met `Authorization: Bearer `: | Methode | Pad | Actie | BlueGit | |---|---|---|---| | GET | `/api/v1/admin/status` | Status | ✓ | | GET | `/api/v1/admin/actions` | Alle acties | ✓ | | GET | `/api/v1/admin/config` | Instellingen met uitleg | ✓ | | PUT | `/api/v1/admin/config` | Instellingen wijzigen, bv. `{"retention_days": 14}` | ✓ | | POST | `/api/v1/admin/connect` | `{"url", "key", "on_conflict": ""\|"wipe"\|"restore"}` | | | POST | `/api/v1/admin/disconnect` | Ontkoppelen (kopie en archieven blijven) | ✓ | | POST | `/api/v1/admin/sync` | Nu synchroniseren (`{"wait": false}`: op de achtergrond) | ✓ | | POST | `/api/v1/admin/archive` | Nu archiveren | ✓ | | POST | `/api/v1/admin/prune` | Bewaarregels nu toepassen | ✓ | | GET | `/api/v1/admin/archives` | Archieven | ✓ | | GET | `/api/v1/admin/archives/{name}/download` | Archief downloaden | | | DELETE | `/api/v1/admin/archives/{name}` | Archief verwijderen | ✓ | | POST | `/api/v1/admin/rollback` | `{"archive", "confirm": archiefnaam}`; niet terug te draaien | ✓ | ✓ betekent dat de gekoppelde BlueGit dit ook mag, met een ondertekend verzoek. Een sessie van de webinterface mag de API ook gebruiken, met het CSRF-token in `X-CSRF-Token`. ## Compatibiliteit BlueGit en de backup server melden elkaar hun protocolversie en de oudste versie van de andere kant die ze nog ondersteunen (koppen `X-Backup-Protocol`/`X-Backup-Min-Protocol` en `X-BlueGit-Protocol`/`X-BlueGit-Min-Protocol`, plus `info`). Deze versie spreekt protocol 1 en ondersteunt BlueGit vanaf protocol 1. Een BlueGit die geen protocol meldt, spreekt protocol 1. Past het niet: - weigert de backup server te synchroniseren en terug te zetten (`409`), en geven `GET /api/v1/admin/status` en de webinterface `compat` (`bluegit_too_old` of `backup_too_old`) en een uitleg; - zien beheerders in BlueGit bovenaan elke pagina een banner met de naam van de backup server en wie er geüpdatet moet worden, met een link naar Beheer → Backup; - weigert BlueGit de gegevens (`426`). Updaten doe je zelf (zie [Releases](#releases)); bij het volgende contact is alles weer normaal. Het protocol staat in [docs/PROTOCOL.md](docs/PROTOCOL.md). ## CLI ```sh bluegit-backup status | list | config | actions bluegit-backup sync | archive | prune | disconnect bluegit-backup set retention_days=14 archive_interval=12h bluegit-backup delete bluegit-20261115-030000.tar.gz bluegit-backup rollback bluegit-20261115-030000.tar.gz # vraagt om de naam over te typen bluegit-backup token # beheertoken voor de webinterface ``` Deze commando's praten met de draaiende server via `data_dir/admin.token`. Draai ze dus als een gebruiker die dat bestand kan lezen (`sudo -u bluegit-backup …`). ## Configuratie | Sleutel | Standaard | Betekenis | |---|---|---| | `listen` | `0.0.0.0:8080` | Adres van de webinterface en API (na herstart) | | `public_url` | (leeg) | Adres waarop BlueGit deze server bereikt | | `data_dir` | `/var/lib/bluegit-backup` | Kopie, archieven en koppeling (alleen in `config.yml`) | | `archive_interval` | `24h` | Hoe vaak een archief | | `retention_days` | `30` | Archieven ouder dan dit weg (0 = nooit) | | `min_free_mb` | `1024` | Minder vrij: oudste archief weg | | `rate_limit_kib` | `1024` | Downloadsnelheid in KiB/s (0 = onbeperkt) | | `full_sync_interval` | `1h` | Ook zonder melding alles nalopen | | `min_sync_interval` | `10s` | Minimale tijd tussen syncs na meldingen | In `data_dir`: - `mirror/` is de lopende kopie. - `archives/` bevat `bluegit-YYYYMMDD-HHMMSS.tar.gz` (UTC). - `state.json` (0600) is de koppeling met de key. - `admin.token` (0600) is voor de webinterface, de API en de CLI. - `settings.yml` (0600) bevat wat via de webinterface, API of BlueGit is ingesteld. ## Releases Een AUR-pakket (`bluegit-backup`, bijgewerkt vanaf master) en binaries bij een tag. Zie `blue-ci-cd.yml`. - Elke release-job hangt af van de job `integration`. Die bouwt een echte BlueGit (`scripts/build-bluegit.sh`, ref in `.bluegit-ref`), start hem, configureert hem en test daarmee elke feature. Faalt er één test, dan is er geen release. - Releases vanaf master staan pas aan zodra het bestand `.release-enabled` in de repository staat. De geheimen staan in de kop van `blue-ci-cd.yml`. - Een release bij een tag (`v*`) publiceert de binaries bij een bestaande tag. - Eerste release: [v0.1.0](https://git.timfalken.com/timfa/bluegit-backup/-/releases) (linux amd64/arm64 en `SHA256SUMS`). Updaten doe je zelf: met je AUR-helper (bijvoorbeeld `yay -Syu bluegit-backup`) of met een nieuwe binary van de releasepagina. Er is geen self-update. ## Tests ```sh go test ./... # unit-tests ./scripts/build-bluegit.sh # bouwt .bluegit-bin/bluegit BLUEGIT_BIN=$PWD/.bluegit-bin/bluegit go test -tags integration -v ./integration/ ``` Daarnaast controleren unit-tests dat elke wijzigende actie een formulier in de webinterface heeft, en elk formulier een API-actie. De integratietests starten per test een echte BlueGit in een tijdelijke map (dev-login, geen SSH, geen CI-runner). Ze maken een beheerderstoken en daarmee repositories, issues en een Backupserver-Key. Daarna testen ze tegen die BlueGit: | Test | Feature | |---|---| | `TestKeyGenerationAndConnect` | Key maken in BlueGit, koppelen, verkeerde key geweigerd | | `TestFullSyncCopiesAllData` | Alle data en configuratie komt binnen, en de kopie klopt | | `TestNotificationTriggersSync` | Een wijziging in BlueGit geeft een melding en daarna een sync | | `TestDownloadIsThrottled` | Downloaden blijft onder `rate_limit_kib` | | `TestArchiveIntervalAndListInBlueGit` | Archief per interval, lijst zichtbaar in BlueGit | | `TestRetentionAndDiskFull` | Weggooien op leeftijd en bij volle schijf | | `TestRollbackFromBlueGit` | Rollback vanuit BlueGit (met bevestiging), BlueGit staat daarna terug | | `TestNewInstanceWipe` | Nieuwe instantie, keuze wissen | | `TestNewInstanceRestore` | Nieuwe instantie, keuze herstellen | | `TestCLIConnectAsksOnConflict` | `connect` vraagt de keuze | | `TestWebUIConfiguresAndOperatesEverything` | Webinterface: inloggen, alle instellingen, koppelen, sync, archief, download, opruimen, rollback, verwijderen, ontkoppelen | | `TestAPIDoesEverythingTheUICan` | Elke actie via de API; de test faalt als er een actie bij komt zonder test | | `TestBlueGitControlsBackupServer` | Instellingen, archief, sync en verwijderen vanuit BlueGit (API en webinterface) | | `TestMultipleBackupServers` | Twee backup servers aan één BlueGit; meldingen naar beide; verwijderen ontkoppelt alleen die ene | | `TestCompatBlueGitTooOld` | Backup server vraagt een nieuwer protocol: hij weigert sync en rollback, waarschuwt in UI en API; BlueGit toont beheerders de banner op elke pagina; na de update is alles weer normaal | | `TestCompatBackupTooOld` | Test-build van BlueGit met protocol 99 (`-ldflags -X`): koppelen lukt, BlueGit geeft `426`, de backup server weigert, beheerders zien de banner en een gewone gebruiker niet | De pipeline bouwt BlueGit van de ref in `.bluegit-ref`, plus een test-build met protocol 99 (`.bluegit-bin/bluegit-future`) voor `TestCompatBackupTooOld`. ## Licentie Zie [LICENSE](LICENSE).