BlueGit

timfa bluegit

Files

bluegit / docs / BACKUP.md

BACKUP.md

BACKUP.md 4.5 KiB Download Raw

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/backupstatus, gekoppelde server, archieven
POST /api/v1/admin/backup/keynieuwe key, {"key": "bgbk_…"} (eenmalig)
DELETE /api/v1/admin/backup/keykey 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/infoinstance_id, base_url, gekoppelde server
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"}

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
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
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
13Dezelfde 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
34Vijf 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
39X-BlueGit-Instance: <instance_id>
40X-BlueGit-Timestamp: <unix-seconden> (hoogstens 5 minuten verschil)
41X-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
56state/bluegit.db consistente kopie (VACUUM INTO), niet het live bestand
57state/secret.key nodig voor de versleutelde geheimen in de database
58state/ssh/… SSH-hostkey
59state/logos/…, state/avatars/…
60data/repos/… bare repositories
61data/releases/… release-assets (zonder .incoming)
62data/artifacts/… CI-artifacts
63```
64
65Niet 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`.