669 lines
20 KiB
Markdown
669 lines
20 KiB
Markdown
# Forgejo Actions — deploy-pipeline opzetten voor Server Up
|
|
|
|
Volledig stappenplan om vanuit je laptop via Forgejo automatisch te deployen naar een Ubuntu/Debian server met Docker Compose. Inclusief een dev/prod-splitsing zodat je `dev`-server alleen de ontwikkelversie krijgt en prod-servers alleen stabiele releases.
|
|
|
|
## Al eerder opgezet? Lees dit eerst
|
|
|
|
Als je de pipeline al hebt ingericht en alleen de dev/prod-splitsing wilt toevoegen, hoef je niet alles opnieuw te doen. Voer alleen deze stappen uit:
|
|
|
|
1. **Runner opnieuw registreren met label `dev`** — zie [Stap 4b](#4b-registreren-op-de-app-server)
|
|
2. **`dev`-branch aanmaken** in je repo: `git checkout -b dev && git push -u origin dev`
|
|
3. **Workflow-bestanden bijwerken** — commit en push de gewijzigde `.forgejo/workflows/deploy.yml` en nieuwe `deploy-prod.yml` naar `dev`
|
|
4. **`/opt/server-up/.env`** aanmaken voor handmatige builds buiten de pipeline:
|
|
```bash
|
|
echo "SU_VERSION=dev-handmatig" > /opt/server-up/.env
|
|
```
|
|
|
|
---
|
|
|
|
## Architectuur
|
|
|
|
```
|
|
[ Laptop ]
|
|
|
|
|
| git push naar dev-branch
|
|
v
|
|
[ Forgejo VPS ] ──── dispatcht workflow ────> [ Dev-server ]
|
|
- act_runner (label: dev)
|
|
- Docker + Compose
|
|
- /opt/server-up/
|
|
|
|
[ Forgejo VPS ] ──── dispatcht workflow ────> [ Prod-server(s) ]
|
|
- act_runner (label: prod)
|
|
- Docker + Compose
|
|
- /opt/server-up/
|
|
```
|
|
|
|
Twee soorten servers:
|
|
|
|
- **Dev-server** — draait de `dev` branch. Wordt automatisch bijgewerkt bij elke push naar `dev`. Bedoeld voor testen.
|
|
- **Prod-server(s)** — draaien de `main` branch of een `v*`-tag. Worden alleen bijgewerkt als je bewust naar `main` merget of een release tagt.
|
|
|
|
De routing werkt via **runner-labels**: elke server registreert zijn runner met een eigen label (`dev` of `prod`). De workflow kiest op dat label. Zo pikt een dev-server nooit een prod-deploy op en andersom.
|
|
|
|
We draaien de runner in _host mode_: jobs draaien direct op de host, niet in een container. Dat is voor deploy-jobs verreweg het simpelst — Docker socket en bind-mount paden kloppen vanzelf.
|
|
|
|
---
|
|
|
|
## Wat je nodig hebt
|
|
|
|
- Forgejo VPS met root- of admin-toegang
|
|
- App-server (Ubuntu 22.04/24.04 of Debian 12) met root- of sudo-toegang
|
|
- DNS-naam voor je Forgejo-instance (bv. `forgejo.example.com`) met geldig TLS-certificaat
|
|
- Server Up uitgecheckt lokaal, met `Dockerfile` en `docker-compose.yml`
|
|
|
|
---
|
|
|
|
## Stap 1 — Actions globaal aanzetten in Forgejo
|
|
|
|
Forgejo heeft **geen UI-toggle** voor Actions. Je zet het aan in `app.ini`. Zolang het uit staat zie je geen **Actions**-tab in repo's.
|
|
|
|
### 1a. Snelle check: staat het al aan?
|
|
|
|
Open een willekeurige repo in Forgejo. Zie je bovenaan een **Actions**-tab? Dan is het al aan — ga door naar stap 1d.
|
|
|
|
### 1b. `app.ini` vinden
|
|
|
|
SSH naar je Forgejo VPS:
|
|
|
|
```bash
|
|
# Zoek de containernaam
|
|
docker ps --format 'table {{.Names}}\t{{.Image}}' | grep -i forgejo
|
|
|
|
# Bekijk huidige Actions-config
|
|
docker exec forgejo cat /data/gitea/conf/app.ini | grep -A2 "\[actions\]" \
|
|
|| echo "Geen [actions] blok gevonden"
|
|
|
|
# Vind het hostpad van de data-map
|
|
docker inspect forgejo --format \
|
|
'{{ range .Mounts }}{{ .Source }} -> {{ .Destination }}{{ "\n" }}{{ end }}'
|
|
```
|
|
|
|
Zoek de regel waar `Destination` `/data` is. Het bestand staat dan op `<Source>/gitea/conf/app.ini`. Typische plekken:
|
|
|
|
- `/var/lib/forgejo/gitea/conf/app.ini`
|
|
- `./forgejo/gitea/conf/app.ini` (relatief aan je `docker-compose.yml`)
|
|
- Bij een named volume: `/var/lib/docker/volumes/<naam>/_data/gitea/conf/app.ini`
|
|
|
|
### 1c. `app.ini` aanpassen en Forgejo herstarten
|
|
|
|
```bash
|
|
APP_INI=/var/lib/forgejo/gitea/conf/app.ini # pas aan naar jouw pad
|
|
sudo cp "$APP_INI" "$APP_INI.bak"
|
|
sudo nano "$APP_INI"
|
|
```
|
|
|
|
Voeg onderaan toe — of update het bestaande `[actions]`-blok:
|
|
|
|
```ini
|
|
[actions]
|
|
ENABLED = true
|
|
DEFAULT_ACTIONS_URL = https://code.forgejo.org
|
|
```
|
|
|
|
Herstart Forgejo:
|
|
|
|
```bash
|
|
docker compose restart forgejo # in de map waar je docker-compose.yml staat
|
|
# of zonder compose:
|
|
docker restart forgejo
|
|
```
|
|
|
|
Refresh een repo-pagina — de **Actions**-tab moet nu zichtbaar zijn.
|
|
|
|
### 1d. Repo-Actions inschakelen
|
|
|
|
Ga in je repo naar **Settings → Actions → General → Enable Repository Actions** (dit is standaard aan zodra Actions globaal aan staan).
|
|
|
|
---
|
|
|
|
## Stap 2 — App-server voorbereiden
|
|
|
|
SSH naar de app-server als root of met `sudo`.
|
|
|
|
### 2a. Systeem up-to-date
|
|
|
|
```bash
|
|
apt update && apt upgrade -y
|
|
apt install -y curl ca-certificates gnupg git rsync ufw
|
|
```
|
|
|
|
### 2b. Docker + Compose plugin installeren
|
|
|
|
```bash
|
|
install -m 0755 -d /etc/apt/keyrings
|
|
curl -fsSL https://download.docker.com/linux/debian/gpg | \
|
|
gpg --dearmor -o /etc/apt/keyrings/docker.gpg
|
|
chmod a+r /etc/apt/keyrings/docker.gpg
|
|
|
|
# Voor Ubuntu vervang 'debian' door 'ubuntu'
|
|
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
|
|
https://download.docker.com/linux/debian $(. /etc/os-release && echo $VERSION_CODENAME) stable" \
|
|
> /etc/apt/sources.list.d/docker.list
|
|
|
|
apt update
|
|
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
|
|
systemctl enable --now docker
|
|
docker --version && docker compose version
|
|
```
|
|
|
|
### 2c. Deploy-user aanmaken
|
|
|
|
```bash
|
|
useradd -m -s /bin/bash deploy
|
|
usermod -aG docker deploy
|
|
mkdir -p /opt/server-up
|
|
chown deploy:deploy /opt/server-up
|
|
```
|
|
|
|
De runner draait als `deploy`. Door deze user in de `docker`-groep te zetten kan hij `docker compose` zonder sudo aanroepen.
|
|
|
|
### 2d. Firewall (optioneel maar aanbevolen)
|
|
|
|
```bash
|
|
ufw default deny incoming
|
|
ufw default allow outgoing
|
|
ufw allow OpenSSH
|
|
ufw allow 80/tcp
|
|
ufw allow 443/tcp
|
|
ufw enable
|
|
```
|
|
|
|
De runner heeft alleen _uitgaande_ HTTPS naar je Forgejo nodig — geen inkomende poort.
|
|
|
|
---
|
|
|
|
## Stap 3 — Act_runner installeren
|
|
|
|
Forgejo gebruikt `act_runner` als runner-daemon.
|
|
|
|
```bash
|
|
# Controleer de nieuwste versie op:
|
|
# https://code.forgejo.org/forgejo/act_runner/releases
|
|
VERSION=6.2.2
|
|
ARCH=amd64 # of arm64 voor ARM-servers
|
|
curl -fsSL -o /usr/local/bin/act_runner \
|
|
"https://code.forgejo.org/forgejo/runner/releases/download/v${VERSION}/forgejo-runner-${VERSION}-linux-${ARCH}"
|
|
chmod +x /usr/local/bin/act_runner
|
|
act_runner --version
|
|
```
|
|
|
|
### Werkdirectory en config
|
|
|
|
```bash
|
|
mkdir -p /etc/act_runner /var/lib/act_runner
|
|
chown deploy:deploy /var/lib/act_runner
|
|
act_runner generate-config > /etc/act_runner/config.yaml
|
|
chown root:deploy /etc/act_runner/config.yaml
|
|
chmod 640 /etc/act_runner/config.yaml
|
|
```
|
|
|
|
Open `/etc/act_runner/config.yaml` en pas deze velden aan:
|
|
|
|
```yaml
|
|
runner:
|
|
file: /var/lib/act_runner/.runner
|
|
capacity: 1
|
|
timeout: 30m
|
|
insecure: false
|
|
fetch_timeout: 5s
|
|
fetch_interval: 2s
|
|
cache:
|
|
enabled: true
|
|
dir: /var/lib/act_runner/cache
|
|
host:
|
|
workdir_parent: /var/lib/act_runner/host-work
|
|
```
|
|
|
|
---
|
|
|
|
## Stap 4 — Runner registreren
|
|
|
|
### 4a. Token ophalen uit Forgejo
|
|
|
|
Ga in Forgejo naar je repo → **Settings → Actions → Runners → Create new Runner**. Kopieer het token.
|
|
|
|
Kies het niveau dat bij je gebruik past:
|
|
|
|
- **Repo-niveau** (alleen deze repo) — veiligst
|
|
- **Organization-niveau** — handig als je meerdere repo's hebt
|
|
- **Site-niveau** — alleen als je veel repo's wilt deployen
|
|
|
|
### 4b. Registreren op de app-server
|
|
|
|
**Dev-server** — registreer met label `dev`:
|
|
|
|
```bash
|
|
sudo -u deploy bash -c '
|
|
cd /var/lib/act_runner && \
|
|
act_runner register \
|
|
--no-interactive \
|
|
--instance https://jouw-forgejo-url \
|
|
--token JOUW_TOKEN \
|
|
--name dev-server \
|
|
--labels self-hosted,dev \
|
|
--config /etc/act_runner/config.yaml
|
|
'
|
|
```
|
|
|
|
**Prod-server** — registreer met label `prod`:
|
|
|
|
```bash
|
|
sudo -u deploy bash -c '
|
|
cd /var/lib/act_runner && \
|
|
act_runner register \
|
|
--no-interactive \
|
|
--instance https://jouw-forgejo-url \
|
|
--token JOUW_TOKEN \
|
|
--name prod-server-1 \
|
|
--labels self-hosted,prod \
|
|
--config /etc/act_runner/config.yaml
|
|
'
|
|
```
|
|
|
|
> **Al geregistreerd met andere labels?** Stop de service, verwijder het `.runner`-bestand en registreer opnieuw:
|
|
> ```bash
|
|
> systemctl stop act_runner
|
|
> rm /var/lib/act_runner/.runner
|
|
> # voer daarna bovenstaand register-commando uit
|
|
> ```
|
|
|
|
Controleer in Forgejo onder **Settings → Actions → Runners** — je runner staat als **Idle**.
|
|
|
|
---
|
|
|
|
## Stap 5 — Runner als systemd-service instellen
|
|
|
|
Doe dit op elke server na de registratie:
|
|
|
|
```bash
|
|
cat > /etc/systemd/system/act_runner.service << 'EOF'
|
|
[Unit]
|
|
Description=Forgejo Actions runner
|
|
After=network-online.target docker.service
|
|
Wants=network-online.target
|
|
|
|
[Service]
|
|
Type=simple
|
|
User=deploy
|
|
Group=deploy
|
|
WorkingDirectory=/var/lib/act_runner
|
|
ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
|
|
Restart=on-failure
|
|
RestartSec=5s
|
|
NoNewPrivileges=true
|
|
ProtectSystem=full
|
|
ProtectHome=read-only
|
|
PrivateTmp=true
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
EOF
|
|
|
|
systemctl daemon-reload
|
|
systemctl enable --now act_runner
|
|
systemctl status act_runner
|
|
```
|
|
|
|
Logs volgen:
|
|
|
|
```bash
|
|
journalctl -u act_runner -f
|
|
```
|
|
|
|
---
|
|
|
|
## Stap 6 — Branches inrichten
|
|
|
|
De workflows zijn opgezet rond twee branches:
|
|
|
|
| Branch | Doel | Deploy naar |
|
|
|--------|------|-------------|
|
|
| `dev` | Ontwikkeling, testen | Dev-server |
|
|
| `main` | Stabiele releases | Prod-server(s) |
|
|
|
|
Maak de `dev`-branch aan als die er nog niet is:
|
|
|
|
```bash
|
|
git checkout -b dev
|
|
git push -u origin dev
|
|
```
|
|
|
|
Typische werkwijze:
|
|
|
|
```
|
|
feature-branch → merge naar dev → automatisch op dev-server getest
|
|
dev → stabiel → merge naar main → automatisch op prod-server(s)
|
|
main → git tag v1.2.3 → deploy met versienummer ingebakken
|
|
```
|
|
|
|
---
|
|
|
|
## Stap 7 — Workflow-bestanden
|
|
|
|
De repo bevat twee deploy-workflows in `.forgejo/workflows/`:
|
|
|
|
### `deploy.yml` — dev-server
|
|
|
|
Triggert bij elke push naar `dev`. Draait alleen op runners met label `dev`.
|
|
|
|
```yaml
|
|
name: Deploy server-up (dev)
|
|
|
|
on:
|
|
push:
|
|
branches: [dev]
|
|
workflow_dispatch:
|
|
|
|
concurrency:
|
|
group: server-up-deploy-dev
|
|
cancel-in-progress: false
|
|
|
|
jobs:
|
|
deploy:
|
|
runs-on: [self-hosted, dev]
|
|
timeout-minutes: 20
|
|
|
|
env:
|
|
DEPLOY_DIR: /opt/server-up
|
|
|
|
steps:
|
|
- name: Checkout
|
|
uses: actions/checkout@v4
|
|
with:
|
|
fetch-depth: 1
|
|
|
|
- name: Bepaal versie
|
|
id: version
|
|
run: |
|
|
set -euo pipefail
|
|
VERSION="dev-${GITHUB_SHA:0:8}"
|
|
echo "VERSION=${VERSION}" >> "$GITHUB_ENV"
|
|
echo "SU_VERSION=${VERSION}" >> "$GITHUB_ENV"
|
|
echo "CHANNEL=dev" >> "$GITHUB_ENV"
|
|
echo "Deploying version: ${VERSION}"
|
|
|
|
- name: Sync code naar deploy-directory
|
|
run: |
|
|
set -euo pipefail
|
|
rsync -a --delete \
|
|
--exclude='.git/' \
|
|
--exclude='.forgejo/' \
|
|
./ "$DEPLOY_DIR/"
|
|
|
|
- name: Schrijf VERSION-bestand
|
|
working-directory: ${{ env.DEPLOY_DIR }}
|
|
run: echo "${VERSION}" > VERSION
|
|
|
|
- name: Build image
|
|
working-directory: ${{ env.DEPLOY_DIR }}
|
|
run: |
|
|
docker compose build --pull
|
|
docker tag "server-up:${VERSION}" server-up:latest
|
|
docker tag "server-up:${VERSION}" server-up:dev
|
|
|
|
- name: Deploy
|
|
working-directory: ${{ env.DEPLOY_DIR }}
|
|
run: |
|
|
set -euo pipefail
|
|
docker compose up -d --remove-orphans
|
|
docker compose ps
|
|
|
|
- name: Wachten op healthcheck
|
|
run: |
|
|
set -euo pipefail
|
|
for i in {1..40}; do
|
|
status=$(docker inspect --format '{{.State.Health.Status}}' server-up 2>/dev/null || echo "starting")
|
|
echo "poll $i: $status"
|
|
if [ "$status" = "healthy" ]; then
|
|
echo "server-up is healthy als versie ${VERSION}"
|
|
exit 0
|
|
fi
|
|
sleep 3
|
|
done
|
|
echo "server-up werd niet healthy in tijd — logs:"
|
|
cd "$DEPLOY_DIR" && docker compose logs --tail=200
|
|
exit 1
|
|
|
|
- name: Oude images opruimen (behoud laatste 5)
|
|
if: success()
|
|
run: |
|
|
docker images server-up --format '{{.Tag}} {{.ID}}' \
|
|
| grep -vE '^(latest|release|dev) ' \
|
|
| tail -n +6 \
|
|
| awk '{print $2}' \
|
|
| xargs -r docker rmi -f || true
|
|
docker image prune -f
|
|
```
|
|
|
|
### `deploy-prod.yml` — prod-servers
|
|
|
|
Triggert bij push naar `main` of een `v*`-tag. Draait alleen op runners met label `prod`.
|
|
|
|
```yaml
|
|
name: Deploy server-up (prod)
|
|
|
|
on:
|
|
push:
|
|
branches: [main]
|
|
tags: ['v*']
|
|
workflow_dispatch:
|
|
|
|
concurrency:
|
|
group: server-up-deploy-prod
|
|
cancel-in-progress: false
|
|
|
|
jobs:
|
|
deploy:
|
|
runs-on: [self-hosted, prod]
|
|
timeout-minutes: 20
|
|
|
|
env:
|
|
DEPLOY_DIR: /opt/server-up
|
|
|
|
steps:
|
|
- name: Checkout
|
|
uses: actions/checkout@v4
|
|
with:
|
|
fetch-depth: 1
|
|
|
|
- name: Bepaal versie
|
|
id: version
|
|
run: |
|
|
set -euo pipefail
|
|
if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
|
|
VERSION="${GITHUB_REF_NAME}"
|
|
CHANNEL="release"
|
|
else
|
|
VERSION="main-${GITHUB_SHA:0:8}"
|
|
CHANNEL="main"
|
|
fi
|
|
echo "VERSION=${VERSION}" >> "$GITHUB_ENV"
|
|
echo "CHANNEL=${CHANNEL}" >> "$GITHUB_ENV"
|
|
echo "SU_VERSION=${VERSION}" >> "$GITHUB_ENV"
|
|
echo "Deploying version: ${VERSION} (${CHANNEL})"
|
|
|
|
- name: Sync code naar deploy-directory
|
|
run: |
|
|
set -euo pipefail
|
|
rsync -a --delete \
|
|
--exclude='.git/' \
|
|
--exclude='.forgejo/' \
|
|
./ "$DEPLOY_DIR/"
|
|
|
|
- name: Schrijf VERSION-bestand
|
|
working-directory: ${{ env.DEPLOY_DIR }}
|
|
run: echo "${VERSION}" > VERSION
|
|
|
|
- name: Build image
|
|
working-directory: ${{ env.DEPLOY_DIR }}
|
|
run: |
|
|
docker compose build --pull
|
|
docker tag "server-up:${VERSION}" server-up:latest
|
|
docker tag "server-up:${VERSION}" "server-up:${CHANNEL}"
|
|
|
|
- name: Deploy
|
|
working-directory: ${{ env.DEPLOY_DIR }}
|
|
run: |
|
|
set -euo pipefail
|
|
docker compose up -d --remove-orphans
|
|
docker compose ps
|
|
|
|
- name: Wachten op healthcheck
|
|
run: |
|
|
set -euo pipefail
|
|
for i in {1..40}; do
|
|
status=$(docker inspect --format '{{.State.Health.Status}}' server-up 2>/dev/null || echo "starting")
|
|
echo "poll $i: $status"
|
|
if [ "$status" = "healthy" ]; then
|
|
echo "server-up is healthy als versie ${VERSION}"
|
|
exit 0
|
|
fi
|
|
sleep 3
|
|
done
|
|
echo "server-up werd niet healthy in tijd — logs:"
|
|
cd "$DEPLOY_DIR" && docker compose logs --tail=200
|
|
exit 1
|
|
|
|
- name: Oude images opruimen (behoud laatste 5)
|
|
if: success()
|
|
run: |
|
|
docker images server-up --format '{{.Tag}} {{.ID}}' \
|
|
| grep -vE '^(latest|release|main) ' \
|
|
| tail -n +6 \
|
|
| awk '{print $2}' \
|
|
| xargs -r docker rmi -f || true
|
|
docker image prune -f
|
|
```
|
|
|
|
### Wat doet een deploy-workflow?
|
|
|
|
1. Code uitchecken in de runner-workspace
|
|
2. Versienummer bepalen (`dev-<sha>` voor dev, `v1.2.3` voor tags)
|
|
3. Code naar `/opt/server-up` synchen via `rsync --delete`
|
|
4. Docker-image bouwen met `docker compose build --pull` en `SU_VERSION` ingebakken
|
|
5. Container herstarten met `docker compose up -d`
|
|
6. Wachten tot de healthcheck groen is (max. ~2 minuten)
|
|
7. Oude images opruimen (behoudt de laatste 5)
|
|
|
|
---
|
|
|
|
## Stap 8 — Handmatig triggeren
|
|
|
|
Elke workflow heeft `workflow_dispatch`, waarmee je hem handmatig start zonder een commit:
|
|
|
|
**Forgejo UI**: Actions → selecteer de workflow → **Run workflow**
|
|
|
|
Handig als je de pipeline opnieuw wilt draaien na een serverherstel of configuratiewijziging.
|
|
|
|
---
|
|
|
|
## Stap 9 — Eerste deploy testen
|
|
|
|
Vanuit je repo op je laptop:
|
|
|
|
```bash
|
|
git checkout dev
|
|
echo "# Deploy test $(date)" >> README.md
|
|
git add README.md
|
|
git commit -m "ci: trigger first deploy"
|
|
git push origin dev
|
|
```
|
|
|
|
In Forgejo: ga naar de **Actions**-tab van je repo. Je ziet de workflow-run starten. Klik erop om de logs live te volgen.
|
|
|
|
Op de server parallel meekijken:
|
|
|
|
```bash
|
|
journalctl -u act_runner -f
|
|
# in een tweede shell:
|
|
docker logs -f server-up
|
|
```
|
|
|
|
Als alles goed gaat: groen vinkje, container draait nieuwe image.
|
|
|
|
---
|
|
|
|
## Stap 10 — Rollback
|
|
|
|
Omdat images getagd worden met de git SHA is rollback eenvoudig:
|
|
|
|
```bash
|
|
cd /opt/server-up
|
|
|
|
# Beschikbare images bekijken
|
|
docker images server-up --format '{{.Tag}}\t{{.CreatedAt}}'
|
|
|
|
# Rollback naar een eerdere SHA — pas aan
|
|
SU_VERSION=dev-abcdef12 docker compose up -d
|
|
```
|
|
|
|
Voor extra zekerheid kun je in de workflow de huidige tag wegschrijven vóór de deploy:
|
|
|
|
```bash
|
|
echo "$(docker inspect server-up --format '{{.Config.Image}}')" \
|
|
> /opt/server-up/.last-good-image
|
|
```
|
|
|
|
---
|
|
|
|
## Stap 11 — Uitbreidingen
|
|
|
|
### CI vóór deploy (tests, lint)
|
|
|
|
Splits in twee jobs zodat tests in isolatie draaien en de deploy alleen bij groen start:
|
|
|
|
```yaml
|
|
jobs:
|
|
test:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
- run: docker build --target build -t server-up:test .
|
|
# voeg je eigen testcommando's toe
|
|
|
|
deploy:
|
|
needs: test
|
|
runs-on: [self-hosted, dev]
|
|
steps:
|
|
# ... zoals hierboven
|
|
```
|
|
|
|
### Nieuwe prod-server toevoegen
|
|
|
|
1. Installeer `act_runner` op de nieuwe server (stap 3)
|
|
2. Maak een nieuw runner-token aan in Forgejo
|
|
3. Registreer met `--labels self-hosted,prod` (stap 4b)
|
|
4. Stel de systemd-service in (stap 5)
|
|
|
|
De `deploy-prod.yml` workflow pikt de nieuwe runner automatisch op bij de volgende push naar `main` of een tag.
|
|
|
|
### Image registry
|
|
|
|
Voor grotere setups wil je niet op de productieserver bouwen. Push de image naar de Forgejo Container Registry (ingebouwd onder **Packages**) vanuit een aparte build-job, en trek alleen op de app-server. Scheelt CPU en disk op productie.
|
|
|
|
---
|
|
|
|
## Beveiligingstips
|
|
|
|
- **Runner draait niet als root** — de `deploy`-user heeft alleen rechten op `/opt/server-up` en is lid van de `docker`-groep. Het Server Up-container zelf draait als root (`user: "0:0"` in compose), dat is een bewuste keuze voor Docker socket-toegang.
|
|
- **Repo-niveau token** is veiliger dan site-niveau — bij een lek heeft een aanvaller niet meteen toegang tot alle repo's.
|
|
- **Branch protection op `main`** — Repo → Settings → Branches → Add Rule. Vereis dat pushes via een PR gaan en de dev-pipeline groen is.
|
|
- **Secrets nooit in compose of git** — zet gevoelige waarden in Forgejo Secrets en schrijf ze in de workflow-step naar `.env`.
|
|
- **Runner-binary updaten** — periodiek bijwerken: nieuwe versie naar `/usr/local/bin/act_runner` schrijven en `systemctl restart act_runner`. Geen herregistratie nodig.
|
|
- **Forgejo zelf** — zet 2FA aan, draai achter een reverse proxy met TLS, configureer fail2ban op de SSH-poort.
|
|
|
|
---
|
|
|
|
## Problemen oplossen
|
|
|
|
| Symptoom | Oorzaak / oplossing |
|
|
|----------|---------------------|
|
|
| Workflow blijft "queued" hangen | Geen runner met het juiste label online. Check `systemctl status act_runner` en of het label (`dev`/`prod`) overeenkomt met `runs-on` in de workflow. |
|
|
| `permission denied` bij Docker | `deploy`-user niet in `docker`-groep, of service gestart vóór die toevoeging — `systemctl restart act_runner`. |
|
|
| `rsync: not found` | `apt install rsync` op de server. |
|
|
| `SU_VERSION ontbreekt` bij handmatige build | Maak `/opt/server-up/.env` aan: `echo "SU_VERSION=dev-handmatig" > /opt/server-up/.env` |
|
|
| Container draait oude code na rebuild | Deploy-directory niet bijgewerkt. Controleer: `docker exec --workdir /app server-up grep -n "trim_blocks" core/boilerplates.py`. Als dit `True` toont, trigger de pipeline handmatig of sync de code zelf: `rsync -a --delete --exclude='.git/' --exclude='.forgejo/' ./ /opt/server-up/` |
|
|
| Boilerplate geeft `yaml: line 5` fout | Zelfde oorzaak als boven — `trim_blocks=True` in de draaiende container. Fix: rebuild na correcte sync. Eerder geïnstalleerde stacks met kapotte compose-bestanden opnieuw installeren via de app-store. |
|
|
| Healthcheck-step faalt altijd | Check `docker compose logs`. Vaak ontbreekt een env-var of klopt een pad niet. |
|
|
| TLS-fout bij registreren | Zet `runner.insecure: true` in config alleen tijdelijk voor self-signed certs. Een geldig certificaat (Let's Encrypt) is de structurele oplossing. |
|