BlueGit

timfa bluegit

Files

bluegit / README.md

README.md

README.md 16.7 KiB Download Raw

BlueGit

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.

Er is geen lokaal wachtwoord. Aanmelden gaat via de OAuth-flow van auth.timfalken.com (auth.mode: oauth, de standaard) of via Microsoft Entra ID (auth.mode: entra, één tenant). Zie docs/AUTH.md.

Het logo is de blauwe ster: assets/logo.svg.

BlueGit

Wat het doet

  • Repositories van een gebruiker of een groep, met bestanden, commits, branches, tags en releases.
  • Op de project-overzichtspagina staat een commitgrafiek rechts van de centrale kolom, als er plek is. De centrale kolom schuift daardoor iets naar links; op brede schermen vult de grafiek alle ruimte rechts van de kolom tot aan de rand. Elke commit staat op één regel; de lijnen lopen in verticale lanes met afgeronde 90-graden bochten, en de avatar is de commitknoop. De tekst begint in één kolom, rechts van de meest rechtse lane. Elke avatar staat in de SVG op de lane van die commit (niet via inline CSS: de CSP staat geen style-attributen toe). De grafiek wordt niet verkleind en heeft geen eigen scrollbar; als hij onderaan het scherm stopt, vagen de lijnen naar transparant weg. Te lange committekst vervaagt naar transparant (geen ellipsis) en toont bij hover het volledige bericht via een native title. Past de volle grafiek (met tekstkolom) niet, dan verschijnt een smalle modus: dezelfde lanes, avatars en labels, maar zonder committekst; hover op een commit toont het bericht via de native SVG-title. In die modus valt van een branchnaam alles t/m de laatste '/' weg (de volledige naam blijft in title). Elke commitknoop heeft een dunne omlijning in de lanekleur; de gekozen branch houdt een dikkere gloed. Alleen als ook de smalle modus niet past, zoals op mobiel, blijft de grafiek verborgen. Wordt de centrale kolom te smal (sidebar plus smalle grafiek, rond 1024–1280px), dan schuift Project information onder de inhoud; de laatste-commit-balk wrapt, de branchrij blijft op één regel en de bestandstabel toont alle drie de kolommen met ellipsis. Op een brede kolom (zoals 1920px) blijft de twee-koloms lay-out. De lijn van de in de dropdown gekozen branch gloeit. De hoofdbranch gebruikt de BlueGit-blauw; andere branches krijgen een vaste kleur uit hun naam. De grafiek wordt in het geheugen bewaard (LRU) en bij een push ververst, zodat herhaald laden geen git-I/O op schijf doet.
  • Markdown (README's, .md-bestanden, issues, merge requests, opmerkingen) toont afbeeldingen inline: ![alt](pad) met een relatief pad wordt een /-/raw/-adres op dezelfde ref (ook vanuit een submap, ../ kan niet boven de repo-root uit, een leidende / is de repo-root), absolute https://-adressen, HTML <img src alt width height title> en een los https://-adres naar een .png/.jpg/.jpeg/.gif/.webp/.svg/.avif. Een .svg is altijd een <img> met &as=img (geen inline SVG, scripts draaien niet). Andere HTML blijft geëscaped; alleen <a href> (http/https/mailto), <br> en omhulsels als <p align="center"> worden herschreven of weggelaten. javascript:-, data:- en http:-afbeeldingen worden niet geladen; links met een ander schema dan http/https/mailto worden #. De CSP staat img-src 'self' https: data: toe; afbeeldingen krijgen referrerpolicy="no-referrer" en loading="lazy". Een README in een submap staat onder de bestandslijst van die map; een .md-bestand wordt gerenderd, met de bron in een uitklapblok. Afbeeldingen zijn nooit breder dan de kolom (max-width: min(100%, 100cqw), height: auto); in een tabel maximaal 32rem of de kolombreedte, en een brede tabel scrolt binnen haar eigen vak.
  • Merge requests met reviews, squash en het verwijderen van de bronbranch na een merge.
  • 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.
  • In de projectzijbalk staat naast Merge requests en Issues een rond tellertje met het aantal open items. Bij 0 blijft het bolletje weg; vanaf 100 staat er 99+. Vertrouwelijke issues tellen alleen mee als je ze ook in de lijst ziet. De zichtbare teller is verborgen voor hulptechnologie; de link krijgt een aria-label zoals “1 open merge request”.
  • 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. CI kan per project worden gepauzeerd (instellingen of ci_paused op PUT /api/v1/projects/{owner}/{repo}): er worden dan geen nieuwe pipelines in de wachtrij gezet; jobs die al lopen of wachten, lopen wel af.
  • Jobs die je niet halverwege wilt stoppen (FTP-upload, databasemigratie) markeer je met doNotInterrupt: true: BlueGit stopt ze nooit automatisch, een nieuwere pipeline op dezelfde ref wacht erop, en handmatig stoppen vraagt om bevestiging. Zie docs/CI.md.
  • Webhooks op een repository of een groep, met presets, een eigen body en een overzicht van de laatste afleveringen.
  • Geheimen als omgevingsvariabelen in een job. Een beschermd geheim gaat alleen mee op een beschermde branch of een tag die op een beschermd tagpatroon past.
  • Groepen, met eigen leden, geheimen en webhooks.
  • Git over SSH en over HTTPS.
  • Periodiek onderhoud van de bare repositories (git gc --auto, plus git maintenance voor loose objects en incremental-repack als de git-binary dat kent). Standaard elke 24 uur (git.maintenance_interval; off of 0 zet het uit). Eén repo tegelijk, met lage prioriteit (nice -n 19) en gits eigen locking, nooit --prune=now. Een fout op één repo slaat die over. Installatiebeheerders zien de status en kunnen een ronde starten via GET/POST /api/v1/admin/git-maintenance.
  • REST-API. Het schema staat op /api/v1/openapi.json.
  • Self-update: de instantie installeert een nieuw AUR-pakket met pacman.
  • Een of meer losse backup servers (bluegit-backup, ook in deze repository, zie docs/BACKUP-SERVER.md) onder Beheer > Backup: per server een Backupserver-Key, een melding na elke wijziging, de archieflijst, een rollback met waarschuwing en de bediening en instellingen van de backup server zelf. Past een backup server niet bij deze BlueGit (een van de twee is verouderd), dan zien beheerders bovenaan elke pagina een waarschuwing. Zie docs/BACKUP.md.
  • Linkpreviews: een gedeelde pagina krijgt een kaart via Open Graph, oEmbed en /-/card.png.

Een repository hoort bij een gebruiker of bij een groep. De hoogste rol telt.

RolLezenSchrijven op een gewone branchBeschermde branchGeheimen, webhooks, leden, verwijderen
Alleen lezenjaneeneenee
Ontwikkelaarjajaneenee
Beheerderjajajaja

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.

Installeren

Op Arch installeer je het AUR-pakket bluegit. De configuratie staat in /etc/bluegit/config.yml. De systemd-service heet bluegit.service.

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.

Op andere distro's gebruik je de pakketten van de releasepagina. Elke release (tag v*) heeft voor bluegit, bluegit-runner en bluegit-backup:

  • losse binaries voor linux amd64 en arm64 (bluegit-linux-amd64, …);
  • Windows-zips voor amd64 en arm64 (bluegit-windows-amd64.zip, …), elk met de .exe;
  • .deb voor Ubuntu Server en Debian (apt install ./bluegit_amd64.deb);
  • .rpm voor RHEL, Rocky, Alma en Fedora (dnf install ./bluegit.x86_64.rpm);
  • .pkg.tar.zst voor Arch (pacman -U bluegit-x86_64.pkg.tar.zst);
  • SHA256SUMS over alle bestanden.

De pakketten installeren de systemd-unit, de gebruiker (bluegit, bluegit-runner, bluegit-backup) en de config onder /etc/<naam>/, net als de AUR-pakketten. Ze zetten de service niet aan. De self-update (bluegit-update) zit alleen in het AUR-pakket. <programma> --version toont de tag. De CI test elk pakket in ubuntu:24.04, debian:12, rockylinux:9, fedora en archlinux voordat er een release komt.

Hoe het AUR-pakket gepubliceerd wordt en hoe de self-update via pacman werkt, staat in docs/AUR.md. De stappen voor de installatie op git.timfalken.com staan in docs/BEHEER.md.

Windows

Elke release (vanaf de eerstvolgende tag na deze wijziging) bevat zips voor Windows amd64 en arm64: bluegit-windows-amd64.zip, bluegit-runner-windows-amd64.zip en bluegit-backup-windows-amd64.zip (zelfde namen met arm64). Pak de zip uit en zet de .exe in een map die in je PATH staat, of roep hem met het volle pad aan. Er is geen installer, geen Windows-service en geen self-update.

Je hebt Git for Windows nodig (voor git en de pre-receive-hook, die een #!/bin/sh-script is). Voor de runner heb je daarnaast Docker Desktop nodig, met de Linux-engine: CI-jobs draaien nog steeds in Linux-containers (sh, /workspace).

Zonder --config zoekt bluegit.exe eerst naar BLUEGIT_CONFIG, daarna naar bluegit.yml in de werkmap, en anders naar %LOCALAPPDATA%\BlueGit\config.yml. De standaard-state_path is %LOCALAPPDATA%\BlueGit. Voor de runner is dat %LOCALAPPDATA%\BlueGit-runner (config en work_dir), voor de backup server %LOCALAPPDATA%\BlueGit-backup. storage_path blijft leeg tot je in /setup een bestaand, beschrijfbaar, absoluut pad kiest met minstens 1 GiB vrij.

Een minimaal voorbeeld, op te slaan als bluegit.yml in de werkmap of als %LOCALAPPDATA%\BlueGit\config.yml:

base_url: http://127.0.0.1:8080
listen: 127.0.0.1:8080
auth:
  mode: dev
  dev_user: tim
ssh:
  enabled: false
ci:
  enabled: false
bluegit.exe serve --config bluegit.yml

storage_path laat je weg; na het aanmelden vraag BlueGit om het datapad. Een toegangstoken maak je onder Account. Open SSH (ssh.enabled) alleen als je de poort zelf bereikbaar maakt; er is geen ingress-handleiding voor Windows.

Bekende beperkingen

  • Unix-bestandsrechten (0600, 0750) worden op NTFS niet afgedwongen. Beperk de toegang tot de state- en datamap via de maprechten van Windows.
  • Er is geen systemd, geen AUR-pakket en geen self-update. Updaten is: nieuwe zip downloaden en de .exe vervangen.
  • Na het terugzetten van een backup start BlueGit een nieuw proces; de PID verandert (op Linux blijft die gelijk).
  • De runner is bedoeld voor Docker Desktop met Linux-containers. Functies die systemd of een Linux-host veronderstellen (de unit inschakelen na register als root) doen op Windows niets.
  • De officiële installatie en de pakketten (deb, rpm, Arch, AUR) blijven Linux. De Windows-binaries zijn een extra om BlueGit, de runner of de backup server zonder Linux-host te draaien.

Zie ook docs/ASSUMPTIONS.md.

Microsoft Entra ID

Details en de OIDC-controles staan in docs/AUTH.md. Kort, stap voor stap:

1. Open het Microsoft Entra-beheercentrum → Identiteit → Toepassingen → App-registraties → Nieuwe registratie. 2. Kies één tenant (Accounts in this organizational directory only / single tenant). 3. Platform: Web. De redirect-URI moet exact {base_url}{auth.redirect_path} zijn, het pad dat BlueGit verwacht. auth.redirect_path is standaard /auth/callback, dus bijvoorbeeld https://git.timfalken.com/auth/callback. Een ander pad, schema (http vs https) of een slash te veel of te weinig geeft een redirect-mismatch. 4. Maak onder Certificates & secrets een client secret aan. Noteer de waarde (die is maar één keer zichtbaar) en de verloopdatum; na verlopen stopt aanmelden. 5. BlueGit vraagt de scopes openid, profile, email en User.Read. De eerste drie horen bij OpenID Connect. User.Read is nodig om bij het aanmelden de profielfoto op te halen bij Microsoft Graph (GET https://graph.microsoft.com/v1.0/me/photo/$value). Voeg Microsoft Graph → User.Read (gedelegeerd) toe onder API-machtigingen van de app-registratie en geef desnoods admin-toestemming. Zonder foto (404) toont BlueGit initialen; een handmatig geüploade avatar wordt niet overschreven. 6. Op het overzicht van de app-registratie staan de Directory (tenant) ID (auth.tenant_id) en de Application (client) ID (auth.client_id).

Zet in /etc/bluegit/config.yml (geen echte geheimen in dit bestand of in deze docs):

auth:
  mode: entra
  tenant_id:     # Directory (tenant) ID
  client_id:     # Application (client) ID
  client_secret_file: /etc/bluegit/client_secret
  redirect_path: /auth/callback
  # issuer alleen voor een andere cloud of een test; leeg =
  # https://login.microsoftonline.com/{tenant_id}/v2.0

Het clientgeheim zet je niet in de yaml als het vermijdbaar is. Alternatieven met exacte namen uit de code: auth.client_secret, auth.client_secret_file (bijvoorbeeld /etc/bluegit/client_secret, mode 0600) of de omgevingsvariabele BLUEGIT_AUTH_CLIENT_SECRET (bijvoorbeeld in /etc/bluegit/secret.env). auth.base_url hoort bij mode: oauth, niet bij entra.

Herstart daarna de service (systemctl restart bluegit). De bestaande knop Aanmelden (in de navigatie, naar /login) start de Entra-flow; er is geen aparte knop. Zonder auth.mode: entra blijft die knop naar auth.timfalken.com gaan.

Accountkoppeling. De BlueGit-gebruiker hangt aan tid + oid uit het ID-token (stabiele auth_id). Dezelfde Entra-gebruiker komt terug op het bestaande account. Een nieuwe login waarvan de afgeleide gebruikersnaam al door een ander account bezet is, wordt geweigerd; er is geen overname via e-mail.

Veelvoorkomende fouten

  • De redirect-URI komt niet exact overeen (pad, schema, host, slash) → redirect mismatch (vaak AADSTS50011).
  • Verlopen client secret → de token-exchange faalt; maak een nieuw geheim, werk auth.client_secret_file of BLUEGIT_AUTH_CLIENT_SECRET bij, en herstart.
  • Verkeerde tenant: auth.tenant_id hoort bij een andere directory, of tid in het token komt niet overeen → aanmelden wordt geweigerd.

Lokaal

auth.mode: dev maakt een sessie zonder de auth-server. De configuratie weigert die modus zodra base_url op git.timfalken.com wijst.

base_url: http://127.0.0.1:8080
listen: 127.0.0.1:8080
auth:
  mode: dev
  dev_user: tim
ssh:
  enabled: false
ci:
  enabled: false
go build -o bluegit ./cmd/bluegit
./bluegit serve --config bluegit.yml

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.

Een toegangstoken maak je onder Account. Git gebruikt dat token als wachtwoord:

git clone http://tim:bg_…@127.0.0.1:8080/tim/demo.git

Documentatie

Tests

go test ./...

Licentie

MIT. Zie LICENSE.

Source
1# BlueGit
2
3BlueGit 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
5Er is geen lokaal wachtwoord. Aanmelden gaat via de OAuth-flow van [auth.timfalken.com](https://auth.timfalken.com) (`auth.mode: oauth`, de standaard) of via Microsoft Entra ID (`auth.mode: entra`, één tenant). Zie [docs/AUTH.md](docs/AUTH.md).
6
7Het logo is de blauwe ster: [`assets/logo.svg`](assets/logo.svg).
8
9![BlueGit](assets/logo.svg)
10
11## Wat het doet
12
13- Repositories van een gebruiker of een groep, met bestanden, commits, branches, tags en releases.
14- Op de project-overzichtspagina staat een commitgrafiek rechts van de centrale kolom, als er plek is. De centrale kolom schuift daardoor iets naar links; op brede schermen vult de grafiek alle ruimte rechts van de kolom tot aan de rand. Elke commit staat op één regel; de lijnen lopen in verticale lanes met afgeronde 90-graden bochten, en de avatar is de commitknoop. De tekst begint in één kolom, rechts van de meest rechtse lane. Elke avatar staat in de SVG op de lane van die commit (niet via inline CSS: de CSP staat geen style-attributen toe). De grafiek wordt niet verkleind en heeft geen eigen scrollbar; als hij onderaan het scherm stopt, vagen de lijnen naar transparant weg. Te lange committekst vervaagt naar transparant (geen ellipsis) en toont bij hover het volledige bericht via een native title. Past de volle grafiek (met tekstkolom) niet, dan verschijnt een smalle modus: dezelfde lanes, avatars en labels, maar zonder committekst; hover op een commit toont het bericht via de native SVG-title. In die modus valt van een branchnaam alles t/m de laatste '/' weg (de volledige naam blijft in title). Elke commitknoop heeft een dunne omlijning in de lanekleur; de gekozen branch houdt een dikkere gloed. Alleen als ook de smalle modus niet past, zoals op mobiel, blijft de grafiek verborgen. Wordt de centrale kolom te smal (sidebar plus smalle grafiek, rond 1024–1280px), dan schuift Project information onder de inhoud; de laatste-commit-balk wrapt, de branchrij blijft op één regel en de bestandstabel toont alle drie de kolommen met ellipsis. Op een brede kolom (zoals 1920px) blijft de twee-koloms lay-out. De lijn van de in de dropdown gekozen branch gloeit. De hoofdbranch gebruikt de BlueGit-blauw; andere branches krijgen een vaste kleur uit hun naam. De grafiek wordt in het geheugen bewaard (LRU) en bij een push ververst, zodat herhaald laden geen git-I/O op schijf doet.
15- Markdown (README's, `.md`-bestanden, issues, merge requests, opmerkingen) toont afbeeldingen inline: `![alt](pad)` met een relatief pad wordt een `/-/raw/`-adres op dezelfde ref (ook vanuit een submap, `../` kan niet boven de repo-root uit, een leidende `/` is de repo-root), absolute `https://`-adressen, HTML `<img src alt width height title>` en een los `https://`-adres naar een `.png/.jpg/.jpeg/.gif/.webp/.svg/.avif`. Een `.svg` is altijd een `<img>` met `&as=img` (geen inline SVG, scripts draaien niet). Andere HTML blijft geëscaped; alleen `<a href>` (http/https/mailto), `<br>` en omhulsels als `<p align="center">` worden herschreven of weggelaten. `javascript:`-, `data:`- en `http:`-afbeeldingen worden niet geladen; links met een ander schema dan http/https/mailto worden `#`. De CSP staat `img-src 'self' https: data:` toe; afbeeldingen krijgen `referrerpolicy="no-referrer"` en `loading="lazy"`. Een README in een submap staat onder de bestandslijst van die map; een `.md`-bestand wordt gerenderd, met de bron in een uitklapblok. Afbeeldingen zijn nooit breder dan de kolom (`max-width: min(100%, 100cqw)`, `height: auto`); in een tabel maximaal 32rem of de kolombreedte, en een brede tabel scrolt binnen haar eigen vak.
16- Merge requests met reviews, squash en het verwijderen van de bronbranch na een merge.
17- 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.
18- In de projectzijbalk staat naast Merge requests en Issues een rond tellertje met het aantal open items. Bij 0 blijft het bolletje weg; vanaf 100 staat er 99+. Vertrouwelijke issues tellen alleen mee als je ze ook in de lijst ziet. De zichtbare teller is verborgen voor hulptechnologie; de link krijgt een aria-label zoals “1 open merge request”.
19- 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. CI kan per project worden gepauzeerd (instellingen of `ci_paused` op `PUT /api/v1/projects/{owner}/{repo}`): er worden dan geen nieuwe pipelines in de wachtrij gezet; jobs die al lopen of wachten, lopen wel af.
20- Jobs die je niet halverwege wilt stoppen (FTP-upload, databasemigratie) markeer je met `doNotInterrupt: true`: BlueGit stopt ze nooit automatisch, een nieuwere pipeline op dezelfde ref wacht erop, en handmatig stoppen vraagt om bevestiging. Zie [docs/CI.md](docs/CI.md#donotinterrupt).
21- Webhooks op een repository of een groep, met presets, een eigen body en een overzicht van de laatste afleveringen.
22- Geheimen als omgevingsvariabelen in een job. Een beschermd geheim gaat alleen mee op een beschermde branch of een tag die op een beschermd tagpatroon past.
23- Groepen, met eigen leden, geheimen en webhooks.
24- Git over SSH en over HTTPS.
25- Periodiek onderhoud van de bare repositories (`git gc --auto`, plus `git maintenance` voor loose objects en incremental-repack als de git-binary dat kent). Standaard elke 24 uur (`git.maintenance_interval`; `off` of `0` zet het uit). Eén repo tegelijk, met lage prioriteit (`nice -n 19`) en gits eigen locking, nooit `--prune=now`. Een fout op één repo slaat die over. Installatiebeheerders zien de status en kunnen een ronde starten via `GET`/`POST /api/v1/admin/git-maintenance`.
26- REST-API. Het schema staat op `/api/v1/openapi.json`.
27- Self-update: de instantie installeert een nieuw AUR-pakket met pacman.
28- Een of meer losse backup servers (`bluegit-backup`, ook in deze repository, zie [docs/BACKUP-SERVER.md](docs/BACKUP-SERVER.md)) onder Beheer > Backup: per server een Backupserver-Key, een melding na elke wijziging, de archieflijst, een rollback met waarschuwing en de bediening en instellingen van de backup server zelf. Past een backup server niet bij deze BlueGit (een van de twee is verouderd), dan zien beheerders bovenaan elke pagina een waarschuwing. Zie [docs/BACKUP.md](docs/BACKUP.md).
29- Linkpreviews: een gedeelde pagina krijgt een kaart via Open Graph, oEmbed en `/-/card.png`.
30
31Een repository hoort bij een gebruiker of bij een groep. De hoogste rol telt.
32
33| Rol | Lezen | Schrijven op een gewone branch | Beschermde branch | Geheimen, webhooks, leden, verwijderen |
34| --- | --- | --- | --- | --- |
35| Alleen lezen | ja | nee | nee | nee |
36| Ontwikkelaar | ja | ja | nee | nee |
37| Beheerder | ja | ja | ja | ja |
38
39De 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.
40
41## Installeren
42
43Op Arch installeer je het AUR-pakket `bluegit`. De configuratie staat in `/etc/bluegit/config.yml`. De systemd-service heet `bluegit.service`.
44
45`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.
46
47Op andere distro's gebruik je de pakketten van de [releasepagina](https://git.timfalken.com/timfa/bluegit/-/releases). Elke release (tag `v*`) heeft voor `bluegit`, `bluegit-runner` en `bluegit-backup`:
48
49- losse binaries voor linux amd64 en arm64 (`bluegit-linux-amd64`, …);
50- Windows-zips voor amd64 en arm64 (`bluegit-windows-amd64.zip`, …), elk met de `.exe`;
51- `.deb` voor Ubuntu Server en Debian (`apt install ./bluegit_amd64.deb`);
52- `.rpm` voor RHEL, Rocky, Alma en Fedora (`dnf install ./bluegit.x86_64.rpm`);
53- `.pkg.tar.zst` voor Arch (`pacman -U bluegit-x86_64.pkg.tar.zst`);
54- `SHA256SUMS` over alle bestanden.
55
56De pakketten installeren de systemd-unit, de gebruiker (`bluegit`, `bluegit-runner`, `bluegit-backup`) en de config onder `/etc/<naam>/`, net als de AUR-pakketten. Ze zetten de service niet aan. De self-update (bluegit-update) zit alleen in het AUR-pakket. `<programma> --version` toont de tag. De CI test elk pakket in ubuntu:24.04, debian:12, rockylinux:9, fedora en archlinux voordat er een release komt.
57
58Hoe het AUR-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).
59
60
61## Windows
62
63Elke release (vanaf de eerstvolgende tag na deze wijziging) bevat zips voor Windows amd64 en arm64: `bluegit-windows-amd64.zip`, `bluegit-runner-windows-amd64.zip` en `bluegit-backup-windows-amd64.zip` (zelfde namen met `arm64`). Pak de zip uit en zet de `.exe` in een map die in je `PATH` staat, of roep hem met het volle pad aan. Er is geen installer, geen Windows-service en geen self-update.
64
65Je hebt [Git for Windows](https://gitforwindows.org/) nodig (voor `git` en de `pre-receive`-hook, die een `#!/bin/sh`-script is). Voor de runner heb je daarnaast Docker Desktop nodig, met de Linux-engine: CI-jobs draaien nog steeds in Linux-containers (`sh`, `/workspace`).
66
67Zonder `--config` zoekt `bluegit.exe` eerst naar `BLUEGIT_CONFIG`, daarna naar `bluegit.yml` in de werkmap, en anders naar `%LOCALAPPDATA%\BlueGit\config.yml`. De standaard-`state_path` is `%LOCALAPPDATA%\BlueGit`. Voor de runner is dat `%LOCALAPPDATA%\BlueGit-runner` (config en `work_dir`), voor de backup server `%LOCALAPPDATA%\BlueGit-backup`. `storage_path` blijft leeg tot je in `/setup` een bestaand, beschrijfbaar, absoluut pad kiest met minstens 1 GiB vrij.
68
69Een minimaal voorbeeld, op te slaan als `bluegit.yml` in de werkmap of als `%LOCALAPPDATA%\BlueGit\config.yml`:
70
71```yaml
72base_url: http://127.0.0.1:8080
73listen: 127.0.0.1:8080
74auth:
75 mode: dev
76 dev_user: tim
77ssh:
78 enabled: false
79ci:
80 enabled: false
81```
82
83```powershell
84bluegit.exe serve --config bluegit.yml
85```
86
87`storage_path` laat je weg; na het aanmelden vraag BlueGit om het datapad. Een toegangstoken maak je onder Account. Open SSH (`ssh.enabled`) alleen als je de poort zelf bereikbaar maakt; er is geen ingress-handleiding voor Windows.
88
89**Bekende beperkingen**
90
91- Unix-bestandsrechten (`0600`, `0750`) worden op NTFS niet afgedwongen. Beperk de toegang tot de state- en datamap via de maprechten van Windows.
92- Er is geen systemd, geen AUR-pakket en geen self-update. Updaten is: nieuwe zip downloaden en de `.exe` vervangen.
93- Na het terugzetten van een backup start BlueGit een nieuw proces; de PID verandert (op Linux blijft die gelijk).
94- De runner is bedoeld voor Docker Desktop met Linux-containers. Functies die systemd of een Linux-host veronderstellen (de unit inschakelen na `register` als root) doen op Windows niets.
95- De officiële installatie en de pakketten (deb, rpm, Arch, AUR) blijven Linux. De Windows-binaries zijn een extra om BlueGit, de runner of de backup server zonder Linux-host te draaien.
96
97Zie ook [docs/ASSUMPTIONS.md](docs/ASSUMPTIONS.md).
98
99## Microsoft Entra ID
100
101Details en de OIDC-controles staan in [docs/AUTH.md](docs/AUTH.md). Kort, stap voor stap:
102
1031. Open het [Microsoft Entra-beheercentrum](https://entra.microsoft.com) → Identiteit → Toepassingen → App-registraties → Nieuwe registratie.
1042. Kies één tenant (*Accounts in this organizational directory only* / single tenant).
1053. Platform: **Web**. De redirect-URI moet exact `{base_url}{auth.redirect_path}` zijn, het pad dat BlueGit verwacht. `auth.redirect_path` is standaard `/auth/callback`, dus bijvoorbeeld `https://git.timfalken.com/auth/callback`. Een ander pad, schema (`http` vs `https`) of een slash te veel of te weinig geeft een redirect-mismatch.
1064. Maak onder *Certificates & secrets* een client secret aan. Noteer de waarde (die is maar één keer zichtbaar) en de verloopdatum; na verlopen stopt aanmelden.
1075. BlueGit vraagt de scopes `openid`, `profile`, `email` en `User.Read`. De eerste drie horen bij OpenID Connect. `User.Read` is nodig om bij het aanmelden de profielfoto op te halen bij Microsoft Graph (`GET https://graph.microsoft.com/v1.0/me/photo/$value`). Voeg *Microsoft Graph → User.Read* (gedelegeerd) toe onder API-machtigingen van de app-registratie en geef desnoods admin-toestemming. Zonder foto (404) toont BlueGit initialen; een handmatig geüploade avatar wordt niet overschreven.
1086. Op het overzicht van de app-registratie staan de **Directory (tenant) ID** (`auth.tenant_id`) en de **Application (client) ID** (`auth.client_id`).
109
110Zet in `/etc/bluegit/config.yml` (geen echte geheimen in dit bestand of in deze docs):
111
112```yaml
113auth:
114 mode: entra
115 tenant_id: # Directory (tenant) ID
116 client_id: # Application (client) ID
117 client_secret_file: /etc/bluegit/client_secret
118 redirect_path: /auth/callback
119 # issuer alleen voor een andere cloud of een test; leeg =
120 # https://login.microsoftonline.com/{tenant_id}/v2.0
121```
122
123Het clientgeheim zet je niet in de yaml als het vermijdbaar is. Alternatieven met exacte namen uit de code: `auth.client_secret`, `auth.client_secret_file` (bijvoorbeeld `/etc/bluegit/client_secret`, mode `0600`) of de omgevingsvariabele `BLUEGIT_AUTH_CLIENT_SECRET` (bijvoorbeeld in `/etc/bluegit/secret.env`). `auth.base_url` hoort bij `mode: oauth`, niet bij entra.
124
125Herstart daarna de service (`systemctl restart bluegit`). De bestaande knop **Aanmelden** (in de navigatie, naar `/login`) start de Entra-flow; er is geen aparte knop. Zonder `auth.mode: entra` blijft die knop naar auth.timfalken.com gaan.
126
127**Accountkoppeling.** De BlueGit-gebruiker hangt aan `tid` + `oid` uit het ID-token (stabiele `auth_id`). Dezelfde Entra-gebruiker komt terug op het bestaande account. Een nieuwe login waarvan de afgeleide gebruikersnaam al door een ander account bezet is, wordt geweigerd; er is geen overname via e-mail.
128
129**Veelvoorkomende fouten**
130
131- De redirect-URI komt niet exact overeen (pad, schema, host, slash) → redirect mismatch (vaak AADSTS50011).
132- Verlopen client secret → de token-exchange faalt; maak een nieuw geheim, werk `auth.client_secret_file` of `BLUEGIT_AUTH_CLIENT_SECRET` bij, en herstart.
133- Verkeerde tenant: `auth.tenant_id` hoort bij een andere directory, of `tid` in het token komt niet overeen → aanmelden wordt geweigerd.
134
135## Lokaal
136
137`auth.mode: dev` maakt een sessie zonder de auth-server. De configuratie weigert die modus zodra `base_url` op `git.timfalken.com` wijst.
138
139```yaml
140base_url: http://127.0.0.1:8080
141listen: 127.0.0.1:8080
142auth:
143 mode: dev
144 dev_user: tim
145ssh:
146 enabled: false
147ci:
148 enabled: false
149```
150
151```shell
152go build -o bluegit ./cmd/bluegit
153./bluegit serve --config bluegit.yml
154```
155
156Laat `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.
157
158Een toegangstoken maak je onder Account. Git gebruikt dat token als wachtwoord:
159
160```shell
161git clone http://tim:bg_…@127.0.0.1:8080/tim/demo.git
162```
163
164## Documentatie
165
166- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) beschrijft het proces, de schijf en waarom het één binary is.
167- [docs/AUTH.md](docs/AUTH.md) beschrijft de OAuth-koppeling en Microsoft Entra ID.
168- [docs/INGRESS.md](docs/INGRESS.md) beschrijft TLS, de publieke SSH-poort, en hoe Apache encoded slashes (`%2F`) doorlaat.
169- [docs/CI.md](docs/CI.md) beschrijft `blue-ci-cd.yml` en Steve.
170- [docs/AUR.md](docs/AUR.md) beschrijft het pakket en de self-update.
171- [docs/BEHEER.md](docs/BEHEER.md) beschrijft de installatie op git.timfalken.com.
172- [docs/BACKUP.md](docs/BACKUP.md) beschrijft de koppeling met losse backup servers (bluegit-backup): Backupserver-Keys, meldingen, archieven, rollback en bediening vanuit BlueGit.
173- [docs/BACKUP-SERVER.md](docs/BACKUP-SERVER.md) beschrijft de backup server zelf, [docs/BACKUP-PROTOCOL.md](docs/BACKUP-PROTOCOL.md) het protocol.
174- [docs/ASSUMPTIONS.md](docs/ASSUMPTIONS.md) bevat de aannames.
175- [docs/MIGRATIE.md](docs/MIGRATIE.md) beschrijft de overstap van de user-unit naar de system-service.
176- [docs/ROADMAP.md](docs/ROADMAP.md) en [docs/VRAGEN.md](docs/VRAGEN.md) houden bij wat nog openstaat en welke besluiten al vastliggen.
177
178## Tests
179
180```shell
181go test ./...
182```
183
184## Licentie
185
186MIT. Zie [LICENSE](LICENSE).