# 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. 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 ci/Ci.java ` 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 ` 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. 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 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. 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. ## 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. Op de mini-pc starten Docker Desktop en de runner automatisch na grafisch aanmelden. Bij een Docker Desktop-socket installeert de installer hiervoor `~/.config/systemd/user/agiledancers-runner.service.d/10-agiledancers-docker-desktop.conf` en schakelt beide services in voor `graphical-session.target`. De runner wacht via `~/.local/share/agiledancers-runner/WaitForDocker.java` maximaal 120 seconden tot de ingestelde Docker-engine bereikbaar is. Bij een mislukte start probeert systemd het na tien seconden opnieuw. De runner volgt stoppen en herstarten van Docker Desktop en stopt bij afmelden. User lingering staat op deze pc uit: vóór aanmelden starten deze services niet. 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= 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--` 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/).