9.2 KiB
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. Tijdens de installatie kun je alle standaardinstellingen accepteren.
Controleer daarna of het werkt:
git --version
Stap 2 — Pakketten installeren op de server
Log in op de server als root of met sudo. Installeer de benodigde pakketten:
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.
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:
docker --version
docker compose version
Draai je Ubuntu in plaats van Debian? Vervang beide keren
debiandoorubuntuin 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:
useradd -m -s /bin/bash git-user
usermod -aG docker git-user
Controleer of het gelukt is:
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.
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:
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:
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:
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:
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:
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:
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.
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.
# 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:
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.
# 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:
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:
- Ga naar je repository → Actions
- Klik op de workflow die je wilt starten
- Klik rechtsboven op Run workflow
Iets terugdraaien
Elk gebouwd image krijgt een versietag mee. Je kunt altijd terug:
# 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:
systemctl start act_runner
systemctl status act_runner
Fout: rsync: command not found
apt install -y rsync
Fout: Cannot find node in PATH
apt install -y nodejs
Fout: permission denied bij rsync
De runner-gebruiker heeft geen schrijfrechten op de deploy-map:
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:
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:
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
git branch # toont welke branch actief is
git checkout dev # wissel naar dev
git checkout main # wissel naar main
Bestanden worden niet meegenomen
git status # toont welke bestanden nog niet zijn toegevoegd
git add . # voeg alles toe