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:

```ini
[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`:
>
> ```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:

```bash
# 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`):

```bash
# .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.

Eerste keer overstappen van lokaal bouwen naar de registry:

```bash
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

```bash
# 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:

```bash
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:

```bash
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

```bash
# 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
```