258 lines
12 KiB
Markdown
258 lines
12 KiB
Markdown
# Gitea build pipeline beheren
|
|
|
|
De workflow staat in `.gitea/workflows/build.yaml`. Elke branchpush bouwt en test
|
|
backend en frontend, bouwt twee images en draait Playwright tegen die containers.
|
|
Alleen `main` mag daarna images publiceren. Er vindt geen deployment plaats.
|
|
Tagpushes en aparte pull-requestevents starten geen extra workflow.
|
|
|
|
## Java-bronbestanden uitvoeren
|
|
|
|
De CI- en setuphulpmiddelen zijn Java 25-bronbestanden. Start ze direct met
|
|
`java ci/Ci.java <opdracht>` vanuit de repositoryroot. De Java-launcher compileert
|
|
de benodigde bronbestanden in het geheugen. Er is geen aparte `javac`-stap,
|
|
Maven-module, Python-installatie of scriptingframework nodig. De helper gebruikt
|
|
alleen de JDK, inclusief de HTTP-client, process builder en bestandsloten.
|
|
|
|
Beschikbare opdrachten: `verify`, `publish`, `cleanup`, `attempt`, `test`,
|
|
`configure-gitea`, `configure-docker <daemon.json>` en
|
|
`install-runner [--prepare-only]`. `verify` heeft een intern tijdsbudget van
|
|
75 minuten; `publish` 15 minuten. Opruimen krijgt een apart budget van 2 minuten.
|
|
|
|
Zorg dat `java` naar JDK 25 verwijst, bijvoorbeeld met:
|
|
|
|
```sh
|
|
export JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64
|
|
export PATH="$JAVA_HOME/bin:$PATH"
|
|
```
|
|
|
|
## Machines en voorwaarden
|
|
|
|
Gitea 1.25.4 en de registry staan op de bestaande Synology,
|
|
`http://192.168.2.28:3000`. De runner draait als gebruikersservice op de bestaande
|
|
Linux x86_64 mini-pc. Er is geen extra hardware nodig. De mini-pc moet aanstaan en
|
|
wakker blijven; Docker en de runner moeten draaien. Anders blijven jobs wachten.
|
|
Een host-runner voert repositorycode uit als de ontwikkelgebruiker: gebruik deze
|
|
runner alleen voor deze vertrouwde repository.
|
|
|
|
De runner heeft Git, Bash, JDK 25, Maven 3.9+, Node 22.22.3+/24.15.0+/26+, npm
|
|
en een werkende Docker-daemon
|
|
nodig. De huidige mini-pc heeft de ontwikkeltools en Docker Desktop al geïnstalleerd.
|
|
De workflow gebruikt één job tegelijk (`capacity: 1`), één Playwright-worker en
|
|
CPU/geheugenlimieten voor de tijdelijke applicatie- en browsercontainers.
|
|
|
|
### Doelarchitectuur eerst vaststellen
|
|
|
|
Controleer op de Synology via een bestaande beheerverbinding:
|
|
|
|
```sh
|
|
uname -m
|
|
docker info --format '{{.OSType}}/{{.Architecture}}'
|
|
```
|
|
|
|
`x86_64`/`amd64` betekent `linux/amd64`; `aarch64`/`arm64` betekent `linux/arm64`.
|
|
Leg de werkelijke uitvoer, datum en het Synology-model vast bij de oplevering en
|
|
stel repositoryvariabele `TARGET_PLATFORM` daarop in. De workflow weigert een
|
|
ontbrekende waarde en een verschil met de Docker-daemon van de runner; hij doet
|
|
dus geen stilzwijgende aanname over de NAS en gebruikt geen ongeteste emulatie.
|
|
Een mismatch vereist een geteste oplossing op de bestaande machines voordat S4
|
|
afgerond kan worden; er worden geen multi-architecture images gebouwd.
|
|
|
|
### Docker op de mini-pc
|
|
|
|
Start de al aanwezige Docker Desktop via de desktop of:
|
|
|
|
```sh
|
|
systemctl --user start docker-desktop
|
|
docker --context desktop-linux info
|
|
```
|
|
|
|
Bij Docker Desktop configureer je onder **Settings → Docker Engine** de inhoud
|
|
van `ci/runner/docker-daemon.json`, samengevoegd met bestaande instellingen.
|
|
Je kunt de instelling ook samenvoegen met behoud van bestaande instellingen en
|
|
backup via:
|
|
|
|
```sh
|
|
java ci/Ci.java configure-docker "$HOME/.docker/daemon.json"
|
|
```
|
|
|
|
Voor Docker Engine op Linux is dat dezelfde toevoeging aan
|
|
`/etc/docker/daemon.json` (met de daarvoor benodigde beheerrechten). Overschrijf geen andere daemoninstellingen. Pas de
|
|
wijziging toe/herstart de daemon en controleer met `docker info` dat
|
|
`192.168.2.28:3000` onder de insecure registries staat. Configureer ook andere
|
|
Docker-clients die images van deze interne HTTP-registry moeten ophalen.
|
|
|
|
Gebruik de Docker Desktop-context of zet `DOCKER_HOST` expliciet. De installer
|
|
neemt de geselecteerde socket over in de gebruikersservice. Als de socket later
|
|
wijzigt, pas dan `~/.config/agiledancers-runner/environment` aan en herstart de
|
|
runner. Bij Docker Desktop blijft de Desktop-VM eveneens nodig voor builds.
|
|
Runner en containers moeten de Synology en internetdownloads kunnen bereiken.
|
|
|
|
## Gitea-instellingen en credentials
|
|
|
|
Repository: `wanjakrah/agiledancers`, hoofdbranch: `main`.
|
|
Actions staat voor deze repository al aan. Controleer zo nodig op de Synology
|
|
`app.ini` onder `[actions]` de instelling `ENABLED = true` en de Actions-feature
|
|
onder repositoryinstellingen. Stel `SKIP_WORKFLOW_STRINGS` leeg in als ook commits met teksten als `[skip ci]`
|
|
verplicht moeten draaien, zoals de afspraak elke branchpush vereist.
|
|
Wijzig serverconfiguratie alleen indien nodig.
|
|
|
|
Stel bij repository **Settings → Actions** in:
|
|
|
|
| Soort | Naam | Waarde/doel |
|
|
| --- | --- | --- |
|
|
| Variabele | `TARGET_PLATFORM` | Vastgestelde Synology-platformwaarde |
|
|
| Secret | `REGISTRY_USER` | Gitea-gebruiker die in namespace `wanjakrah` mag publiceren |
|
|
| Secret | `REGISTRY_TOKEN` | PAT met `write:package` en `read:repository` voor imagepublicatie en controle van de huidige hoofdbranch |
|
|
|
|
Het gewone jobtoken van Gitea 1.25 biedt geen packagepublicatie; gebruik een PAT.
|
|
Gebruik een repository-runnerregistratietoken, geen instancebrede registratie.
|
|
Sla tokenwaarden buiten Git op en plaats ze niet in opdrachten, screenshots of logs.
|
|
|
|
Voor reproduceerbare configuratie bestaat `java ci/Ci.java configure-gitea`. Maak twee
|
|
bestanden buiten de repository met mode `600`: één voor een PAT met voldoende
|
|
repositorybeheerrechten (repository Actions, secrets, variabelen en runnerregistratie),
|
|
en één voor de publicatie-PAT. De beheer-PAT hoeft niet als workflowsecret te worden
|
|
bewaard. Vul die bestanden via een lokale editor of verborgen terminalinvoer.
|
|
Voer daarna uit met de werkelijke platformwaarde:
|
|
|
|
```sh
|
|
export GITEA_ADMIN_TOKEN_FILE="$HOME/.config/agiledancers-runner/admin-token"
|
|
export REGISTRY_TOKEN_FILE="$HOME/.config/agiledancers-runner/registry-token"
|
|
export REGISTRY_USER=wanjakrah
|
|
export TARGET_PLATFORM=linux/amd64 # alleen als dit op de Synology is vastgesteld
|
|
java ci/Ci.java configure-gitea
|
|
```
|
|
|
|
Het script stelt de repository-instellingen in via de API en schrijft het
|
|
runnerregistratietoken naar
|
|
`~/.config/agiledancers-runner/registration-token` met mode `600`. Het toont geen
|
|
tokenwaarden. Voor handmatige inrichting kun je dat registratietoken uit de
|
|
repository-instellingen halen en in hetzelfde bestand plaatsen.
|
|
|
|
Controleer de artifactretentie op de server: een workflow vraagt veertien dagen
|
|
via `retention-days: 14`. Een kortere serverlimiet of het vroegtijdig verwijderen
|
|
van workflowruns mag die periode niet inkorten. Artifactretentie geldt voor
|
|
testdiagnostiek; gepubliceerde containerimages worden niet automatisch verwijderd.
|
|
|
|
## Runner installeren en starten
|
|
|
|
```sh
|
|
export JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64
|
|
java ci/Ci.java install-runner --prepare-only
|
|
# Na Dockerconfiguratie en het opslaan van het registratietoken:
|
|
java ci/Ci.java install-runner
|
|
systemctl --user status agiledancers-runner
|
|
journalctl --user -u agiledancers-runner -f
|
|
```
|
|
|
|
De installer controleert tools, installeert checksum-gecontroleerde runner
|
|
`v0.2.13`, neemt label `agiledancers-mini-pc:host` over en registreert de runner.
|
|
Configuratie en `.runner`-credentials staan in
|
|
`~/.local/share/agiledancers-runner`, de service in
|
|
`~/.config/systemd/user/agiledancers-runner.service` en de expliciete Java-, PATH-
|
|
en Docker-socketinstellingen in `~/.config/agiledancers-runner/environment`.
|
|
Een bestaande registratie wordt hergebruikt. Er worden geen secrets in de
|
|
repository geschreven. Bewaar het tokenbestand alleen zolang registratie/herstel
|
|
dat nodig heeft en behandel `.runner` als credential.
|
|
|
|
De gebruikersservice start bij een gebruikerssessie. Automatisch doorlopen zonder
|
|
inloggen vereist daarnaast een bewuste keuze voor user lingering en een Docker-
|
|
daemon die zonder desktopsessie beschikbaar is. S4 belooft geen beschikbaarheid
|
|
wanneer de mini-pc uitstaat. Herstarten/stoppen:
|
|
|
|
```sh
|
|
systemctl --user restart agiledancers-runner
|
|
systemctl --user stop agiledancers-runner
|
|
```
|
|
|
|
## Images en publicatie
|
|
|
|
| Component | Image |
|
|
| --- | --- |
|
|
| Backend | `192.168.2.28:3000/wanjakrah/agiledancers-backend` |
|
|
| Frontend | `192.168.2.28:3000/wanjakrah/agiledancers-frontend` |
|
|
|
|
De volledige commit-SHA is de versie van beide images. Een `main`-tag wijst naar
|
|
de nieuwste met succes gepubliceerde actuele hoofdbranchbuild. Gebruik voor een
|
|
exact passend paar op beide images dezelfde SHA:
|
|
|
|
```sh
|
|
# Gebruik bij private packages eerst docker login met interactieve invoer.
|
|
commit_sha=<volledige-commit-SHA>
|
|
docker pull "192.168.2.28:3000/wanjakrah/agiledancers-backend:$commit_sha"
|
|
docker pull "192.168.2.28:3000/wanjakrah/agiledancers-frontend:$commit_sha"
|
|
```
|
|
|
|
De frontend luistert op containerpoort 8080, ondersteunt SPA-routes en proxy't
|
|
`/api/` naar `BACKEND_UPSTREAM` (standaard `backend:8080`). De backend luistert op
|
|
8080. Voorbeelden voor eventueel handmatig starten staan los van de pipeline;
|
|
de pipeline start geen blijvende applicatie op de NAS.
|
|
|
|
`java ci/Ci.java verify` maakt een succesmarker pas na alle builds en tests.
|
|
`java ci/Ci.java publish` vereist die marker en hoofdbranchref. Onder een gedeeld Java-bestandslot (`FileChannel`)
|
|
buiten de checkout worden bestaande commitimages hergebruikt en ontbrekende
|
|
images geüpload. Iedere image wordt teruggehaald, op revisielabel gecontroleerd en
|
|
met digest vastgelegd in de diagnostiek. Authenticatie- of netwerkfouten tellen
|
|
niet als een ontbrekende tag.
|
|
|
|
Pas na beide images worden `main`-tags bijgewerkt, met een actuele hoofdbranch-
|
|
controle voor iedere wijziging. De gedeelde lock voorkomt dat een oudere pipeline
|
|
een door een nieuwere pipeline bijgewerkte tag terugzet. `capacity: 1` ondersteunt
|
|
dat op de enige runner. Vertrouw niet op workflow-`concurrency`: Gitea 1.25 negeert
|
|
die instelling. De twee bewegende tags zijn geen atomisch paar.
|
|
|
|
## Diagnostiek en herstellen
|
|
|
|
Iedere workflowpoging bewaart beschikbare diagnostiek als
|
|
`diagnostics-<run-id>-<unique-attempt-id>` gedurende veertien dagen: Maven-rapporten, JUnit-
|
|
rapporten van frontend/Playwright, het Playwright HTML-rapport, traces/screenshots
|
|
en containerlogs. Open de artifactdownload op de Gitea Actions-runpagina.
|
|
Build- en publicatielogs staan er eveneens in. Gitea 1.25 vult `gitea.run_attempt`
|
|
niet in; de workflow maakt daarom zelf een unieke identificatie per poging. Geen environmentdump of Docker
|
|
inspect met mogelijke credentials wordt opgenomen.
|
|
|
|
Bij mislukking blijven de oorspronkelijke exitstatus en rapporten behouden.
|
|
Een Java-`finally`/shutdown-hook én een `always()`-stap verzamelen diagnostiek en verwijderen de tijdelijke
|
|
containers en het netwerk met hun unieke runnaam. Een harde machine-uitval kan
|
|
opruimen onderbreken: controleer daarna uitsluitend achtergebleven resources met
|
|
label `agiledancers.ci.run`; gebruik geen algemene Docker-prune op de ontwikkel-PC.
|
|
|
|
Herstart een mislukte run vanuit Gitea. Als slechts één commitimage gepubliceerd
|
|
was, bewaart de herhaling die en vult de ontbrekende image aan. Een fout bij
|
|
publiceren, terughalen of bijwerken van `main` laat de pipeline falen. Bestaande
|
|
commitimages worden niet overschreven. Bij een inmiddels nieuwere hoofdbranch
|
|
blijven de committags bruikbaar en worden de oude `main`-updates overgeslagen.
|
|
|
|
Lokale controle van publicatie-/foutgedrag zonder registrywijzigingen:
|
|
|
|
```sh
|
|
java ci/Ci.java test
|
|
```
|
|
|
|
Volledige lokale verificatie met Docker en de vastgestelde platformwaarde:
|
|
|
|
```sh
|
|
export JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64
|
|
export TARGET_PLATFORM=linux/amd64 # eerst de Synology controleren
|
|
java ci/Ci.java verify
|
|
```
|
|
|
|
## Operationele oplevering
|
|
|
|
Leg links/run-ID's en beide image-digests vast in `docs/s4-validation.md` voor:
|
|
|
|
1. Een geslaagde feature-branchpush, inclusief twee builds en container-E2E,
|
|
zonder imagepublicatie.
|
|
2. Een expres mislukte build/test op een tijdelijke branch die publicatie blokkeert,
|
|
met downloadbare foutdiagnostiek. Herstel die testwijziging daarna.
|
|
3. Een geslaagde hoofdbranchrun met beide teruggehaalde commitimages.
|
|
4. Een herhaling/partiële-publicatieherstel en bewijs dat bestaande committags
|
|
behouden blijven en oudere builds `main` niet terugzetten.
|
|
|
|
Zonder werkende runner, vastgestelde NAS-architectuur, registrytoegang en echte
|
|
pipelinebewijzen is S4 niet volledig opgeleverd.
|
|
|
|
Bronnen: [runner](https://docs.gitea.com/1.25/usage/actions/act-runner/),
|
|
[Gitea-verschillen](https://docs.gitea.com/1.25/usage/actions/comparison/),
|
|
[containerregistry](https://docs.gitea.com/1.25/usage/packages/container/).
|