314 lines
12 KiB
Markdown
314 lines
12 KiB
Markdown
# 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. Forgejo-tag `v0.5.10` vertalen naar registry-tag `0.5.10`
|
|
2. docker pull git.example.com/bes-r/server-up:0.5.10
|
|
3. SU_TAG=0.5.10 en SU_VERSION=0.5.10 in de deploy-.env vastleggen
|
|
4. helper starten met exact dezelfde Compose-projectnaam en configuratiebestanden
|
|
5. Server Up vervangen; de browser pollt /healthz tot de nieuwe versie leeft
|
|
```
|
|
|
|
Stap 4 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.
|
|
Met `--no-build --pull never` gebruikt Compose gegarandeerd precies dat image.
|
|
|
|
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
|
|
SU_VERSION=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.
|
|
|
|
De Git-release heet bijvoorbeeld `v0.5.10`, maar de canonieke image-tag heet
|
|
`:0.5.10`. Server Up verwijdert die ene voorloop-`v` automatisch voor zowel
|
|
stable/main- als beta-releases. De build publiceert daarnaast `:v0.5.10` als
|
|
compatibiliteitstag, zodat installaties met de oude updater één keer zonder
|
|
handmatige ingreep naar de gerepareerde versie kunnen overstappen.
|
|
|
|
> De draaiende Server Up-container schrijft niet rechtstreeks in je deploy-
|
|
> `.env`: de installatiemap is daar niet gemount. De updatehelper mount die map
|
|
> wel en werkt `SU_TAG` en `SU_VERSION` samen bij. Zo blijft ook een latere
|
|
> handmatige `docker compose up -d` op dezelfde versie.
|
|
|
|
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
|
|
```
|