# 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 ` 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. 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= 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/).