Merge branch 'cursor/readme-bezoekers-65da' into 'master'
docs: beschrijf BlueGit voor bezoekers See merge request Timfa/bluegit!54
@@ -1,34 +1,48 @@
1
1
# BlueGit
2
2
3
BlueGit is Tims eigen git-platform, bedoeld voor `git.timfalken.com` op een mini-PC met Arch Linux. De repositories staan op een configureerbare schijf (de 4 TB-disk). Aanmelden gaat via [auth.timfalken.com](https://auth.timfalken.com). Er is geen lokaal wachtwoord.
3
BlueGit is een self-hosted git-platform. Het is één Go-binary: de website, smart HTTP, de REST-API en de SSH-listener draaien in hetzelfde proces. Metadata staat in SQLite. Git-objecten staan in bare repositories op een schijf die de beheerder kiest. Docker wordt alleen gebruikt om CI-jobs te draaien.
4
4
5
Het logo is Tims blauwe ster: [`assets/logo.svg`](assets/logo.svg).
5
Er is geen lokaal wachtwoord. Aanmelden gaat via de OAuth-flow van [auth.timfalken.com](https://auth.timfalken.com).
6
7
Het logo is de blauwe ster: [`assets/logo.svg`](assets/logo.svg).
6
8
7
9

8
10
9
## Stack
11
## Wat het doet
12
13
- Repositories van een gebruiker of een groep, met bestanden, commits, branches, tags en releases.
14
- Merge requests met reviews, squash en het verwijderen van de bronbranch na een merge.
15
- Issues, met beschrijvingssjablonen in `.bluegit/issue_templates`. Merge requests gebruiken `.bluegit/merge_request_templates`. `Default.md` vult een lege beschrijving. Dezelfde namen onder `.gitlab/` zijn een terugval.
16
- Een ingebouwde CI-runner, Steve. Het bestand is `blue-ci-cd.yml`. Elke job draait in een eigen container. `image: bluegit/base` en de andere aliassen zijn image-presets die Steve lokaal bouwt.
17
- Webhooks op een repository of een groep, met presets, een eigen body en een overzicht van de laatste afleveringen.
18
- Geheimen als omgevingsvariabelen in een job. Een beschermd geheim gaat alleen mee op een beschermde branch.
19
- Groepen, met eigen leden, geheimen en webhooks.
20
- Git over SSH en over HTTPS.
21
- REST-API. Het schema staat op `/api/v1/openapi.json`.
22
- Self-update: de instantie installeert een nieuw AUR-pakket met pacman.
23
- Linkpreviews: een gedeelde pagina krijgt een kaart via Open Graph, oEmbed en `/-/card.png`.
24
25
Een repository hoort bij een gebruiker of bij een groep. De hoogste rol telt.
26
27
| Rol | Lezen | Schrijven op een gewone branch | Beschermde branch | Geheimen, webhooks, leden, verwijderen |
28
| --- | --- | --- | --- | --- |
29
| Alleen lezen | ja | nee | nee | nee |
30
| Ontwikkelaar | ja | ja | nee | nee |
31
| Beheerder | ja | ja | ja | ja |
10
32
11
Eén statische Go-binary, SQLite voor de metadata, de gewone `git` voor de objecten, en Docker alleen voor CI-jobs.
33
De installatiebeheerder is geen beheerder van andermans repository. Een onbeschermd geheim kan een pipeline uitlezen via `blue-ci-cd.yml`. Markeer het als beschermd als het alleen op een beschermde branch mee mag.
12
34
13
Die keuze houdt de mini-PC klein. Er is geen Postgres, geen Redis en geen aparte frontend-build. Git zelf doet smart HTTP; dat protocol opnieuw bouwen levert niets op. SQLite past bij één machine en één beheerder: de database is een bestand naast de repositories, op dezelfde schijf. Een kant-en-klaar product als Forgejo zou sneller een volle forge geven, maar niet deze auth-server, dit CI-bestand of dit webhookmodel.
35
## Installeren
14
36
15
## Wat deze basis al doet
37
Op Arch installeer je het AUR-pakket `bluegit`. De configuratie staat in `/etc/bluegit/config.yml`. De systemd-service heet `bluegit.service`.
16
38
17
- Aanmelden met de authorization-code-flow van auth.timfalken.com. De eerste ingelogde gebruiker wordt installatiebeheerder. `is_admin` van de auth-server geeft die rol niet, en de vlag geeft geen toegang tot andermans repositories, groepen of geheimen.
18
- Repositories van een gebruiker of een groep, met de rollen alleen-lezen, ontwikkelaar en beheerder. De standaardbranch is `master`.
19
- Git over HTTPS (smart HTTP) en SSH. Achter de ingress is HTTP plain, en de clone-URL gebruikt `ssh.public_host` en `ssh.public_port`. `ssh.listen` is de poort op de mini-PC.
20
- Webinterface: bestanden, commits, branches, merge requests, pipelines, releases, leden, geheimen en webhooks.
21
- `blue-ci-cd.yml`: stages, jobs, `needs`, `rules`, artifacts. Elke job in een eigen container.
22
- Geheimen als omgevingsvariabelen. Beschermde geheimen alleen op een beschermde branch.
23
- Releases op een commit, vanuit een pipeline met een job-token. Artifacts worden release-bestanden.
24
- Webhooks op repository en groep, met presets voor Discord, Grok Bot en een generieke JSON-webhook. Bestemmingen in privénetwerken worden geweigerd; het IP wordt bij het verbinden vastgezet.
25
- Een PKGBUILD, een systemd-unit en `packaging/install.sh`.
39
`bluegit example-config` print een voorbeeld. Het clientgeheim hoort in `/etc/bluegit/client_secret` (mode `0600`) of als `BLUEGIT_AUTH_CLIENT_SECRET` in `/etc/bluegit/secret.env`. Zonder configuratie én geheim start de service niet. De eerste aangemelde gebruiker wordt installatiebeheerder en kiest in `/setup` de schijf voor de repositories.
26
40
27
Wat nog niet af is, staat in [docs/ROADMAP.md](docs/ROADMAP.md). De vorm van het systeem staat in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). De auth-koppeling staat in [docs/AUTH.md](docs/AUTH.md). De ingress staat in [docs/INGRESS.md](docs/INGRESS.md). De besluiten staan in [docs/VRAGEN.md](docs/VRAGEN.md).
41
Hoe het pakket gepubliceerd wordt en hoe de self-update via pacman werkt, staat in [docs/AUR.md](docs/AUR.md). De stappen voor de installatie op git.timfalken.com staan in [docs/BEHEER.md](docs/BEHEER.md).
28
42
29
## Lokaal proberen
43
## Lokaal
30
44
31
`auth.mode: dev` maakt een sessie zonder de auth-server. Dat is geen wachtwoord, en de configuratie weigert deze modus zodra `base_url` op `git.timfalken.com` wijst.
45
`auth.mode: dev` maakt een sessie zonder de auth-server. De configuratie weigert die modus zodra `base_url` op `git.timfalken.com` wijst.
32
46
33
47
```yaml
34
48
base_url: http://127.0.0.1:8080
@@ -42,65 +56,29 @@ ci:
42
56
enabled: false
43
57
```
44
58
45
Laat `storage_path` weg. Na het aanmelden vraagt BlueGit om een absoluut pad dat al bestaat, beschrijfbaar is en minstens 1 GiB vrij heeft. `mkdir -p "$PWD/data"` en plak het absolute pad in dat scherm. Zet je toch `storage_path` in dit bestand, dan moet dat pad absoluut zijn; het slaat het scherm over zolang de state-map nog geen keuze bewaart.
46
47
59
```shell
48
60
go build -o bluegit ./cmd/bluegit
49
61
./bluegit serve --config bluegit.yml
50
62
```
51
63
52
Open http://127.0.0.1:8080 en meld aan. Onder Account maak je een toegangstoken. Git gebruikt dat token als wachtwoord:
53
54
```shell
55
git clone http://tim:bg_…@127.0.0.1:8080/tim/demo.git
56
```
57
58
## Installeren op Arch
64
Laat `storage_path` weg. Na het aanmelden vraagt BlueGit om een absoluut pad dat al bestaat, beschrijfbaar is en minstens 1 GiB vrij heeft. `mkdir -p "$PWD/data"` en plak dat pad in het scherm. Zet je toch `storage_path` in het bestand, dan moet dat pad absoluut zijn. Het slaat het scherm over zolang de state-map nog geen keuze bewaart.
59
65
60
Eerste keer met de hand, daarna kan de pipeline in [`blue-ci-cd.yml`](blue-ci-cd.yml) de binary vervangen.
66
Een toegangstoken maak je onder Account. Git gebruikt dat token als wachtwoord:
61
67
62
68
```shell
63
sudo packaging/install.sh
64
# of, vanuit de repository:
65
cd packaging/arch && makepkg -si
69
git clone http://tim:bg_…@127.0.0.1:8080/tim/demo.git
66
70
```
67
71
68
Daarna:
69
70
1. Mount de 4 TB-schijf op een pad dat jij kiest. Maak die map beschrijfbaar voor de gebruiker `bluegit`. Er is geen standaardpad.
71
2. Kopieer `/usr/share/bluegit/storage.conf.example` naar `/etc/systemd/system/bluegit.service.d/storage.conf` en zet `ReadWritePaths` op die map. Zonder die drop-in blokkeert `ProtectSystem` schrijven buiten `/var/lib/bluegit`, en de schrijftest in het setup-scherm faalt. De database blijft in `/var/lib/bluegit`.
72
3. Registreer bij https://auth.timfalken.com/admin het domein `git.timfalken.com` met callback-pad `/auth/callback`. Het client_id is het domein. Het geheim verschijnt één keer.
73
4. Zet het geheim in `/etc/bluegit/client_secret` (mode `0600`) of in `BLUEGIT_AUTH_CLIENT_SECRET` via `/etc/bluegit/secret.env`.
74
5. Zet de ingress op de andere machine. BlueGit zelf blijft plain HTTP. `trusted_proxies` is het adres van die ingress, `base_url` is `https://git.timfalken.com`, en `ssh.public_port` is de poort die gebruikers zien. Het voorbeeld staat in [docs/INGRESS.md](docs/INGRESS.md).
75
6. `systemctl daemon-reload && systemctl enable --now bluegit`. De eerste aanmelding wordt installatiebeheerder en kiest het pad in het setup-scherm. Daar staat ook hoeveel ruimte vrij is. Git en CI doen niets tot dat pad opgeslagen is.
72
## Documentatie
76
73
77
SSH voor git luistert op `ssh.listen` (in het voorbeeld `0.0.0.0:2222`), naast de SSH van het besturingssysteem. De hostkey komt de eerste keer in de opslagmap. De clone-URL gebruikt `ssh.public_host` en `ssh.public_port`, niet de bindpoort.
78
79
## Rollen
80
81
Een repository hoort bij een gebruiker (die is beheerder) of bij een groep. Iemand kan ook rechtstreeks lid zijn. De hoogste rol telt.
82
83
| Rol | Lezen | Schrijven op een gewone branch | Beschermde branch | Geheimen, webhooks, leden, verwijderen |
84
| --- | --- | --- | --- | --- |
85
| Alleen lezen | ja | nee | nee | nee |
86
| Ontwikkelaar | ja | ja | nee | nee |
87
| Beheerder | ja | ja | ja | ja |
88
89
Een ontwikkelaar ziet geheimen niet terug. Een job krijgt ze wel als omgevingsvariabele, anders kan CI er niets mee. Wie een pipeline mag starten, kan een onbeschermd geheim dus uitlezen via `blue-ci-cd.yml`. Markeer een geheim als beschermd als het alleen op een beschermde branch mee mag, en bescherm `master`.
90
91
De installatiebeheerder is geen beheerder van andermans repository. Geheimen, groepen en privérepositories blijven bij de leden.
92
93
## CI, releases, webhooks
94
95
De specificatie staat in [docs/CI.md](docs/CI.md). Kort: `stages`, `jobs`, `image`, `script`, `needs`, `rules`, `artifacts`. Elke job is `docker run` van dat image.
96
97
Een release maakt de pipeline zelf, met `CI_JOB_TOKEN` en `CI_API_URL`. Bestanden komen uit artifacts van een eerdere job in dezelfde pipeline, niet uit de request-body.
98
99
Webhooks hebben een URL-sjabloon, eigen headers en een body-sjabloon. `{{secret.NAAM}}` en `{{event.summary}}` worden bij het versturen ingevuld. Een push kan gefilterd worden op een exacte branch of op `re:` plus een reguliere expressie. Presets: `discord`, `grok` (JSON met een `Authorization`-header) en `generic`. Een bestemming in een privénetwerk, of een naam die daarheen oplost, wordt geweigerd. Het IP van een publieke naam wordt vastgezet op het moment van verbinden, en elke redirect wordt opnieuw gekeurd.
100
101
## Zelf bijwerken
102
103
[`blue-ci-cd.yml`](blue-ci-cd.yml) test, bouwt een statische binary, maakt een release en kopieert die via SSH naar de host. Daar is geen apart deploy-kanaal voor. De eerste binary zet je neer met het pakket. Daarna zijn de geheimen `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_PORT`, `DEPLOY_PATH` en `DEPLOY_SSH_KEY` genoeg, als beschermde geheimen op een beschermde branch.
74
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) beschrijft het proces, de schijf en waarom het één binary is.
75
- [docs/AUTH.md](docs/AUTH.md) beschrijft de OAuth-koppeling.
76
- [docs/INGRESS.md](docs/INGRESS.md) beschrijft TLS en de publieke SSH-poort.
77
- [docs/CI.md](docs/CI.md) beschrijft `blue-ci-cd.yml` en Steve.
78
- [docs/AUR.md](docs/AUR.md) beschrijft het pakket en de self-update.
79
- [docs/BEHEER.md](docs/BEHEER.md) beschrijft de installatie op git.timfalken.com.
80
- [docs/MIGRATIE.md](docs/MIGRATIE.md) beschrijft de overstap van de user-unit naar de system-service.
81
- [docs/ROADMAP.md](docs/ROADMAP.md) en [docs/VRAGEN.md](docs/VRAGEN.md) houden bij wat nog openstaat en welke besluiten al vastliggen.
104
82
105
83
## Tests
106
84
@@ -108,8 +86,6 @@ Webhooks hebben een URL-sjabloon, eigen headers en een body-sjabloon. `{{secret.
108
86
go test ./...
109
87
```
110
88
111
De kern zit in `internal/access` (rollen en beschermde branches), `internal/ci` (de parser en wanneer een job mag starten) en `internal/webhook` (filters en sjablonen). `internal/server` doet een ronde met een echte `git push` en controleert dat een ontwikkelaar geen geheim kan opslaan.
112
113
89
## Licentie
114
90
115
91
MIT. Zie [LICENSE](LICENSE).
@@ -1,34 +1,48 @@1
# BlueGit1
# BlueGit2
2
3
BlueGit is Tims eigen git-platform, bedoeld voor `git.timfalken.com` op een mini-PC met Arch Linux. De repositories staan op een configureerbare schijf (de 4 TB-disk). Aanmelden gaat via [auth.timfalken.com](https://auth.timfalken.com). Er is geen lokaal wachtwoord.3
BlueGit is een self-hosted git-platform. Het is één Go-binary: de website, smart HTTP, de REST-API en de SSH-listener draaien in hetzelfde proces. Metadata staat in SQLite. Git-objecten staan in bare repositories op een schijf die de beheerder kiest. Docker wordt alleen gebruikt om CI-jobs te draaien.4
4
5
Het logo is Tims blauwe ster: [`assets/logo.svg`](assets/logo.svg).5
Er is geen lokaal wachtwoord. Aanmelden gaat via de OAuth-flow van [auth.timfalken.com](https://auth.timfalken.com).6
7
Het logo is de blauwe ster: [`assets/logo.svg`](assets/logo.svg).6
8
7
9
8
10
9
## Stack11
## Wat het doet12
13
- Repositories van een gebruiker of een groep, met bestanden, commits, branches, tags en releases.14
- Merge requests met reviews, squash en het verwijderen van de bronbranch na een merge.15
- Issues, met beschrijvingssjablonen in `.bluegit/issue_templates`. Merge requests gebruiken `.bluegit/merge_request_templates`. `Default.md` vult een lege beschrijving. Dezelfde namen onder `.gitlab/` zijn een terugval.16
- Een ingebouwde CI-runner, Steve. Het bestand is `blue-ci-cd.yml`. Elke job draait in een eigen container. `image: bluegit/base` en de andere aliassen zijn image-presets die Steve lokaal bouwt.17
- Webhooks op een repository of een groep, met presets, een eigen body en een overzicht van de laatste afleveringen.18
- Geheimen als omgevingsvariabelen in een job. Een beschermd geheim gaat alleen mee op een beschermde branch.19
- Groepen, met eigen leden, geheimen en webhooks.20
- Git over SSH en over HTTPS.21
- REST-API. Het schema staat op `/api/v1/openapi.json`.22
- Self-update: de instantie installeert een nieuw AUR-pakket met pacman.23
- Linkpreviews: een gedeelde pagina krijgt een kaart via Open Graph, oEmbed en `/-/card.png`.24
25
Een repository hoort bij een gebruiker of bij een groep. De hoogste rol telt.26
27
| Rol | Lezen | Schrijven op een gewone branch | Beschermde branch | Geheimen, webhooks, leden, verwijderen |28
| --- | --- | --- | --- | --- |29
| Alleen lezen | ja | nee | nee | nee |30
| Ontwikkelaar | ja | ja | nee | nee |31
| Beheerder | ja | ja | ja | ja |10
32
11
Eén statische Go-binary, SQLite voor de metadata, de gewone `git` voor de objecten, en Docker alleen voor CI-jobs.33
De installatiebeheerder is geen beheerder van andermans repository. Een onbeschermd geheim kan een pipeline uitlezen via `blue-ci-cd.yml`. Markeer het als beschermd als het alleen op een beschermde branch mee mag.12
34
13
Die keuze houdt de mini-PC klein. Er is geen Postgres, geen Redis en geen aparte frontend-build. Git zelf doet smart HTTP; dat protocol opnieuw bouwen levert niets op. SQLite past bij één machine en één beheerder: de database is een bestand naast de repositories, op dezelfde schijf. Een kant-en-klaar product als Forgejo zou sneller een volle forge geven, maar niet deze auth-server, dit CI-bestand of dit webhookmodel.35
## Installeren14
36
15
## Wat deze basis al doet37
Op Arch installeer je het AUR-pakket `bluegit`. De configuratie staat in `/etc/bluegit/config.yml`. De systemd-service heet `bluegit.service`.16
38
17
- Aanmelden met de authorization-code-flow van auth.timfalken.com. De eerste ingelogde gebruiker wordt installatiebeheerder. `is_admin` van de auth-server geeft die rol niet, en de vlag geeft geen toegang tot andermans repositories, groepen of geheimen.39
`bluegit example-config` print een voorbeeld. Het clientgeheim hoort in `/etc/bluegit/client_secret` (mode `0600`) of als `BLUEGIT_AUTH_CLIENT_SECRET` in `/etc/bluegit/secret.env`. Zonder configuratie én geheim start de service niet. De eerste aangemelde gebruiker wordt installatiebeheerder en kiest in `/setup` de schijf voor de repositories.18
- Repositories van een gebruiker of een groep, met de rollen alleen-lezen, ontwikkelaar en beheerder. De standaardbranch is `master`.19
- Git over HTTPS (smart HTTP) en SSH. Achter de ingress is HTTP plain, en de clone-URL gebruikt `ssh.public_host` en `ssh.public_port`. `ssh.listen` is de poort op de mini-PC.20
- Webinterface: bestanden, commits, branches, merge requests, pipelines, releases, leden, geheimen en webhooks.21
- `blue-ci-cd.yml`: stages, jobs, `needs`, `rules`, artifacts. Elke job in een eigen container.22
- Geheimen als omgevingsvariabelen. Beschermde geheimen alleen op een beschermde branch.23
- Releases op een commit, vanuit een pipeline met een job-token. Artifacts worden release-bestanden.24
- Webhooks op repository en groep, met presets voor Discord, Grok Bot en een generieke JSON-webhook. Bestemmingen in privénetwerken worden geweigerd; het IP wordt bij het verbinden vastgezet.25
- Een PKGBUILD, een systemd-unit en `packaging/install.sh`.26
40
27
Wat nog niet af is, staat in [docs/ROADMAP.md](docs/ROADMAP.md). De vorm van het systeem staat in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). De auth-koppeling staat in [docs/AUTH.md](docs/AUTH.md). De ingress staat in [docs/INGRESS.md](docs/INGRESS.md). De besluiten staan in [docs/VRAGEN.md](docs/VRAGEN.md).41
Hoe het pakket gepubliceerd wordt en hoe de self-update via pacman werkt, staat in [docs/AUR.md](docs/AUR.md). De stappen voor de installatie op git.timfalken.com staan in [docs/BEHEER.md](docs/BEHEER.md).28
42
29
## Lokaal proberen43
## Lokaal30
44
31
`auth.mode: dev` maakt een sessie zonder de auth-server. Dat is geen wachtwoord, en de configuratie weigert deze modus zodra `base_url` op `git.timfalken.com` wijst.45
`auth.mode: dev` maakt een sessie zonder de auth-server. De configuratie weigert die modus zodra `base_url` op `git.timfalken.com` wijst.32
46
33
```yaml47
```yaml34
base_url: http://127.0.0.1:808048
base_url: http://127.0.0.1:8080@@ -42,65 +56,29 @@ ci:42
enabled: false56
enabled: false43
```57
```44
58
45
Laat `storage_path` weg. Na het aanmelden vraagt BlueGit om een absoluut pad dat al bestaat, beschrijfbaar is en minstens 1 GiB vrij heeft. `mkdir -p "$PWD/data"` en plak het absolute pad in dat scherm. Zet je toch `storage_path` in dit bestand, dan moet dat pad absoluut zijn; het slaat het scherm over zolang de state-map nog geen keuze bewaart.46
47
```shell59
```shell48
go build -o bluegit ./cmd/bluegit60
go build -o bluegit ./cmd/bluegit49
./bluegit serve --config bluegit.yml61
./bluegit serve --config bluegit.yml50
```62
```51
63
52
Open http://127.0.0.1:8080 en meld aan. Onder Account maak je een toegangstoken. Git gebruikt dat token als wachtwoord:64
Laat `storage_path` weg. Na het aanmelden vraagt BlueGit om een absoluut pad dat al bestaat, beschrijfbaar is en minstens 1 GiB vrij heeft. `mkdir -p "$PWD/data"` en plak dat pad in het scherm. Zet je toch `storage_path` in het bestand, dan moet dat pad absoluut zijn. Het slaat het scherm over zolang de state-map nog geen keuze bewaart.53
54
```shell55
git clone http://tim:bg_…@127.0.0.1:8080/tim/demo.git56
```57
58
## Installeren op Arch59
65
60
Eerste keer met de hand, daarna kan de pipeline in [`blue-ci-cd.yml`](blue-ci-cd.yml) de binary vervangen.66
Een toegangstoken maak je onder Account. Git gebruikt dat token als wachtwoord:61
67
62
```shell68
```shell63
sudo packaging/install.sh69
git clone http://tim:bg_…@127.0.0.1:8080/tim/demo.git64
# of, vanuit de repository:65
cd packaging/arch && makepkg -si66
```70
```67
71
68
Daarna:72
## Documentatie69
70
1. Mount de 4 TB-schijf op een pad dat jij kiest. Maak die map beschrijfbaar voor de gebruiker `bluegit`. Er is geen standaardpad.71
2. Kopieer `/usr/share/bluegit/storage.conf.example` naar `/etc/systemd/system/bluegit.service.d/storage.conf` en zet `ReadWritePaths` op die map. Zonder die drop-in blokkeert `ProtectSystem` schrijven buiten `/var/lib/bluegit`, en de schrijftest in het setup-scherm faalt. De database blijft in `/var/lib/bluegit`.72
3. Registreer bij https://auth.timfalken.com/admin het domein `git.timfalken.com` met callback-pad `/auth/callback`. Het client_id is het domein. Het geheim verschijnt één keer.73
4. Zet het geheim in `/etc/bluegit/client_secret` (mode `0600`) of in `BLUEGIT_AUTH_CLIENT_SECRET` via `/etc/bluegit/secret.env`.74
5. Zet de ingress op de andere machine. BlueGit zelf blijft plain HTTP. `trusted_proxies` is het adres van die ingress, `base_url` is `https://git.timfalken.com`, en `ssh.public_port` is de poort die gebruikers zien. Het voorbeeld staat in [docs/INGRESS.md](docs/INGRESS.md).75
6. `systemctl daemon-reload && systemctl enable --now bluegit`. De eerste aanmelding wordt installatiebeheerder en kiest het pad in het setup-scherm. Daar staat ook hoeveel ruimte vrij is. Git en CI doen niets tot dat pad opgeslagen is.76
73
77
SSH voor git luistert op `ssh.listen` (in het voorbeeld `0.0.0.0:2222`), naast de SSH van het besturingssysteem. De hostkey komt de eerste keer in de opslagmap. De clone-URL gebruikt `ssh.public_host` en `ssh.public_port`, niet de bindpoort.74
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) beschrijft het proces, de schijf en waarom het één binary is.78
75
- [docs/AUTH.md](docs/AUTH.md) beschrijft de OAuth-koppeling.79
## Rollen76
- [docs/INGRESS.md](docs/INGRESS.md) beschrijft TLS en de publieke SSH-poort.80
77
- [docs/CI.md](docs/CI.md) beschrijft `blue-ci-cd.yml` en Steve.81
Een repository hoort bij een gebruiker (die is beheerder) of bij een groep. Iemand kan ook rechtstreeks lid zijn. De hoogste rol telt.78
- [docs/AUR.md](docs/AUR.md) beschrijft het pakket en de self-update.82
79
- [docs/BEHEER.md](docs/BEHEER.md) beschrijft de installatie op git.timfalken.com.83
| Rol | Lezen | Schrijven op een gewone branch | Beschermde branch | Geheimen, webhooks, leden, verwijderen |80
- [docs/MIGRATIE.md](docs/MIGRATIE.md) beschrijft de overstap van de user-unit naar de system-service.84
| --- | --- | --- | --- | --- |81
- [docs/ROADMAP.md](docs/ROADMAP.md) en [docs/VRAGEN.md](docs/VRAGEN.md) houden bij wat nog openstaat en welke besluiten al vastliggen.85
| Alleen lezen | ja | nee | nee | nee |86
| Ontwikkelaar | ja | ja | nee | nee |87
| Beheerder | ja | ja | ja | ja |88
89
Een ontwikkelaar ziet geheimen niet terug. Een job krijgt ze wel als omgevingsvariabele, anders kan CI er niets mee. Wie een pipeline mag starten, kan een onbeschermd geheim dus uitlezen via `blue-ci-cd.yml`. Markeer een geheim als beschermd als het alleen op een beschermde branch mee mag, en bescherm `master`.90
91
De installatiebeheerder is geen beheerder van andermans repository. Geheimen, groepen en privérepositories blijven bij de leden.92
93
## CI, releases, webhooks94
95
De specificatie staat in [docs/CI.md](docs/CI.md). Kort: `stages`, `jobs`, `image`, `script`, `needs`, `rules`, `artifacts`. Elke job is `docker run` van dat image.96
97
Een release maakt de pipeline zelf, met `CI_JOB_TOKEN` en `CI_API_URL`. Bestanden komen uit artifacts van een eerdere job in dezelfde pipeline, niet uit de request-body.98
99
Webhooks hebben een URL-sjabloon, eigen headers en een body-sjabloon. `{{secret.NAAM}}` en `{{event.summary}}` worden bij het versturen ingevuld. Een push kan gefilterd worden op een exacte branch of op `re:` plus een reguliere expressie. Presets: `discord`, `grok` (JSON met een `Authorization`-header) en `generic`. Een bestemming in een privénetwerk, of een naam die daarheen oplost, wordt geweigerd. Het IP van een publieke naam wordt vastgezet op het moment van verbinden, en elke redirect wordt opnieuw gekeurd.100
101
## Zelf bijwerken102
103
[`blue-ci-cd.yml`](blue-ci-cd.yml) test, bouwt een statische binary, maakt een release en kopieert die via SSH naar de host. Daar is geen apart deploy-kanaal voor. De eerste binary zet je neer met het pakket. Daarna zijn de geheimen `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_PORT`, `DEPLOY_PATH` en `DEPLOY_SSH_KEY` genoeg, als beschermde geheimen op een beschermde branch.104
82
105
## Tests83
## Tests106
84
@@ -108,8 +86,6 @@ Webhooks hebben een URL-sjabloon, eigen headers en een body-sjabloon. `{{secret.108
go test ./...86
go test ./...109
```87
```110
88
111
De kern zit in `internal/access` (rollen en beschermde branches), `internal/ci` (de parser en wanneer een job mag starten) en `internal/webhook` (filters en sjablonen). `internal/server` doet een ronde met een echte `git push` en controleert dat een ontwikkelaar geen geheim kan opslaan.112
113
## Licentie89
## Licentie114
90
115
MIT. Zie [LICENSE](LICENSE).91
MIT. Zie [LICENSE](LICENSE).@@ -20,7 +20,7 @@ De unit is de bestaande system-unit: `User=bluegit`, `ExecStart` met `/etc/blueg
20
20
21
21
`packaging/aur/bluegit.install` maakt bij installatie en upgrade de systeemgebruiker en de state-map aan. `post_install` doet `systemctl daemon-reload` en daarna `systemctl enable --now bluegit.service`, maar alleen als `/etc/bluegit/config.yml` er al is én het clientgeheim in `/etc/bluegit/client_secret` of als `BLUEGIT_AUTH_CLIENT_SECRET` in `/etc/bluegit/secret.env` staat. Een lege `client_secret: ""` telt niet. Ontbreekt een van beide, dan print de hook de vervolgstappen en start hij niets. `post_upgrade` herlaadt systemd en doet `systemctl try-restart bluegit.service`. `pre_remove` doet `systemctl disable --now bluegit.service`. Draait systemd niet (chroot of container), dan slaat de hook die stappen over zonder fout. `backup=('etc/bluegit/config.yml')` laat een aangepaste config staan.
22
22
23
De huidige user-unit (`/home/timfa/bluegit/config.yml`, `/home/timfa/bluegit/state`, datadisk `/home/timfa/temp-bluegit`) gaat over naar deze system-service volgens [MIGRATIE.md](MIGRATIE.md). De datadisk verhuist naar `/srv/bluegit`; een pad onder `/home` blijft met `ProtectHome=true` onbereikbaar.
23
De huidige user-unit (`/home/timfa/bluegit/config.yml`, `/home/timfa/bluegit/state`, datadisk `/home/timfa/temp-bluegit`) gaat over naar deze system-service volgens [MIGRATIE.md](MIGRATIE.md). De datadisk verhuist naar `/srv/bluegit`; een pad onder `/home` blijft met `ProtectHome=true` onbereikbaar. De schijf, het clientgeheim en de ingress van deze installatie staan in [BEHEER.md](BEHEER.md).
24
24
25
25
## Geheimen
26
26
@@ -20,7 +20,7 @@ De unit is de bestaande system-unit: `User=bluegit`, `ExecStart` met `/etc/blueg20
20
21
`packaging/aur/bluegit.install` maakt bij installatie en upgrade de systeemgebruiker en de state-map aan. `post_install` doet `systemctl daemon-reload` en daarna `systemctl enable --now bluegit.service`, maar alleen als `/etc/bluegit/config.yml` er al is én het clientgeheim in `/etc/bluegit/client_secret` of als `BLUEGIT_AUTH_CLIENT_SECRET` in `/etc/bluegit/secret.env` staat. Een lege `client_secret: ""` telt niet. Ontbreekt een van beide, dan print de hook de vervolgstappen en start hij niets. `post_upgrade` herlaadt systemd en doet `systemctl try-restart bluegit.service`. `pre_remove` doet `systemctl disable --now bluegit.service`. Draait systemd niet (chroot of container), dan slaat de hook die stappen over zonder fout. `backup=('etc/bluegit/config.yml')` laat een aangepaste config staan.21
`packaging/aur/bluegit.install` maakt bij installatie en upgrade de systeemgebruiker en de state-map aan. `post_install` doet `systemctl daemon-reload` en daarna `systemctl enable --now bluegit.service`, maar alleen als `/etc/bluegit/config.yml` er al is én het clientgeheim in `/etc/bluegit/client_secret` of als `BLUEGIT_AUTH_CLIENT_SECRET` in `/etc/bluegit/secret.env` staat. Een lege `client_secret: ""` telt niet. Ontbreekt een van beide, dan print de hook de vervolgstappen en start hij niets. `post_upgrade` herlaadt systemd en doet `systemctl try-restart bluegit.service`. `pre_remove` doet `systemctl disable --now bluegit.service`. Draait systemd niet (chroot of container), dan slaat de hook die stappen over zonder fout. `backup=('etc/bluegit/config.yml')` laat een aangepaste config staan.22
22
23
De huidige user-unit (`/home/timfa/bluegit/config.yml`, `/home/timfa/bluegit/state`, datadisk `/home/timfa/temp-bluegit`) gaat over naar deze system-service volgens [MIGRATIE.md](MIGRATIE.md). De datadisk verhuist naar `/srv/bluegit`; een pad onder `/home` blijft met `ProtectHome=true` onbereikbaar.23
De huidige user-unit (`/home/timfa/bluegit/config.yml`, `/home/timfa/bluegit/state`, datadisk `/home/timfa/temp-bluegit`) gaat over naar deze system-service volgens [MIGRATIE.md](MIGRATIE.md). De datadisk verhuist naar `/srv/bluegit`; een pad onder `/home` blijft met `ProtectHome=true` onbereikbaar. De schijf, het clientgeheim en de ingress van deze installatie staan in [BEHEER.md](BEHEER.md).24
24
25
## Geheimen25
## Geheimen26
26
@@ -0,0 +1,50 @@
1
# Beheer van git.timfalken.com
2
3
Deze stappen horen bij de installatie op de mini-PC. Ze stonden eerder in de README. Het pakket, de config en de service voor een bezoeker staan daar nog. De migratie van de oude user-unit staat in [MIGRATIE.md](MIGRATIE.md).
4
5
BlueGit draait op `git.timfalken.com`. De repositories staan op een configureerbare schijf (de 4 TB-disk). Aanmelden gaat via [auth.timfalken.com](https://auth.timfalken.com).
6
7
## Eerste installatie
8
9
Eerste keer met de hand, daarna kan de pipeline in [`blue-ci-cd.yml`](../blue-ci-cd.yml) de binary vervangen. Het AUR-pakket en de self-update via pacman staan in [AUR.md](AUR.md).
10
11
```shell
12
sudo packaging/install.sh
13
# of, vanuit de repository:
14
cd packaging/arch && makepkg -si
15
```
16
17
Daarna:
18
19
1. Mount de 4 TB-schijf op een pad dat jij kiest. Maak die map beschrijfbaar voor de gebruiker `bluegit`. Er is geen standaardpad.
20
2. Kopieer `/usr/share/bluegit/storage.conf.example` naar `/etc/systemd/system/bluegit.service.d/storage.conf` en zet `ReadWritePaths` op die map. Zonder die drop-in blokkeert `ProtectSystem` schrijven buiten `/var/lib/bluegit`, en de schrijftest in het setup-scherm faalt. De database blijft in `/var/lib/bluegit`.
21
3. Registreer bij https://auth.timfalken.com/admin het domein `git.timfalken.com` met callback-pad `/auth/callback`. Het client_id is het domein. Het geheim verschijnt één keer.
22
4. Zet het geheim in `/etc/bluegit/client_secret` (mode `0600`) of in `BLUEGIT_AUTH_CLIENT_SECRET` via `/etc/bluegit/secret.env`.
23
5. Zet de ingress op de andere machine. BlueGit zelf blijft plain HTTP. `trusted_proxies` is het adres van die ingress, `base_url` is `https://git.timfalken.com`, en `ssh.public_port` is de poort die gebruikers zien. Het voorbeeld staat in [INGRESS.md](INGRESS.md).
24
6. `systemctl daemon-reload && systemctl enable --now bluegit`. De eerste aanmelding wordt installatiebeheerder en kiest het pad in het setup-scherm. Daar staat ook hoeveel ruimte vrij is. Git en CI doen niets tot dat pad opgeslagen is.
25
26
SSH voor git luistert op `ssh.listen` (in het voorbeeld `0.0.0.0:2222`), naast de SSH van het besturingssysteem. De hostkey komt de eerste keer in de opslagmap. De clone-URL gebruikt `ssh.public_host` en `ssh.public_port`, niet de bindpoort.
27
28
## Waarom deze vorm op deze machine
29
30
Eén statische Go-binary, SQLite voor de metadata, de gewone `git` voor de objecten, en Docker alleen voor CI-jobs. Die keuze houdt de mini-PC klein. Er is geen Postgres, geen Redis en geen aparte frontend-build. Git zelf doet smart HTTP; dat protocol opnieuw bouwen levert niets op. SQLite past bij één machine en één beheerder: de database is een bestand naast de repositories, op dezelfde schijf. Een kant-en-klaar product als Forgejo zou sneller een volle forge geven, maar niet deze auth-server, dit CI-bestand of dit webhookmodel.
31
32
## Rollen en geheimen
33
34
Een ontwikkelaar ziet geheimen niet terug. Een job krijgt ze wel als omgevingsvariabele, anders kan CI er niets mee. Wie een pipeline mag starten, kan een onbeschermd geheim dus uitlezen via `blue-ci-cd.yml`. Markeer een geheim als beschermd als het alleen op een beschermde branch mee mag, en bescherm `master`.
35
36
De installatiebeheerder is geen beheerder van andermans repository. Geheimen, groepen en privérepositories blijven bij de leden.
37
38
## CI, releases en webhooks
39
40
De specificatie staat in [CI.md](CI.md). Kort: `stages`, `jobs`, `image`, `script`, `needs`, `rules`, `artifacts`. Elke job is `docker run` van dat image.
41
42
Een release maakt de pipeline zelf, met `CI_JOB_TOKEN` en `CI_API_URL`. Bestanden komen uit artifacts van een eerdere job in dezelfde pipeline, niet uit de request-body.
43
44
Webhooks hebben een URL-sjabloon, eigen headers en een body-sjabloon. `{{secret.NAAM}}` en `{{event.summary}}` worden bij het versturen ingevuld. Een push kan gefilterd worden op een exacte branch of op `re:` plus een reguliere expressie. Presets: `discord`, `grok` (JSON met een `Authorization`-header) en `generic`. Een bestemming in een privénetwerk, of een naam die daarheen oplost, wordt geweigerd. Het IP van een publieke naam wordt vastgezet op het moment van verbinden, en elke redirect wordt opnieuw gekeurd.
45
46
## Zelf bijwerken via SSH
47
48
[`blue-ci-cd.yml`](../blue-ci-cd.yml) test, bouwt een statische binary, maakt een release en kan die via SSH naar de host kopiëren. De eerste binary zet je neer met het pakket. Daarna zijn de geheimen `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_PORT`, `DEPLOY_PATH` en `DEPLOY_SSH_KEY` genoeg, als beschermde geheimen op een beschermde branch.
49
50
De geïnstalleerde instantie kan zich daarnaast zelf bijwerken door het AUR-pakket met pacman te installeren. Dat pad, de unit `bluegit-update.service` en de token staan in [AUR.md](AUR.md).
@@ -0,0 +1,50 @@1
# Beheer van git.timfalken.com2
3
Deze stappen horen bij de installatie op de mini-PC. Ze stonden eerder in de README. Het pakket, de config en de service voor een bezoeker staan daar nog. De migratie van de oude user-unit staat in [MIGRATIE.md](MIGRATIE.md).4
5
BlueGit draait op `git.timfalken.com`. De repositories staan op een configureerbare schijf (de 4 TB-disk). Aanmelden gaat via [auth.timfalken.com](https://auth.timfalken.com).6
7
## Eerste installatie8
9
Eerste keer met de hand, daarna kan de pipeline in [`blue-ci-cd.yml`](../blue-ci-cd.yml) de binary vervangen. Het AUR-pakket en de self-update via pacman staan in [AUR.md](AUR.md).10
11
```shell12
sudo packaging/install.sh13
# of, vanuit de repository:14
cd packaging/arch && makepkg -si15
```16
17
Daarna:18
19
1. Mount de 4 TB-schijf op een pad dat jij kiest. Maak die map beschrijfbaar voor de gebruiker `bluegit`. Er is geen standaardpad.20
2. Kopieer `/usr/share/bluegit/storage.conf.example` naar `/etc/systemd/system/bluegit.service.d/storage.conf` en zet `ReadWritePaths` op die map. Zonder die drop-in blokkeert `ProtectSystem` schrijven buiten `/var/lib/bluegit`, en de schrijftest in het setup-scherm faalt. De database blijft in `/var/lib/bluegit`.21
3. Registreer bij https://auth.timfalken.com/admin het domein `git.timfalken.com` met callback-pad `/auth/callback`. Het client_id is het domein. Het geheim verschijnt één keer.22
4. Zet het geheim in `/etc/bluegit/client_secret` (mode `0600`) of in `BLUEGIT_AUTH_CLIENT_SECRET` via `/etc/bluegit/secret.env`.23
5. Zet de ingress op de andere machine. BlueGit zelf blijft plain HTTP. `trusted_proxies` is het adres van die ingress, `base_url` is `https://git.timfalken.com`, en `ssh.public_port` is de poort die gebruikers zien. Het voorbeeld staat in [INGRESS.md](INGRESS.md).24
6. `systemctl daemon-reload && systemctl enable --now bluegit`. De eerste aanmelding wordt installatiebeheerder en kiest het pad in het setup-scherm. Daar staat ook hoeveel ruimte vrij is. Git en CI doen niets tot dat pad opgeslagen is.25
26
SSH voor git luistert op `ssh.listen` (in het voorbeeld `0.0.0.0:2222`), naast de SSH van het besturingssysteem. De hostkey komt de eerste keer in de opslagmap. De clone-URL gebruikt `ssh.public_host` en `ssh.public_port`, niet de bindpoort.27
28
## Waarom deze vorm op deze machine29
30
Eén statische Go-binary, SQLite voor de metadata, de gewone `git` voor de objecten, en Docker alleen voor CI-jobs. Die keuze houdt de mini-PC klein. Er is geen Postgres, geen Redis en geen aparte frontend-build. Git zelf doet smart HTTP; dat protocol opnieuw bouwen levert niets op. SQLite past bij één machine en één beheerder: de database is een bestand naast de repositories, op dezelfde schijf. Een kant-en-klaar product als Forgejo zou sneller een volle forge geven, maar niet deze auth-server, dit CI-bestand of dit webhookmodel.31
32
## Rollen en geheimen33
34
Een ontwikkelaar ziet geheimen niet terug. Een job krijgt ze wel als omgevingsvariabele, anders kan CI er niets mee. Wie een pipeline mag starten, kan een onbeschermd geheim dus uitlezen via `blue-ci-cd.yml`. Markeer een geheim als beschermd als het alleen op een beschermde branch mee mag, en bescherm `master`.35
36
De installatiebeheerder is geen beheerder van andermans repository. Geheimen, groepen en privérepositories blijven bij de leden.37
38
## CI, releases en webhooks39
40
De specificatie staat in [CI.md](CI.md). Kort: `stages`, `jobs`, `image`, `script`, `needs`, `rules`, `artifacts`. Elke job is `docker run` van dat image.41
42
Een release maakt de pipeline zelf, met `CI_JOB_TOKEN` en `CI_API_URL`. Bestanden komen uit artifacts van een eerdere job in dezelfde pipeline, niet uit de request-body.43
44
Webhooks hebben een URL-sjabloon, eigen headers en een body-sjabloon. `{{secret.NAAM}}` en `{{event.summary}}` worden bij het versturen ingevuld. Een push kan gefilterd worden op een exacte branch of op `re:` plus een reguliere expressie. Presets: `discord`, `grok` (JSON met een `Authorization`-header) en `generic`. Een bestemming in een privénetwerk, of een naam die daarheen oplost, wordt geweigerd. Het IP van een publieke naam wordt vastgezet op het moment van verbinden, en elke redirect wordt opnieuw gekeurd.45
46
## Zelf bijwerken via SSH47
48
[`blue-ci-cd.yml`](../blue-ci-cd.yml) test, bouwt een statische binary, maakt een release en kan die via SSH naar de host kopiëren. De eerste binary zet je neer met het pakket. Daarna zijn de geheimen `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_PORT`, `DEPLOY_PATH` en `DEPLOY_SSH_KEY` genoeg, als beschermde geheimen op een beschermde branch.49
50
De geïnstalleerde instantie kan zich daarnaast zelf bijwerken door het AUR-pakket met pacman te installeren. Dat pad, de unit `bluegit-update.service` en de token staan in [AUR.md](AUR.md).