Backup server (bluegit-backup)
Een losse backup server (timfa/bluegit-backup) houdt een kopie bij van alle gegevens en configuratie van één BlueGit. Hij haalt ze langzaam op, krijgt na elke wijziging een melding, maakt periodiek een gecomprimeerd archief, en kan BlueGit naar zo'n archief terugzetten.
In BlueGit
Beheer > Backup (/admin/backup, alleen installatiebeheerders):
- Backupserver-Key maken (één keer getoond), vervangen of intrekken. Er is altijd hoogstens één key; een nieuwe key maakt de oude ongeldig en vergeet de gekoppelde server.
- Gekoppelde backup server: adres, laatste contact, archiefinterval en bewaartermijn.
- Backup-archieven als lijst, met per archief een rollback. Die staat achter een grote rode waarschuwing, een vinkje ("ik begrijp dat dit niet terug te draaien is"), het intypen van de archiefnaam en een bevestigingsdialoog.
Dezelfde acties via de API (token van een beheerder, scope api/admin):
GET /api/v1/admin/backup | status, gekoppelde server, archieven |
POST /api/v1/admin/backup/key | nieuwe key, {"key": "bgbk_…"} (eenmalig) |
DELETE /api/v1/admin/backup/key | key intrekken |
POST /api/v1/admin/backup/rollback | {"archive": "naam", "confirm": "naam"} |
Protocol
De backup server praat met BlueGit met de key als bearer-token (Authorization: Bearer bgbk_…):
GET /api/v1/backup/info | instance_id, base_url, gekoppelde server |
POST /api/v1/backup/connect | {"server_url", "server_id"}: waar BlueGit meldingen heen stuurt |
GET /api/v1/backup/manifest | alle bestanden: pad, grootte, mtime, mode; de database ook met sha256 |
GET /api/v1/backup/file?path=… | één bestand |
POST /api/v1/backup/restore | tar.gz met logische paden; BlueGit pakt uit en herstart (202) |
Vijf mislukte key-pogingen per minuut per IP geven daarna 429.
BlueGit praat met de backup server met een HMAC-handtekening. Het geheim is sha256("bluegit-backup-sign:" + key) als hex; beide kanten leiden het af uit de key. Koppen:
X-BlueGit-Instance: <instance_id>
X-BlueGit-Timestamp: <unix-seconden> (hoogstens 5 minuten verschil)
X-BlueGit-Signature: hex(HMAC-SHA256(geheim, METHOD "\n" PAD "\n" TS "\n" sha256hex(body)))
POST /api/v1/notify | er is iets veranderd |
GET /api/v1/archives | {"archives": [{name, created_at, size}]} |
GET /api/v1/status | interval, bewaartermijn, stand van de laatste rollback |
POST /api/v1/rollback | {"archive": "naam"} |
Meldingen. Na elk schrijvend HTTP-verzoek (behalve de backup-API zelf en git-upload-pack), na elke push (ook SSH) en bij elke CI-gebeurtenis meldt BlueGit een wijziging. Meldingen worden 2 seconden gebundeld en bij een fout tot vier keer opnieuw geprobeerd. De backup server haalt daarnaast periodiek alles op, dus een gemiste melding kost alleen vertraging. Het adres van de backup server mag een privéadres zijn (de beheerder koppelt hem met een eigen key); de SSRF-regels van webhooks gelden hier niet.
Wat er in een backup zit
state/bluegit.db consistente kopie (VACUUM INTO), niet het live bestand
state/secret.key nodig voor de versleutelde geheimen in de database
state/ssh/… SSH-hostkey
state/logos/…, state/avatars/…
data/repos/… bare repositories
data/releases/… release-assets (zonder .incoming)
data/artifacts/… CI-artifacts
Niet mee: config.yml, storage_path, cache.json, backup.json en instance_id (horen bij deze installatie), data/work, *.lock en symlinks. De koppeling staat in <state>/backup.json (0600, alleen de hash van de key) en niet in de database, zodat een rollback naar een oud archief de koppeling niet terugdraait.
Terugzetten
POST /api/v1/backup/restore pakt het archief uit in <state>/.restore en <datadisk>/.restore; de live gegevens blijven tot dan onaangeroerd. Een ongeldig archief (pad buiten de lijst hierboven, .., symlink, geen database of secret.key) wordt geweigerd en opgeruimd. Daarna weigert BlueGit schrijvende verzoeken (503), sluit af zoals bij een gewone stop en start zichzelf opnieuw met exec (zelfde PID, dus systemd ziet geen crash). Bij de start, vóór de database opengaat, worden de mappen omgewisseld: alles uit de lijst hierboven wordt vervangen, ook wat niet in het archief zat. Een BlueGit zonder datadisk kan geen archief met repositories aannemen; kies eerst de datadisk in /setup.
Source
| 1 | # Backup server (bluegit-backup) |
| 2 | |
| 3 | Een losse backup server ([timfa/bluegit-backup](https://git.timfalken.com/timfa/bluegit-backup)) houdt een kopie bij van alle gegevens en configuratie van één BlueGit. Hij haalt ze langzaam op, krijgt na elke wijziging een melding, maakt periodiek een gecomprimeerd archief, en kan BlueGit naar zo'n archief terugzetten. |
| 4 | |
| 5 | ## In BlueGit |
| 6 | |
| 7 | **Beheer > Backup** (`/admin/backup`, alleen installatiebeheerders): |
| 8 | |
| 9 | - **Backupserver-Key** maken (één keer getoond), vervangen of intrekken. Er is altijd hoogstens één key; een nieuwe key maakt de oude ongeldig en vergeet de gekoppelde server. |
| 10 | - **Gekoppelde backup server**: adres, laatste contact, archiefinterval en bewaartermijn. |
| 11 | - **Backup-archieven** als lijst, met per archief een rollback. Die staat achter een grote rode waarschuwing, een vinkje ("ik begrijp dat dit niet terug te draaien is"), het intypen van de archiefnaam en een bevestigingsdialoog. |
| 12 | |
| 13 | Dezelfde acties via de API (token van een beheerder, scope `api`/`admin`): |
| 14 | |
| 15 | | | | |
| 16 | |---|---| |
| 17 | | `GET /api/v1/admin/backup` | status, gekoppelde server, archieven | |
| 18 | | `POST /api/v1/admin/backup/key` | nieuwe key, `{"key": "bgbk_…"}` (eenmalig) | |
| 19 | | `DELETE /api/v1/admin/backup/key` | key intrekken | |
| 20 | | `POST /api/v1/admin/backup/rollback` | `{"archive": "naam", "confirm": "naam"}` | |
| 21 | |
| 22 | ## Protocol |
| 23 | |
| 24 | **De backup server praat met BlueGit** met de key als bearer-token (`Authorization: Bearer bgbk_…`): |
| 25 | |
| 26 | | | | |
| 27 | |---|---| |
| 28 | | `GET /api/v1/backup/info` | `instance_id`, `base_url`, gekoppelde server | |
| 29 | | `POST /api/v1/backup/connect` | `{"server_url", "server_id"}`: waar BlueGit meldingen heen stuurt | |
| 30 | | `GET /api/v1/backup/manifest` | alle bestanden: pad, grootte, mtime, mode; de database ook met sha256 | |
| 31 | | `GET /api/v1/backup/file?path=…` | één bestand | |
| 32 | | `POST /api/v1/backup/restore` | tar.gz met logische paden; BlueGit pakt uit en herstart (202) | |
| 33 | |
| 34 | Vijf mislukte key-pogingen per minuut per IP geven daarna `429`. |
| 35 | |
| 36 | **BlueGit praat met de backup server** met een HMAC-handtekening. Het geheim is `sha256("bluegit-backup-sign:" + key)` als hex; beide kanten leiden het af uit de key. Koppen: |
| 37 | |
| 38 | ```text |
| 39 | X-BlueGit-Instance: <instance_id> |
| 40 | X-BlueGit-Timestamp: <unix-seconden> (hoogstens 5 minuten verschil) |
| 41 | X-BlueGit-Signature: hex(HMAC-SHA256(geheim, METHOD "\n" PAD "\n" TS "\n" sha256hex(body))) |
| 42 | ``` |
| 43 | |
| 44 | | | | |
| 45 | |---|---| |
| 46 | | `POST /api/v1/notify` | er is iets veranderd | |
| 47 | | `GET /api/v1/archives` | `{"archives": [{name, created_at, size}]}` | |
| 48 | | `GET /api/v1/status` | interval, bewaartermijn, stand van de laatste rollback | |
| 49 | | `POST /api/v1/rollback` | `{"archive": "naam"}` | |
| 50 | |
| 51 | **Meldingen.** Na elk schrijvend HTTP-verzoek (behalve de backup-API zelf en `git-upload-pack`), na elke push (ook SSH) en bij elke CI-gebeurtenis meldt BlueGit een wijziging. Meldingen worden 2 seconden gebundeld en bij een fout tot vier keer opnieuw geprobeerd. De backup server haalt daarnaast periodiek alles op, dus een gemiste melding kost alleen vertraging. Het adres van de backup server mag een privéadres zijn (de beheerder koppelt hem met een eigen key); de SSRF-regels van webhooks gelden hier niet. |
| 52 | |
| 53 | ## Wat er in een backup zit |
| 54 | |
| 55 | ```text |
| 56 | state/bluegit.db consistente kopie (VACUUM INTO), niet het live bestand |
| 57 | state/secret.key nodig voor de versleutelde geheimen in de database |
| 58 | state/ssh/… SSH-hostkey |
| 59 | state/logos/…, state/avatars/… |
| 60 | data/repos/… bare repositories |
| 61 | data/releases/… release-assets (zonder .incoming) |
| 62 | data/artifacts/… CI-artifacts |
| 63 | ``` |
| 64 | |
| 65 | Niet mee: `config.yml`, `storage_path`, `cache.json`, `backup.json` en `instance_id` (horen bij deze installatie), `data/work`, `*.lock` en symlinks. De koppeling staat in `<state>/backup.json` (0600, alleen de hash van de key) en niet in de database, zodat een rollback naar een oud archief de koppeling niet terugdraait. |
| 66 | |
| 67 | ## Terugzetten |
| 68 | |
| 69 | `POST /api/v1/backup/restore` pakt het archief uit in `<state>/.restore` en `<datadisk>/.restore`; de live gegevens blijven tot dan onaangeroerd. Een ongeldig archief (pad buiten de lijst hierboven, `..`, symlink, geen database of `secret.key`) wordt geweigerd en opgeruimd. Daarna weigert BlueGit schrijvende verzoeken (503), sluit af zoals bij een gewone stop en start zichzelf opnieuw met `exec` (zelfde PID, dus systemd ziet geen crash). Bij de start, vóór de database opengaat, worden de mappen omgewisseld: alles uit de lijst hierboven wordt vervangen, ook wat niet in het archief zat. Een BlueGit zonder datadisk kan geen archief met repositories aannemen; kies eerst de datadisk in `/setup`. |