- Documentatie

Documentatie Deploy Workflow

Deze server gebruikt Git uitsluitend als transportmechanisme om statische HTML (MkDocs output) te publiceren.

Er wordt geen historie bewaard op de server: elke push vervangt de vorige versie volledig.

---

Architectuur

Lokaal (Mac)

Twee directories:

~/documentatie            # bron (mkdocs.yml + docs/*.md)
~/documentatie-publish    # alleen HTML output (transport repo)

De documentatie-publish repo bevat alleen de gegenereerde site en wordt telkens overschreven.

Server

/srv/git/documentatie.git        # bare repo (alleen ontvangstpunt)
/var/www/html/documentatie       # live gepubliceerde site

De bare repo wordt niet gebruikt als broncontrole, alleen om pushes te ontvangen en een deploy te triggeren.

---

MkDocs configuratie

In ~/documentatie/mkdocs.yml:

site_dir: ../documentatie-publish

Hierdoor schrijft MkDocs direct naar de publish-repo.

---

Publish Script (Mac)

Bestand: ~/documentatie/publish.sh

#!/usr/bin/env bash
set -euo pipefail

SRC="$HOME/documentatie"
PUB="$HOME/documentatie-publish"
REMOTE_URL="ssh://pi@vpn:/srv/git/documentatie.git"

echo "==> Build MkDocs into publish repo"
cd "$SRC"
mkdocs build

echo "==> Prepare publish repo"
cd "$PUB"

git init -q

git switch main 2>/dev/null || git switch -c main

git remote set-url stage "$REMOTE_URL" 2>/dev/null || git remote add stage "$REMOTE_URL"

echo "==> Create single-commit snapshot"

git update-ref -d refs/heads/main 2>/dev/null || true
git switch --orphan main

git reset --mixed

git add -A

git diff --cached --quiet && { echo "No changes to publish."; exit 0; }

git commit -m "publish $(date -u +%Y-%m-%dT%H:%M:%SZ)"

echo "==> Force-push to server"

git push --force stage main

COUNT_FILE="$PUB/.publish-count"
COUNT=$(cat "$COUNT_FILE" 2>/dev/null || echo 0)
COUNT=$((COUNT+1))
echo "$COUNT" > "$COUNT_FILE"

if (( COUNT % 20 == 0 )); then
    echo "Running lightweight git gc..."
    git gc --prune=now
fi

Deze methode zorgt ervoor dat de publish-repo altijd maar één commit bevat.

---

Server Setup

Webroot voorbereiden

sudo mkdir -p /var/www/html/documentatie
sudo chown -R root:deploy /var/www/html/documentatie
sudo chmod -R 2775 /var/www/html/documentatie

---

Bare Repo GC gedrag aanpassen

REPO=/srv/git/documentatie.git

git --git-dir="$REPO" config gc.pruneExpire now
git --git-dir="$REPO" config gc.reflogExpire now
git --git-dir="$REPO" config gc.reflogExpireUnreachable now

Hiermee worden oude pushes onmiddellijk verwijderd.

---

post-receive Hook

Bestand:

/srv/git/documentatie.git/hooks/post-receive

#!/bin/bash
set -euo pipefail

REPO="/srv/git/documentatie.git"
TARGET="/var/www/html/documentatie"

umask 002

TMPDIR="$(mktemp -d)"
trap 'rm -rf "$TMPDIR"' EXIT

while read -r oldrev newrev refname; do
  [[ "$refname" == "refs/heads/main" ]] || continue

  echo "==> Deploy $newrev -> $TARGET" >&2

  git --git-dir="$REPO" archive "$newrev" | tar -x -C "$TMPDIR"

  mkdir -p "$TARGET"

  rsync -rl --delete --no-times --omit-dir-times \
    "$TMPDIR"/ \
    "$TARGET"/

  echo "==> Deploy done" >&2

  git --git-dir="$REPO" reflog expire --expire=now --all || true
  git --git-dir="$REPO" gc --prune=now || true

done

Maak uitvoerbaar:

chmod +x /srv/git/documentatie.git/hooks/post-receive

---

Resultaat

Elke deploy is:

mkdocs build → single snapshot commit → force push → server export → oude versie weg

Server bewaart dus:

• geen historie
• geen bronbestanden
• alleen de actuele statische site

---

Filosofie van deze Setup

Deze configuratie behandelt Git als:

betrouwbare transportlaag + deploy trigger

Niet als versiebeheer op de server.

Alle broncontrole blijft lokaal.