Beheer van git.timfalken.com
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.
BlueGit draait op git.timfalken.com. De repositories staan op een configureerbare schijf (de 4 TB-disk). Aanmelden gaat via auth.timfalken.com.
Eerste installatie
Eerste keer met de hand, daarna kan de pipeline in blue-ci-cd.yml de binary vervangen. Het AUR-pakket en de self-update via pacman staan in AUR.md.
sudo packaging/install.sh
# of, vanuit de repository:
cd packaging/arch && makepkg -si
Daarna:
1. Mount de 4 TB-schijf op een pad dat jij kiest. Maak die map beschrijfbaar voor de gebruiker bluegit. Er is geen standaardpad. 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. 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. 4. Zet het geheim in /etc/bluegit/client_secret (mode 0600) of in BLUEGIT_AUTH_CLIENT_SECRET via /etc/bluegit/secret.env. 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. 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.
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.
Waarom deze vorm op deze machine
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.
Rollen en geheimen
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.
De installatiebeheerder is geen beheerder van andermans repository. Geheimen, groepen en privérepositories blijven bij de leden.
CI, releases en webhooks
De specificatie staat in CI.md. Kort: stages, jobs, image, script, needs, rules, artifacts. Elke job is docker run van dat image.
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.
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.
Zelf bijwerken via SSH
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.
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.
Beheer in de webinterface
Sitebeheerders zien in de bovenbalk één tab Beheer. Daaronder staan de subtabs Gebruikers, Runner en Opslag. Anderen zien de tab niet, en de pagina's geven hun 403. De oude adressen /setup en /admin/runner blijven werken. /admin stuurt door naar /admin/users.
- Gebruikers: een gebruiker beheerder maken of die rol afnemen, telkens na een eigen bevestigingsvenster. Je eigen knop is uitgeschakeld, en de server weigert het ook. Er blijft altijd minstens één beheerder over. Elke wijziging komt als regel
admin auditin de journal. - Taal: rechtsboven zit een vlaggetje voor NL/EN/DE/FR. Ingelogd wordt de keuze bij je account bewaard, anders in een cookie.
- Bevestigingen gebruiken nooit browserpopups (
alert,confirm,prompt), maar een eigen venster in de huisstijl. De testTestNoBrowserPopupslaat CI falen bij nieuwe popups. - Tooltips: het (i)-icoon bij een instelling geeft uitleg bij hover, bij focus en bij tikken.
Releases publiek bij een privé repo
Zet in de instellingen van de repo Zichtbaarheid releases op Publiek. Iedereen kan dan de Releases-pagina zien en de assets downloaden, ook zonder login. De code, de bron-archieven, de pipelines en de rest blijven alleen voor leden. In het overzicht op de startpagina staan zulke repo's onder "Publieke releases", met alleen hun naam en de eerste regel van de beschrijving. Details staan in agents.md.
Source
| 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). |
| 51 | |
| 52 | ## Beheer in de webinterface |
| 53 | |
| 54 | Sitebeheerders zien in de bovenbalk één tab **Beheer**. Daaronder staan de subtabs Gebruikers, Runner en Opslag. Anderen zien de tab niet, en de pagina's geven hun 403. De oude adressen `/setup` en `/admin/runner` blijven werken. `/admin` stuurt door naar `/admin/users`. |
| 55 | |
| 56 | - **Gebruikers**: een gebruiker beheerder maken of die rol afnemen, telkens na een eigen bevestigingsvenster. Je eigen knop is uitgeschakeld, en de server weigert het ook. Er blijft altijd minstens één beheerder over. Elke wijziging komt als regel `admin audit` in de journal. |
| 57 | - **Taal**: rechtsboven zit een vlaggetje voor NL/EN/DE/FR. Ingelogd wordt de keuze bij je account bewaard, anders in een cookie. |
| 58 | - **Bevestigingen** gebruiken nooit browserpopups (`alert`, `confirm`, `prompt`), maar een eigen venster in de huisstijl. De test `TestNoBrowserPopups` laat CI falen bij nieuwe popups. |
| 59 | - **Tooltips**: het (i)-icoon bij een instelling geeft uitleg bij hover, bij focus en bij tikken. |
| 60 | |
| 61 | ## Releases publiek bij een privé repo |
| 62 | |
| 63 | Zet in de instellingen van de repo **Zichtbaarheid releases** op *Publiek*. Iedereen kan dan de Releases-pagina zien en de assets downloaden, ook zonder login. De code, de bron-archieven, de pipelines en de rest blijven alleen voor leden. In het overzicht op de startpagina staan zulke repo's onder "Publieke releases", met alleen hun naam en de eerste regel van de beschrijving. Details staan in [agents.md](agents.md#zichtbaarheid-van-releases). |