256 lines
13 KiB
Markdown
256 lines
13 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. Deze buildworkflow voert geen deployment uit.
|
|
S6 voegt aparte handmatige workflows toe voor productie en rollback; zie
|
|
[productiedeployment](production-deployment.md).
|
|
Tagpushes en aparte pull-requestevents starten geen extra workflow. Een auteur
|
|
kan een branchbuild bewust overslaan met een door Gitea ondersteunde markering,
|
|
zoals `[skip ci]`; dit is expliciet toegestaan.
|
|
|
|
## Java-bronbestanden uitvoeren
|
|
|
|
De CI- en setuphulpmiddelen zijn Java 25-bronbestanden. Start ze direct met
|
|
`java generated/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 de vertrouwde repositories van deze eigenaar.
|
|
|
|
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 generated/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/mini-pc-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. De standaard `SKIP_WORKFLOW_STRINGS`, waaronder `[skip ci]`, mogen blijven staan:
|
|
bewust overslaan is door de maintainer toegestaan. Iedere gewone branchpush start
|
|
een pipeline. Er hoeft daarvoor geen serverinstelling te worden gewijzigd.
|
|
|
|
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 de gedeelde user-scoped runner `mini-pc` voor `wanjakrah`; een nieuwe
|
|
repository heeft geen eigen runnerregistratie nodig.
|
|
Sla tokenwaarden buiten Git op en plaats ze niet in opdrachten, screenshots of logs.
|
|
|
|
Voor reproduceerbare configuratie bestaat `java generated/ci/Ci.java configure-gitea`. Maak twee
|
|
bestanden buiten de repository met mode `600`: één voor een PAT met voldoende
|
|
repositorybeheerrechten (repository Actions, secrets en variabelen),
|
|
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 generated/ci/Ci.java configure-gitea
|
|
```
|
|
|
|
Het script stelt alleen de applicatie-instellingen, registrysecrets en platformwaarde
|
|
in. De gedeelde runnerregistratie wordt eenmalig beheerd vanuit engineering.
|
|
Applicatiespecifieke deploymentcredentials blijven onder ~/.config/agiledancers-runner/.
|
|
|
|
De bevestigde Gitea 1.25.4-configuratie heeft geen `[actions]`-sectie: de defaults
|
|
zijn negentig dagen voor artifacts en 365 dagen voor logs. 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.
|
|
|
|
## Gedeelde runner gebruiken
|
|
|
|
De fysieke mini-pc draait `mini-pc-runner.service` met label `mini-pc:host`,
|
|
geregistreerd op gebruikersniveau voor `wanjakrah`. Daardoor kunnen bestaande en
|
|
nieuwe repositories van deze eigenaar dezelfde runner gebruiken. De gedeelde
|
|
capaciteit is één job tegelijk. De workflowbestanden gebruiken `runs-on: mini-pc`.
|
|
|
|
Voor eenmalige registratie, installatie en migratie volg je de
|
|
[engineering-instructies](http://192.168.2.28:3000/wanjakrah/engineering/src/tag/v2.0.0/README.md).
|
|
Controleer dit project met `java generated/ci/Ci.java check-runner`; gebruik daarbij
|
|
het in engineering beschreven owner-only tokenbestand voor de gedeelde setup.
|
|
|
|
```sh
|
|
systemctl --user status mini-pc-runner
|
|
journalctl --user -u mini-pc-runner -f
|
|
systemctl --user restart mini-pc-runner
|
|
```
|
|
|
|
Runnerstate staat onder ~/.local/share/mini-pc-runner/ en serviceconfiguratie onder
|
|
~/.config/mini-pc-runner/. De runner start samen met Docker Desktop na grafisch
|
|
aanmelden, wacht maximaal 120 seconden op Docker en probeert een mislukte start
|
|
opnieuw. User lingering staat uit: vóór aanmelden of bij een uitgeschakelde mini-pc
|
|
is de runner niet beschikbaar. De oude agiledancers-runnerstate blijft voor herstel
|
|
bewaard; applicatiespecifieke deploymenttokens en SSH-sleutels blijven op hun eigen paden.
|
|
|
|
## 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 generated/ci/Ci.java verify` maakt een succesmarker pas na alle builds en tests.
|
|
`java generated/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 generated/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 generated/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/).
|