# 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](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](https://auth.timfalken.com).

## Eerste installatie

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).

```shell
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](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. De ingebouwde SSH-server biedt eerst de post-quantum sleuteluitwisseling `mlkem768x25519-sha256` aan, daarna `curve25519-sha256` voor oudere clients; OpenSSH 10.1+ toont dan geen post-quantum-waarschuwing. De hostkey verandert daar niet door.

## 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 (of een tag op een beschermd tagpatroon, bijvoorbeeld `v*` voor releases) 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](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`](../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](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 audit` in 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 test `TestNoBrowserPopups` laat 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](agents.md#zichtbaarheid-van-releases).

## Backup

Losse backup servers (bluegit-backup) voeg je toe onder **Beheer > Backup**, elk met een eigen Backupserver-Key. Per server staan daar de status, de instellingen, de archieven en de rollback. Zie [BACKUP.md](BACKUP.md).
