bluegit-backup
Een losse backup server voor één 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_intervalalles na. - Elk
archive_interval(standaard dagelijks) gaat de hele kopie gecomprimeerd in een archief (tar.gz). - Archieven ouder dan
retention_daysgaan weg. Is de schijf vol (minder danmin_free_mbvrij), 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.
Het protocol staat in docs/PROTOCOL.md. De aannames staan in docs/ASSUMPTIONS.md.
Installeren
Arch Linux (AUR)
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:
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. Maak in BlueGit onder Beheer → Backup een Backupserver-Key. Die wordt één keer getoond. 4. Koppel:
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.
Bedienen
bluegit-backup status # koppeling, laatste sync, laatste archief
bluegit-backup list # archieven
bluegit-backup sync # nu synchroniseren
bluegit-backup archive # nu een archief maken
bluegit-backup prune # bewaarregels nu toepassen
Deze commando's praten met de draaiende server via data_dir/admin.token en moeten dus draaien als een gebruiker die dat bestand kan lezen (sudo -u bluegit-backup …).
Een rollback start je in BlueGit, niet hier.
Configuratie
| Sleutel | Standaard | Betekenis |
|---|---|---|
listen | 0.0.0.0:8790 | Adres van de HTTP-server |
public_url | (leeg) | Adres waarop BlueGit deze server bereikt |
data_dir | /var/lib/bluegit-backup | Kopie, archieven en koppeling |
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/bevatbluegit-YYYYMMDD-HHMMSS.tar.gz(UTC).state.json(0600) is de koppeling met de key.admin.token(0600) is voor de CLI.
Releases
Dezelfde opties als BlueGit: een AUR-pakket (bluegit-backup), een self-update van een geïnstalleerde server vanuit de pipeline 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-enabledin de repository staat. De geheimen staan in de kop vanblue-ci-cd.yml. - Een release bij een tag (
v*) publiceert de binaries bij een bestaande tag.
Self-update: zet BLUEGIT_BACKUP_UPDATE_TOKEN in /etc/bluegit-backup/env op de server. Zet in de pipeline hetzelfde token plus BLUEGIT_BACKUP_UPDATE_URL. De server bouwt dan bluegit-backup op het commit van master via bluegit-backup-update.service.
Tests
go test ./... # unit-tests
./scripts/build-bluegit.sh # bouwt .bluegit-bin/bluegit
BLUEGIT_BIN=$PWD/.bluegit-bin/bluegit go test -tags integration -v ./integration/
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 |
De BlueGit-kant (key, meldingen, beheerpagina, rollback) zit in BlueGit op feature/backup-server. Zolang die niet gemerged is, bouwt de pipeline BlueGit van die branch (.bluegit-ref). Zet .bluegit-ref op master zodra hij gemerged is.
Licentie
Zie LICENSE.
Source
| 1 | # bluegit-backup |
| 2 | |
| 3 | Een losse backup server voor één [BlueGit](https://git.timfalken.com/timfa/bluegit)-instantie. |
| 4 | |
| 5 | - Koppelt met een **Backupserver-Key** die een BlueGit-beheerder in BlueGit maakt (*Beheer → Backup*). |
| 6 | - 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. |
| 7 | - BlueGit **meldt elke wijziging**. De backup server haalt dan alleen op wat veranderd is. Daarnaast loopt hij elk `full_sync_interval` alles na. |
| 8 | - Elk `archive_interval` (standaard dagelijks) gaat de hele kopie gecomprimeerd in een archief (`tar.gz`). |
| 9 | - 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. |
| 10 | - 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. |
| 11 | - 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. |
| 12 | |
| 13 | Het protocol staat in [docs/PROTOCOL.md](docs/PROTOCOL.md). De aannames staan in [docs/ASSUMPTIONS.md](docs/ASSUMPTIONS.md). |
| 14 | |
| 15 | ## Installeren |
| 16 | |
| 17 | ### Arch Linux (AUR) |
| 18 | |
| 19 | ```sh |
| 20 | yay -S bluegit-backup |
| 21 | ``` |
| 22 | |
| 23 | 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`). |
| 24 | |
| 25 | ### Binary |
| 26 | |
| 27 | Bij een release staan `bluegit-backup-linux-amd64`, `bluegit-backup-linux-arm64` en `SHA256SUMS`. Zelf bouwen: |
| 28 | |
| 29 | ```sh |
| 30 | go build -o bluegit-backup ./cmd/bluegit-backup |
| 31 | ./bluegit-backup example-config > config.yml |
| 32 | ./bluegit-backup serve --config config.yml |
| 33 | ``` |
| 34 | |
| 35 | ## Koppelen |
| 36 | |
| 37 | 1. Zet in `config.yml` `public_url` op het adres waarop BlueGit deze server bereikt. |
| 38 | 2. Start de server: `systemctl enable --now bluegit-backup`. |
| 39 | 3. Maak in BlueGit onder *Beheer → Backup* een Backupserver-Key. Die wordt één keer getoond. |
| 40 | 4. Koppel: |
| 41 | |
| 42 | ```sh |
| 43 | BLUEGIT_BACKUP_KEY=bgbk_… bluegit-backup connect --url https://git.example.com |
| 44 | ``` |
| 45 | |
| 46 | Had deze server al backups van een andere BlueGit, dan vraagt `connect`: |
| 47 | |
| 48 | ``` |
| 49 | 1) oude backups wissen en opnieuw beginnen |
| 50 | 2) de nieuwe BlueGit herstellen met de laatste backupdata |
| 51 | ``` |
| 52 | |
| 53 | Zonder terminal kies je met `--on-conflict wipe` of `--on-conflict restore`. |
| 54 | |
| 55 | Daarna haalt de server meteen een volledige kopie op en maakt hij een eerste archief. |
| 56 | |
| 57 | ## Bedienen |
| 58 | |
| 59 | ```sh |
| 60 | bluegit-backup status # koppeling, laatste sync, laatste archief |
| 61 | bluegit-backup list # archieven |
| 62 | bluegit-backup sync # nu synchroniseren |
| 63 | bluegit-backup archive # nu een archief maken |
| 64 | bluegit-backup prune # bewaarregels nu toepassen |
| 65 | ``` |
| 66 | |
| 67 | Deze commando's praten met de draaiende server via `data_dir/admin.token` en moeten dus draaien als een gebruiker die dat bestand kan lezen (`sudo -u bluegit-backup …`). |
| 68 | |
| 69 | Een rollback start je in BlueGit, niet hier. |
| 70 | |
| 71 | ## Configuratie |
| 72 | |
| 73 | | Sleutel | Standaard | Betekenis | |
| 74 | |---|---|---| |
| 75 | | `listen` | `0.0.0.0:8790` | Adres van de HTTP-server | |
| 76 | | `public_url` | (leeg) | Adres waarop BlueGit deze server bereikt | |
| 77 | | `data_dir` | `/var/lib/bluegit-backup` | Kopie, archieven en koppeling | |
| 78 | | `archive_interval` | `24h` | Hoe vaak een archief | |
| 79 | | `retention_days` | `30` | Archieven ouder dan dit weg (0 = nooit) | |
| 80 | | `min_free_mb` | `1024` | Minder vrij: oudste archief weg | |
| 81 | | `rate_limit_kib` | `1024` | Downloadsnelheid in KiB/s (0 = onbeperkt) | |
| 82 | | `full_sync_interval` | `1h` | Ook zonder melding alles nalopen | |
| 83 | | `min_sync_interval` | `10s` | Minimale tijd tussen syncs na meldingen | |
| 84 | |
| 85 | In `data_dir`: |
| 86 | |
| 87 | - `mirror/` is de lopende kopie. |
| 88 | - `archives/` bevat `bluegit-YYYYMMDD-HHMMSS.tar.gz` (UTC). |
| 89 | - `state.json` (0600) is de koppeling met de key. |
| 90 | - `admin.token` (0600) is voor de CLI. |
| 91 | |
| 92 | ## Releases |
| 93 | |
| 94 | Dezelfde opties als BlueGit: een AUR-pakket (`bluegit-backup`), een self-update van een geïnstalleerde server vanuit de pipeline en binaries bij een tag. Zie `blue-ci-cd.yml`. |
| 95 | |
| 96 | - 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. |
| 97 | - 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`. |
| 98 | - Een release bij een tag (`v*`) publiceert de binaries bij een bestaande tag. |
| 99 | |
| 100 | Self-update: zet `BLUEGIT_BACKUP_UPDATE_TOKEN` in `/etc/bluegit-backup/env` op de server. Zet in de pipeline hetzelfde token plus `BLUEGIT_BACKUP_UPDATE_URL`. De server bouwt dan `bluegit-backup` op het commit van master via `bluegit-backup-update.service`. |
| 101 | |
| 102 | ## Tests |
| 103 | |
| 104 | ```sh |
| 105 | go test ./... # unit-tests |
| 106 | ./scripts/build-bluegit.sh # bouwt .bluegit-bin/bluegit |
| 107 | BLUEGIT_BIN=$PWD/.bluegit-bin/bluegit go test -tags integration -v ./integration/ |
| 108 | ``` |
| 109 | |
| 110 | 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: |
| 111 | |
| 112 | | Test | Feature | |
| 113 | |---|---| |
| 114 | | `TestKeyGenerationAndConnect` | Key maken in BlueGit, koppelen, verkeerde key geweigerd | |
| 115 | | `TestFullSyncCopiesAllData` | Alle data en configuratie komt binnen, en de kopie klopt | |
| 116 | | `TestNotificationTriggersSync` | Een wijziging in BlueGit geeft een melding en daarna een sync | |
| 117 | | `TestDownloadIsThrottled` | Downloaden blijft onder `rate_limit_kib` | |
| 118 | | `TestArchiveIntervalAndListInBlueGit` | Archief per interval, lijst zichtbaar in BlueGit | |
| 119 | | `TestRetentionAndDiskFull` | Weggooien op leeftijd en bij volle schijf | |
| 120 | | `TestRollbackFromBlueGit` | Rollback vanuit BlueGit (met bevestiging), BlueGit staat daarna terug | |
| 121 | | `TestNewInstanceWipe` | Nieuwe instantie, keuze wissen | |
| 122 | | `TestNewInstanceRestore` | Nieuwe instantie, keuze herstellen | |
| 123 | | `TestCLIConnectAsksOnConflict` | `connect` vraagt de keuze | |
| 124 | |
| 125 | De BlueGit-kant (key, meldingen, beheerpagina, rollback) zit in BlueGit op `feature/backup-server`. Zolang die niet gemerged is, bouwt de pipeline BlueGit van die branch (`.bluegit-ref`). Zet `.bluegit-ref` op `master` zodra hij gemerged is. |
| 126 | |
| 127 | ## Licentie |
| 128 | |
| 129 | Zie [LICENSE](LICENSE). |