BlueGit

timfa bluegit

Files

bluegit / docs / BACKUP.md

BACKUP.md

BACKUP.md 6.5 KiB Download Raw

Backup servers (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.

Eén BlueGit kan meerdere backup servers hebben (hoogstens 16), elk met een eigen Backupserver-Key. Een backup server hoort bij één BlueGit.

In BlueGit

Beheer > Backup (/admin/backup, alleen installatiebeheerders) toont de lijst met backup servers: naam, gekoppeld of wachtend op de key, adres en laatste contact. Backup server toevoegen maakt een nieuwe server met een eigen key, die één keer wordt getoond.

Per backup server (/admin/backup/s/<id>) staat dezelfde bediening als in de webinterface van de backup server zelf:

  • Status: laatste sync en het resultaat ervan, aantal syncs en meldingen, grootte van de kopie, archieven, de laatste rollback en de versie. Met de knoppen Nu synchroniseren, Nu archiveren en Nu opruimen.
  • Instellingen van de backup server: archiefinterval, bewaartermijn, minimale vrije ruimte, downloadsnelheid, syncintervallen, publiek adres en luisteradres. BlueGit krijgt de velden van de backup server en toont ze zoals ze daar staan.
  • Backup-archieven met Verwijderen en Rollback. Een rollback 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.
  • Backupserver-Key vervangen (de oude key werkt meteen niet meer; de server moet opnieuw koppelen), de server hernoemen, of key intrekken en de server verwijderen. Bij verwijderen vraagt BlueGit de backup server eerst om te ontkoppelen. De archieven blijven op de backup server staan.

BlueGit kent de acties niet vooraf. Het vraagt ze op bij de backup server (GET /api/v1/admin/actions) en stuurt ze ondertekend door. Alles wat de backup server voor BlueGit openzet, kan dus ook hier. Koppelen en een archief downloaden kan alleen op de backup server zelf.

Dezelfde acties via de API (token van een beheerder, scope api/admin):

GET /api/v1/admin/backupinstance_id en de lijst met backup servers
POST /api/v1/admin/backup/servers{"name"}: nieuwe backup server; het antwoord bevat eenmalig key
GET /api/v1/admin/backup/servers/{id}server met remote (status), archives en config, zoals de backup server ze meldt
PUT /api/v1/admin/backup/servers/{id}{"name"}: hernoemen
POST /api/v1/admin/backup/servers/{id}/keynieuwe key (eenmalig in het antwoord)
DELETE /api/v1/admin/backup/servers/{id}ontkoppelen en vergeten
POST /api/v1/admin/backup/servers/{id}/actions/{name}actie van de backup server, bijvoorbeeld config.update met {"retention_days": "14"}, sync, archive, prune, archive.delete met {"name"}, of rollback met {"archive": "naam", "confirm": "naam"}

Het antwoord van een actie is het antwoord van de backup server, met dezelfde statuscode.

Protocol

De backup server praat met BlueGit met de key als bearer-token (Authorization: Bearer bgbk_…):

GET /api/v1/backup/infoinstance_id, base_url, naam en adres van de server bij deze key
POST /api/v1/backup/connect{"server_url", "server_id"}: waar BlueGit meldingen heen stuurt
GET /api/v1/backup/manifestalle bestanden: pad, grootte, mtime, mode; de database ook met sha256
GET /api/v1/backup/file?path=…één bestand
POST /api/v1/backup/restoretar.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/notifyer is iets veranderd
GET /api/v1/archives{"archives": [{name, created_at, size}]}
GET /api/v1/statusinterval, bewaartermijn, stand van de laatste rollback
POST /api/v1/rollback{"archive": "naam"}
* /api/v1/admin/…de beheeracties van de backup server (lijst: GET /api/v1/admin/actions, veld bluegit: true)

Meldingen. Elke gekoppelde backup server krijgt ze, ondertekend met zijn eigen key. 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 koppelingen staan in <state>/backup.json (0600, per server 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 servers (bluegit-backup)
2
3Een 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
5Eén BlueGit kan meerdere backup servers hebben (hoogstens 16), elk met een eigen Backupserver-Key. Een backup server hoort bij één BlueGit.
6
7## In BlueGit
8
9**Beheer > Backup** (`/admin/backup`, alleen installatiebeheerders) toont de lijst met backup servers: naam, gekoppeld of wachtend op de key, adres en laatste contact. **Backup server toevoegen** maakt een nieuwe server met een eigen key, die één keer wordt getoond.
10
11Per backup server (`/admin/backup/s/<id>`) staat dezelfde bediening als in de webinterface van de backup server zelf:
12
13- **Status**: laatste sync en het resultaat ervan, aantal syncs en meldingen, grootte van de kopie, archieven, de laatste rollback en de versie. Met de knoppen *Nu synchroniseren*, *Nu archiveren* en *Nu opruimen*.
14- **Instellingen** van de backup server: archiefinterval, bewaartermijn, minimale vrije ruimte, downloadsnelheid, syncintervallen, publiek adres en luisteradres. BlueGit krijgt de velden van de backup server en toont ze zoals ze daar staan.
15- **Backup-archieven** met *Verwijderen* en *Rollback*. Een rollback 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.
16- **Backupserver-Key** vervangen (de oude key werkt meteen niet meer; de server moet opnieuw koppelen), de server hernoemen, of key intrekken en de server verwijderen. Bij verwijderen vraagt BlueGit de backup server eerst om te ontkoppelen. De archieven blijven op de backup server staan.
17
18BlueGit kent de acties niet vooraf. Het vraagt ze op bij de backup server (`GET /api/v1/admin/actions`) en stuurt ze ondertekend door. Alles wat de backup server voor BlueGit openzet, kan dus ook hier. Koppelen en een archief downloaden kan alleen op de backup server zelf.
19
20Dezelfde acties via de API (token van een beheerder, scope `api`/`admin`):
21
22| | |
23|---|---|
24| `GET /api/v1/admin/backup` | `instance_id` en de lijst met backup servers |
25| `POST /api/v1/admin/backup/servers` | `{"name"}`: nieuwe backup server; het antwoord bevat eenmalig `key` |
26| `GET /api/v1/admin/backup/servers/{id}` | server met `remote` (status), `archives` en `config`, zoals de backup server ze meldt |
27| `PUT /api/v1/admin/backup/servers/{id}` | `{"name"}`: hernoemen |
28| `POST /api/v1/admin/backup/servers/{id}/key` | nieuwe key (eenmalig in het antwoord) |
29| `DELETE /api/v1/admin/backup/servers/{id}` | ontkoppelen en vergeten |
30| `POST /api/v1/admin/backup/servers/{id}/actions/{name}` | actie van de backup server, bijvoorbeeld `config.update` met `{"retention_days": "14"}`, `sync`, `archive`, `prune`, `archive.delete` met `{"name"}`, of `rollback` met `{"archive": "naam", "confirm": "naam"}` |
31
32Het antwoord van een actie is het antwoord van de backup server, met dezelfde statuscode.
33
34## Protocol
35
36**De backup server praat met BlueGit** met de key als bearer-token (`Authorization: Bearer bgbk_…`):
37
38| | |
39|---|---|
40| `GET /api/v1/backup/info` | `instance_id`, `base_url`, naam en adres van de server bij deze key |
41| `POST /api/v1/backup/connect` | `{"server_url", "server_id"}`: waar BlueGit meldingen heen stuurt |
42| `GET /api/v1/backup/manifest` | alle bestanden: pad, grootte, mtime, mode; de database ook met sha256 |
43| `GET /api/v1/backup/file?path=…` | één bestand |
44| `POST /api/v1/backup/restore` | tar.gz met logische paden; BlueGit pakt uit en herstart (202) |
45
46Vijf mislukte key-pogingen per minuut per IP geven daarna `429`.
47
48**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:
49
50```text
51X-BlueGit-Instance: <instance_id>
52X-BlueGit-Timestamp: <unix-seconden> (hoogstens 5 minuten verschil)
53X-BlueGit-Signature: hex(HMAC-SHA256(geheim, METHOD "\n" PAD "\n" TS "\n" sha256hex(body)))
54```
55
56| | |
57|---|---|
58| `POST /api/v1/notify` | er is iets veranderd |
59| `GET /api/v1/archives` | `{"archives": [{name, created_at, size}]}` |
60| `GET /api/v1/status` | interval, bewaartermijn, stand van de laatste rollback |
61| `POST /api/v1/rollback` | `{"archive": "naam"}` |
62| `* /api/v1/admin/…` | de beheeracties van de backup server (lijst: `GET /api/v1/admin/actions`, veld `bluegit: true`) |
63
64**Meldingen.** Elke gekoppelde backup server krijgt ze, ondertekend met zijn eigen key. 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.
65
66## Wat er in een backup zit
67
68```text
69state/bluegit.db consistente kopie (VACUUM INTO), niet het live bestand
70state/secret.key nodig voor de versleutelde geheimen in de database
71state/ssh/… SSH-hostkey
72state/logos/…, state/avatars/…
73data/repos/… bare repositories
74data/releases/… release-assets (zonder .incoming)
75data/artifacts/… CI-artifacts
76```
77
78Niet mee: `config.yml`, `storage_path`, `cache.json`, `backup.json` en `instance_id` (horen bij deze installatie), `data/work`, `*.lock` en symlinks. De koppelingen staan in `<state>/backup.json` (0600, per server alleen de hash van de key) en niet in de database, zodat een rollback naar een oud archief de koppeling niet terugdraait.
79
80## Terugzetten
81
82`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`.