server-up/docs/updates.md

Updates en Forgejo-instelling

Server Up controleert zelf of er een nieuwere versie is en kan zichzelf bijwerken met één klik. Dit document beschrijft hoe dat werkt en hoe je Forgejo er precies voor inricht.

---

Hoe het werkt

Er zijn twee losse onderdelen:

Onderdeel	Wat het doet	Waar het vandaan komt
Detectie	"Er is een v0.5.10"	Forgejo Releases-API
Uitvoeren	Het nieuwe image ophalen en de container vervangen	Forgejo container-registry

Je hebt ze allebei nodig voor de updateknop. Alleen detectie werkt ook prima — dan zie je een melding en werk je bij met een git-tag, zoals voorheen.

Twee manieren van bijwerken — kies er één per server

	Hoe je bijwerkt	Knop in de interface
Git-gestuurd (SU_IMAGE leeg)	Push naar de branch, de deploy-workflow bouwt en herstart	Uit, met uitleg
Registry (SU_IMAGE gezet)	Knop "Nu bijwerken", of een tag pushen	Aan

Een server die zelf bouwt kán niet uit een registry bijwerken: het image server-up:0.5.40-beta heeft geen registry-pad, dus er is niets om op te halen. De interface meldt dat en verwijst naar de Git-route. Dat is geen storing — zo is een dev-server die na elke push opnieuw bouwt precies bedoeld.

Gebruik ze niet door elkaar op dezelfde server. De deploy-workflow schrijft SU_TAG in .env, en de updateknop doet dat ook. Werk je in de interface bij naar 0.5.50 en pusht daarna iemand naar die branch, dan zet de workflow SU_TAG terug naar wat de branch bevat. Voor een server die aan een branch hangt is dat juist goed — git is daar de bron — maar verwacht dan geen effect van de knop.

In de praktijk: dev-server op Git, en de registry-route voor productie of voor installaties die geen toegang tot je repository hebben.

Kanalen

Kanaal	Ziet	Voorbeeld
stable	Alleen echte releases	v0.5.10
beta	Ook pre-releases	v0.5.10-beta1 én v0.5.10

Een tag met een streepje erin (v0.5.10-beta1) wordt door release.yml automatisch als pre-release gemarkeerd. Semver bepaalt de volgorde, en een release telt hoger dan zijn eigen beta: 0.5.10-beta1 < 0.5.10. Zit je op beta en verschijnt de definitieve v0.5.10, dan krijg je die dus als update aangeboden.

Wat er gebeurt als je op "Nu bijwerken" klikt

1. docker pull git.example.com/bes-r/server-up:0.5.10
2. SU_TAG=0.5.10 wegschrijven in het .env van de deploy-map
3. helper-container starten:  sleep 5 && docker compose up -d server-up
4. Server Up wordt vervangen; de browser pollt /healthz tot de nieuwe versie leeft

Stap 3 is nodig omdat een container zichzelf niet kan hercreëren: het commando zou halverwege zijn eigen proces afbreken. De helper draait op het zojuist gehaalde image — dat bevat de docker- en compose-CLI al — en ruimt zichzelf op.

De deploy-map wordt niet geraden maar uitgelezen uit de compose-labels op de eigen container (com.docker.compose.project.working_dir). Draait Server Up niet via compose, dan meldt de interface dat bijwerken niet kan in plaats van iets te proberen.

---

Deel 1 — Forgejo inrichten

1.1 Container-registry aanzetten

De registry zit in Forgejo ingebouwd, maar staat niet altijd aan. Controleer in app.ini op je Forgejo-server:

[packages]
ENABLED = true

Herstart Forgejo na een wijziging. Ga daarna naar je profiel → Packages; als die pagina bestaat, werkt de registry.

Draai je Forgejo op een poort (bv. :3000) zonder TLS? Dan moet Docker die registry als "insecure" kennen. Zet op elke server die images ophaalt in /etc/docker/daemon.json:

{ "insecure-registries": ["10.0.20.22:3000"] }

en systemctl restart docker. Met HTTPS en een geldig certificaat is dit niet nodig — dat heeft de voorkeur.

1.2 Token aanmaken voor de registry

Instellingen → Applicaties → Nieuw token genereren

Veld	Waarde
Naam	server-up-packages
Rechten	package: Read and Write

Kopieer het token meteen — je ziet het maar één keer. Je hebt het twee keer nodig: als repository-secret (voor de build) en in Server Up zelf (voor het ophalen).

Wil je scheiden: maak een tweede token met alleen package: Read voor de servers die enkel ophalen. Dat is netter, maar niet verplicht.

1.3 Repository-variabelen en -secrets

Ga naar de repository → Settings → Actions.

Variables (niet geheim, zichtbaar in logs):

Naam	Waarde	Toelichting
REGISTRY	10.0.20.22:3000	Host van je Forgejo, zonder http://
OWNER	bes-r	Je gebruikersnaam of organisatie

Secrets (versleuteld, gemaskeerd in logs):

Naam	Waarde
PACKAGE_TOKEN	het token uit 1.2
RELEASE_TOKEN	(optioneel) token met repository: Read and Write, als het automatische GITHUB_TOKEN niet volstaat voor release.yml

1.4 Runners controleren

De workflows verwachten deze labels:

Workflow	Draait op	Trigger
deploy.yml	[self-hosted, dev]	push naar dev
deploy-prod.yml	[self-hosted, prod]	push naar main + v*-tags
release.yml	[self-hosted, prod]	v*-tags
build.yml	[self-hosted, prod]	alleen handmatig

Controleer je labels met:

# op de server waar act_runner draait
grep -A3 'labels:' /etc/act_runner/config.yaml

Staat er iets anders, pas dan runs-on: in de workflows aan óf hernoem de labels van de runner. De runner heeft toegang tot de docker-socket nodig.

Let op de volgorde. deploy-prod.yml bouwt én pusht het image in dezelfde job. Dat is bewust: een aparte build-workflow zou bij één runner met de deploy om dezelfde plek in de wachtrij strijden, waarbij de deploy wacht op een build die zelf nog in de rij staat. build.yml is er alleen voor handmatig herbouwen.

---

Deel 2 — De server instellen

Op de server waar Server Up draait, in de deploy-map (/opt/server-up):

# .env
SU_IMAGE=10.0.20.22:3000/bes-r/server-up
SU_TAG=0.5.10
BIND=127.0.0.1
PORT=5000

SU_IMAGE is het schakelaartje: staat het er, dan draait deze server vanaf de registry en werkt de updateknop. Staat het er niet, dan bouwt de server lokaal zoals voorheen en meldt de interface netjes waarom bijwerken niet kan.

Server Up schrijft SU_TAG niet zelf in je .env, en dat is met opzet: de installatiemap is nergens in de container gemount. De helper-container die de hercreatie doet, mount hem wél en zet de tag daar. Tot v0.10.20 probeerde Server Up het zelf, en faalde dat dus altijd.

Eerste keer overstappen van lokaal bouwen naar de registry:

cd /opt/server-up
docker login 10.0.20.22:3000 -u bes-r          # token uit 1.2 als wachtwoord
docker pull 10.0.20.22:3000/bes-r/server-up:0.5.10
docker compose up -d
docker compose ps                               # controleer de nieuwe image-naam

Deel 3 — Server Up instellen

Instellingen → Updates:

Veld	Waarde
Kanaal	Stable of Beta
Releases-API URL	http://10.0.20.22:3000/api/v1/repos/bes-r/server-up/releases
Image	10.0.20.22:3000/bes-r/server-up
Registry-gebruiker	bes-r (alleen bij een privé repo)
Registry-token	het token uit 1.2 (idem)

Het registry-token wordt opgeslagen in config.json (0600) en komt nooit terug via de API — je ziet alleen of het ingesteld is. Leeg laten bij het opslaan betekent "niet wijzigen".

Klik op Controleren. Staat er een versie, dan werkt de detectie.

---

Een versie uitbrengen

# 1. Versienummer bijwerken
echo "0.5.10" > VERSION

# 2. Changelog-sectie schrijven (release.yml haalt de notes hieruit)
$EDITOR CHANGELOG.md          # begin met:  # v0.5.10 — Korte titel

# 3. Vastleggen en taggen
git add VERSION CHANGELOG.md
git commit -m "v0.5.10 - korte omschrijving"
git push origin dev

# 4. Via een pull request naar main, dan pas taggen
git checkout main && git pull
git tag v0.5.10
git push origin v0.5.10

Die tag zet drie dingen in gang:

1. release.yml maakt de Forgejo-release met notes uit CHANGELOG.md plus een commitoverzicht sinds de vorige tag.
2. deploy-prod.yml draait de tests, bouwt het image, pusht het als :0.5.10 én :latest, en herstart de prod-server.
3. Elke Server Up-installatie ziet bij de volgende check de nieuwe versie.

Een beta uitbrengen

Precies hetzelfde, met een streepje in de tag:

echo "0.5.10-beta1" > VERSION
git commit -am "v0.5.10-beta1"
git tag v0.5.10-beta1
git push origin v0.5.10-beta1

release.yml markeert dit automatisch als pre-release, en het image krijgt de tags :0.5.10-beta1 en :beta (géén :latest). Alleen installaties op het beta-kanaal zien hem.

Volgens de projectafspraken toont de dev-branch altijd beta in het versienummer; die tags horen dus bij wat je vanuit dev uitbrengt.

---

Terugrollen

Server Up onthoudt bij elke update de vorige tag. Onder Instellingen → Updates verschijnt dan een knop "Terug naar deze versie", die precies hetzelfde doet met het oude image.

Start de nieuwe versie helemaal niet — dan is er ook geen interface om op te klikken — dan doe je het met de hand:

cd /opt/server-up
sed -i 's/^SU_TAG=.*/SU_TAG=0.5.00/' .env
docker compose up -d

---

Problemen oplossen

Symptoom	Oorzaak en oplossing
Knop staat uit, "komt niet uit een registry"	SU_IMAGE ontbreekt in .env, of de container draait nog op een lokaal gebouwd image. Zie deel 2.
Knop staat uit, "geen compose-labels"	De container is met docker run gestart in plaats van met compose. Start hem via docker compose up -d.
Knop staat uit, "container niet te vinden"	De docker-socket is niet gemount, of de containernaam wijkt af. Zet SU_CONTAINER op de juiste naam.
docker pull faalt met "unauthorized"	Registry-gebruiker/token niet ingesteld in Server Up, of het token mist package: Read.
docker pull faalt met "http: server gave HTTP response to HTTPS client"	Insecure registry niet geconfigureerd; zie 1.1.
"Geen releases gevonden in kanaal 'stable'"	Er zijn alleen pre-releases. Zet het kanaal op Beta of breng een release zonder streepje uit.
Update-check geeft een netwerkfout	De Releases-URL klopt niet, of Server Up kan Forgejo niet bereiken. Test met curl vanuit de container.
Interface komt na bijwerken niet terug	Nieuwe image start niet. Kijk met docker compose logs server-up en rol handmatig terug (zie boven).
Nieuwe versie verschijnt niet	De check cachet een uur. Klik op Controleren om te forceren.

Handmatig controleren of de registry werkt

# Is het image gepusht?
curl -s -u bes-r:<token> \
  http://10.0.20.22:3000/v2/bes-r/server-up/tags/list

# Geeft de Releases-API iets terug?
curl -s http://10.0.20.22:3000/api/v1/repos/bes-r/server-up/releases \
  | python3 -m json.tool | head -30