server-up/docs/synchroniseren.md

# Code synchroniseren via Forgejo

Dit is hoe je code van je eigen apparaat automatisch op een server krijgt via Forgejo. Je pusht naar een branch, en de server haalt de wijzigingen zelf op en herstart de applicatie. Je hoeft nooit handmatig in te loggen op de server om iets bij te werken.

Als voorbeeld gebruik ik Server Up, maar de werkwijze is voor elke applicatie hetzelfde.

---

## Hoe het werkt

Je werkt met twee branches in je repository:

| Branch | Doel | Wat er gebeurt bij een push |
|--------|------|-----------------------------|
| `dev`  | Testen en ontwikkelen | De dev-server wordt automatisch bijgewerkt |
| `main` | Stabiele versie voor eindgebruikers | De prod-server wordt automatisch bijgewerkt |

Jij pusht code naar Forgejo. Forgejo start automatisch een workflow (een reeks stappen). Die workflow draait op de server zelf via een kleine achtergrondservice genaamd `act_runner`. De server haalt de code op, bouwt een nieuw Docker-image en herstart de applicatie.

---

## Stap 1 — Git installeren op je eigen apparaat

Git heb je nodig om code te beheren en naar Forgejo te pushen.

Download en installeer Git via [git-scm.com](https://git-scm.com). Tijdens de installatie kun je alle standaardinstellingen accepteren.

Controleer daarna of het werkt:

```bash
git --version
```

---

## Stap 2 — Pakketten installeren op de server

Log in op de server als root of met `sudo`. Installeer de benodigde pakketten:

```bash
apt update
apt install -y git rsync nodejs
```

Toelichting:
- **git** — de pipeline checkt de repository uit op de server
- **rsync** — kopieert de bestanden naar de juiste map op de server
- **nodejs** — vereist door `actions/checkout`, de stap die de code ophaalt

---

## Stap 3 — Docker installeren op de server

Docker is nodig om de applicatie te draaien en te bouwen.

```bash
apt install -y ca-certificates curl gnupg
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

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

Controleer of Docker werkt:

```bash
docker --version
docker compose version
```

> Draai je Ubuntu in plaats van Debian? Vervang beide keren `debian` door `ubuntu` in bovenstaande commando's.

---

## Stap 4 — Runner-gebruiker aanmaken op de server

De pipeline draait niet als root maar als een aparte gebruiker. Maak die aan en geef hem toegang tot Docker:

```bash
useradd -m -s /bin/bash git-user
usermod -aG docker git-user
```

Controleer of het gelukt is:

```bash
groups git-user
```

Je ziet `git-user docker` in de uitvoer.

---

## Stap 5 — Act_runner installeren op de server

`act_runner` is de achtergrondservice die de Forgejo-workflows uitvoert.

```bash
VERSION=6.2.2
ARCH=amd64   # gebruik 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
```

Maak de benodigde mappen aan:

```bash
mkdir -p /etc/act_runner /var/lib/act_runner
chown git-user:git-user /var/lib/act_runner
act_runner generate-config > /etc/act_runner/config.yaml
chown root:git-user /etc/act_runner/config.yaml
chmod 640 /etc/act_runner/config.yaml
```

---

## Stap 6 — Runner registreren in Forgejo

### Token ophalen

Ga in Forgejo naar je repository → **Settings → Actions → Runners → Create new Runner**. Kopieer het token.

### Registreren

**Voor een dev-server:**

```bash
sudo -u git-user 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
'
```

**Voor een prod-server:**

```bash
sudo -u git-user bash -c '
cd /var/lib/act_runner && \
act_runner register \
  --no-interactive \
  --instance https://jouw-forgejo-url \
  --token JOUW_TOKEN \
  --name prod-server \
  --labels self-hosted,prod \
  --config /etc/act_runner/config.yaml
'
```

Controleer in Forgejo onder **Settings → Actions → Runners** — de runner verschijnt als **Idle**.

---

## Stap 7 — Runner instellen als achtergrondservice

Zodat de runner automatisch start bij een herstart van de server:

```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=git-user
Group=git-user
WorkingDirectory=/var/lib/act_runner
ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now act_runner
systemctl status act_runner
```

De runner is nu actief en start automatisch opnieuw na een herstart.

---

## Stap 8 — Deploy-map aanmaken op de server

De pipeline kopieert de code naar een vaste map. Maak die eenmalig aan:

```bash
mkdir -p /opt/docker/server-up
chown git-user:git-user /opt/docker/server-up
```

---

## Stap 9 — Repository klonen op je eigen apparaat

Als je de repository nog niet lokaal hebt staan:

```bash
git clone https://jouw-forgejo-url/gebruiker/server-up.git
cd server-up
```

---

## Stap 10 — Dev-branch aanmaken

Doe dit één keer. Als de branch al bestaat, sla je deze stap over.

```bash
git checkout -b dev
git push -u origin dev
```

De pipeline voor de dev-server is nu gekoppeld aan deze branch.

---

## Dagelijks gebruik: wijzigingen naar de dev-server sturen

Dit doe je elke keer als je iets hebt aangepast en wilt testen.

```bash
# Zorg dat je op de dev-branch zit
git checkout dev

# Voeg je gewijzigde bestanden toe
git add .

# Maak een commit met een korte omschrijving
git commit -m "Omschrijving van je wijziging"

# Push naar Forgejo
git push origin dev
```

De pipeline start automatisch. Binnen een paar minuten draait de dev-server de nieuwe versie.

---

## Controleren of de pipeline gelukt is

Ga in Forgejo naar je repository en klik op **Actions**. Je ziet de pipeline-run staan:

- **Groen vinkje** — gelukt, de server draait de nieuwe versie
- **Rood kruis** — er is iets misgegaan, klik erop om de logs te zien

Je kunt ook direct op de server controleren:

```bash
docker inspect --format '{{.State.Health.Status}}' server-up
```

`healthy` betekent dat alles goed draait.

---

## Stabiele versie naar de prod-server sturen

Doe dit alleen als de versie op dev goed werkt.

```bash
# Schakel over naar main
git checkout main

# Haal de laatste versie van main op
git pull origin main

# Voeg alles uit dev samen met main
git merge dev

# Push naar Forgejo
git push origin main
```

De prod-server wordt automatisch bijgewerkt.

---

## Een versienummer vastleggen (optioneel)

Wil je een officieel versienummer aan een release hangen:

```bash
git checkout main
git tag v1.2.3
git push origin v1.2.3
```

Het versienummer `v1.2.3` wordt ingebakken in het Docker-image en is zichtbaar in de applicatie.

---

## Pipeline handmatig opnieuw starten

Wil je de pipeline herhalen zonder iets te wijzigen:

1. Ga naar je repository → **Actions**
2. Klik op de workflow die je wilt starten
3. Klik rechtsboven op **Run workflow**

---

## Iets terugdraaien

Elk gebouwd image krijgt een versietag mee. Je kunt altijd terug:

```bash
# Bekijk beschikbare versies
docker images server-up --format '{{.Tag}}\t{{.CreatedAt}}'

# Start de container met een eerdere versie
cd /opt/docker/server-up
SU_VERSION=dev-abcdef12 docker compose up -d
```

Vervang `dev-abcdef12` door de versietag die je terug wilt zetten.

---

## Problemen oplossen

**De pipeline start niet**
Ga in Forgejo naar **Settings → Actions → Runners**. Als de runner offline is, log dan in op de server en voer uit:
```bash
systemctl start act_runner
systemctl status act_runner
```

**Fout: `rsync: command not found`**
```bash
apt install -y rsync
```

**Fout: `Cannot find node in PATH`**
```bash
apt install -y nodejs
```

**Fout: `permission denied` bij rsync**
De runner-gebruiker heeft geen schrijfrechten op de deploy-map:
```bash
chown -R git-user:git-user /opt/docker/server-up
```

**Fout: `usermod: command not found`**
Je bent niet ingelogd als root. Zet `sudo` voor het commando:
```bash
sudo usermod -aG docker git-user
```

**Fout: `No such image` bij docker tag**
Docker Compose bouwt het image als `latest`. De workflow moet `latest` taggen als de versie, niet andersom. Controleer de build-stap in `.forgejo/workflows/deploy.yml` — die moet er zo uitzien:
```yaml
docker compose build --pull
docker tag server-up:latest "server-up:${VERSION}"
docker tag server-up:latest "server-up:${CHANNEL}"
```

**Je staat op de verkeerde branch**
```bash
git branch           # toont welke branch actief is
git checkout dev     # wissel naar dev
git checkout main    # wissel naar main
```

**Bestanden worden niet meegenomen**
```bash
git status           # toont welke bestanden nog niet zijn toegevoegd
git add .            # voeg alles toe
```