Ga naar inhoud

🚀 Gitea Setup & Proxmox GitOps (Back-up & Herstel)

Dit projectverslag documenteert de volledige realisatie van een GitOps-infrastructuur binnen het homelab. Door het opzetten van een lichtgewicht, onafhankelijke Gitea-omgeving automatiseren we de dagelijkse back-up van de cruciale Proxmox-hostconfiguraties (/etc/pve/). Dit garandeert een volledige rampen-herstelprocedure (Disaster Recovery) binnen 5 minuten bij schijf- of hardware-uitval.

ℹ️ Introductie

Dit document fungeert als de centrale 'single point of truth' voor het Proxmox-cluster (Lenovo ThinkStations) en de standalone server (AOOSTAR met TrueNAS SCALE / RustFS). Naast de standaard back-ups van virtuele machines via PBS, is het beveiligen van de Proxmox-hosts zelf een kritieke schakel. Deze specifieke Git-architectuur biedt daarvoor de meest veerkrachtige oplossing.

📦 Deel 1: Gitea Installatie & Configuratie

Gitea is gekozen vanwege zijn extreem lichtgewicht karakter en lage resource-overhead in vergelijking met zware alternatieve Git-omgevingen.

1. De LXC Container Aanmaken

  1. Open de Proxmox Web UI en klik op Create CT.
  2. General: Vink het vakje Unprivileged container aan. Geef de container een naam (bijv. gitea) en stel een veilig root-wachtwoord in.
  3. Template: Selecteer een schone Debian 12 of Debian 13 template.
  4. Resources: Wijs minimaal 10 GB tot 20 GB schijfruimte toe, 1-2 CPU cores en 1024 MB RAM.
  5. Network: Koppel aan de standaard bridge (vmbr0) en wijs een statisch IP-adres toe (of configureer DHCP).
  6. Start de container op.

2. Systeem Voorbereiden & Gitea Binary Downloaden

Log via de Proxmox console in op de Gitea LXC als root en voer de volgende commando's uit: 

# Systeem updaten en basispakketten installeren
apt update && apt upgrade -y
apt install git sqlite3 gnupg2 -y

# De Git-systeemgebruiker en thuismap handmatig aanmaken
adduser --system --shell /bin/bash --gecos 'Git Version Control' --group --disabled-password git
mkdir -p /home/git/.ssh
chown -R git:git /home/git
chmod 700 /home/git/.ssh

# Gitea binary downloaden en verplaatsen naar het systeempad
wget -O gitea https://dl.gitea.com/gitea/1.27.0/gitea-1.27.0-linux-amd64
mv gitea /usr/local/bin/gitea
chmod +x /usr/local/bin/gitea

# Gitea datamappen aanmaken en rechten dichttimmeren
mkdir -p /var/lib/gitea/{custom,data,log}
chown -R git:git /var/lib/gitea/
chmod -R 750 /var/lib/gitea/
mkdir /etc/gitea
chown root:git /etc/gitea
chmod 770 /etc/gitea

3. De Achtergrondservice (Systemd) & Container SSH Inrichten

Maak het systemd servicebestand aan binnen de container: 

nano /etc/systemd/system/gitea.service
Plak de volgende configuratie in het bestand: 
[Unit]
Description=Gitea (Git with a cup of tea)
After=network.target

[Service]
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea/
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea

[Install]
WantedBy=multi-user.target
Sla op met Ctrl + O en sluit af met Ctrl + X.

Pas vervolgens de SSH-daemon aan om de Gitea SSH-sleutels correct te herkennen: 

nano /etc/ssh/sshd_config
Voeg de volgende regels toe helemaal onderaan het bestand: 
PubkeyAuthentication yes
AuthorizedKeysFile .ssh/authorized_keys /home/git/.ssh/authorized_keys
Herlaad de configuratie en start de services direct op: 
systemctl daemon-reload
systemctl enable --now gitea
systemctl restart sshd

4. De Web-Installatie Afronden

  1. Open je browser en navigeer naar http://[IP-ADRES-VAN-GITEA]:3000.
  2. Database Type: Selecteer SQLite3.
  3. Gitea Base URL: Verander dit naar het daadwerkelijke IP-adres van je Gitea container.
  4. Scroll naar beneden, klap de Administrator Account Settings uit en maak je admin-gebruiker aan. Vink hierbij de optie aan om de instance volledig privé te maken voor maximale homelab-beveiliging.
  5. Klik op Install Gitea.

🌐 Deel 2: Proxmox Host Integratie & Back-up Automatisering

Nu Gitea draait, gaan we de Proxmox-host (bijv. pve1) koppelen om de clusterbestanden automatisch te back-uppen.

1. SSH Handshake Opzetten

Log via SSH in op je Proxmox Host (pve1). Genereer een veilige SSH-sleutel als je deze nog niet hebt: 

ssh-keygen -t rsa -b 4000
Druk driemaal op Enter om de standaardwaarden te accepteren zonder wachtwoordfrase.

Toon en kopieer de openbare sleutel: 

cat ~/.ssh/id_rsa.pub
In de Gitea Web UI: 1. Klik rechtsboven op je profiel-icoon ➔ Instellingen. 2. Navigeer naar SSH / GPG sleutels ➔ Sleutel toevoegen. 3. Geef de sleutel de naam Proxmox Host, plak de gekopieerde sleutel erin en sla op.

2. De Repository Aanmaken & Eerste Push Uitvoeren

  1. Klik in Gitea rechtsboven op het + icoon ➔ Nieuwe repository.
  2. Repositorynaam: proxmox-backup.
  3. Vink het vakje Privé aan.
  4. Klik op Repository aanmaken.

Ga terug naar de terminal van je Proxmox Host en voer de initialisatie uit: 

cd /etc/pve
git init

# Git identiteit configureren
git config --global user.email "[email protected]"
git config --global user.name "Proxmox Host"

# De Gitea repository koppelen (Vervang [GITEA_IP] door het echte IP)
git remote add origin git@[GITEA_IP]:spruitmans/proxmox-backup.git

# Bestanden toevoegen, indexeren en pushen
git add .
git commit -m "Initial automated Proxmox backup"
git branch -M main
git push -u origin main
Typ yes als de terminal vraagt om de host-key te vertrouwen.

3. Back-ups Automatiseren via een Nachtelijke Cronjob

We richten een script in dat elke nacht om 02:00 uur controleert op wijzigingen in de Proxmox-configuratie en deze automatisch naar Gitea pusht.

Maak het back-upscript aan op de Proxmox-host: 

nano /usr/local/bin/proxmox-git-backup.sh
Plak de volgende logica in het bestand: 
#!/bin/bash
cd /etc/pve
git add .
if ! git diff-index --quiet HEAD --; then
    git commit -m "Automated backup on $(date +'%Y-%m-%d %H:%M')"
    git push origin main
fi
Maak het script uitvoerbaar: 
chmod +x /usr/local/bin/proxmox-git-backup.sh
Voeg het script toe aan de systeem-cron: 
crontab -e
Plak de volgende regel helemaal onderaan het crontab-bestand: 
0 2 * * * /usr/local/bin/proxmox-git-backup.sh > /dev/null 2>&1

🛡 Deel 3: Rampen-Herstel (Disaster Recovery)

Mocht je Proxmox-host een catastrofale hardware- of schijffout ervaren, dan herstel je hiermee al je netwerkinstellingen, cluster-setups en VM-definities binnen 5 minuten.

1. Schone Proxmox Basisinstallatie

  1. Installeer Proxmox VE opnieuw op de machine met de officiële ISO.
  2. Cruciaal: Gebruik tijdens de installatie exact dezelfde Hostnaam (bijv. pve1) en exact hetzelfde IP-adres als voorheen. Proxmox-configuraties zijn intern namelijk hard gekoppeld aan de hostnaam.

2. SSH Toegang Herstellen in Gitea

Omdat het een gloednieuwe installatie is, heeft de host een nieuwe SSH-sleutel nodig om te authenticeren bij Gitea. 1. Log in op de nieuwe Proxmox host via SSH. 2. Genereer een nieuwe sleutel: ssh-keygen -t rsa -b 4000 (3x Enter). 3. Toon de sleutel: cat ~/.ssh/id_rsa.pub 4. Verwijder de oude verlopen Proxmox-sleutel uit je Gitea-profielinstellingen en voeg deze nieuwe openbare sleutel toe.

3. De Back-up Terugzetten en Toepassen

Omdat de map /etc/pve/ in Proxmox gebruikmaakt van een uniek, virtueel cluster-bestandssysteem (pmxcfs), kun je een Git-repository hier niet direct overheen clonen. We downloaden de back-up daarom eerst in een tijdelijke map en kopiëren de bestanden daarna op hun plek.

Voer deze commando's uit op de nieuwe Proxmox-host: 

# 1. Download de back-up tijdelijk naar de /tmp directory (Vervang [GITEA_IP])
cd /tmp
git clone git@[GITEA_IP]:spruitmans/proxmox-backup.git

# 2. Stop de Proxmox cluster-service tijdelijk om bestandssluitingen te voorkomen
systemctl stop pve-cluster

# 3. Kopieer alle core configuratiebestanden terug naar de native pve map
cp -r /tmp/proxmox-backup/* /etc/pve/

# 4. Start de Proxmox cluster-service weer op
systemctl start pve-cluster

🏁 Deel 4: Afronding van het Herstel

Zodra de pve-cluster service start, leest Proxmox de teruggezette configuratiebestanden onmiddellijk uit. Vernieuw je Proxmox Web UI in de browser en je zult zien dat: * Alle eerdere opslagpools (NFS/SMB naar TrueNAS) direct weer zijn gekoppeld en verbonden. * Al je virtuele machines en containers (zoals poort 112, 200, 203) direct weer in de mappenlijst staan met hun originele instellingen.

Je netwerk- en systeempaden zijn nu volledig hersteld. Je kan nu de reguliere Proxmox GUI gebruiken om de virtuele schijven van de VM's terug te zetten vanaf de TrueNAS SCALE / RustFS (aws S3 bucket) back-up opslag!

🚀 Deel 5: Geavanceerde GitOps — Automatische Website & Blog Deployment

Naast het back-uppen van systeembestanden gebruik ik mijn Gitea-infrastructuur nu als de centrale motor achter deze complete documentatiewebsite en tech-blog (homelab.patad.nl). Elke keer als ik op mijn beheer-pc een artikel aanpas of toevoeg en dit naar Gitea push, bouwt de TrueNAS Gitea Action Runner de site in een fractie van een seconde en zet deze direct live op de Virtualmin-webserver.

🔐 De Beveiliging: SSH Keys & Geheimen (Secrets)

Om de pipeline volledig handloos en veilig te laten communiceren met Virtualmin, maken we gebruik van een beveiligde SSH-sleutel handshake (Public/Private Key pair). 1. De Private Key: Deze blijft 100% geheim en is veilig opgeslagen binnen Gitea als een Action Secret genaamd FTP_PASSWORD. 2. De Public Key: Deze openbare sleutel is toegevoegd aan de ~/.ssh/authorized_keys map van de homelab gebruiker op de Virtualmin-server. Hierdoor kan de TrueNAS-runner via de SCP-pipeline (Secure Copy) direct inloggen op poort 22 zonder dat er ooit een fysiek wachtwoord over het netwerk wordt gestuurd.

Mijn Afbeelding

💻 Lokale PowerShell Gids: Werkmap Inrichten op de Beheer-PC

Om snel nieuwe Markdown-bestanden, afbeeldingen of thema-aanpassingen door te voeren vanaf je Windows-beheeromgeving, gebruiken we de onderstaande PowerShell-commando's. Dit zorgt voor een mathematisch perfecte mappenstructuur die naadloos aansluit op de backend van MkDocs.

Kopieer en plak dit gecombineerde commando in je lokale PowerShell-venster om de mappenstructuur in één keer foutloos op te zetten of te controleren:

# Navigeer naar de homelab git-omgeving
cd "C:\Users\gebruiker\documents\proxmox-homelab"

# Controleer en maak de vereiste mappenstructuur aan
@("docs", "docs/images", "docs/projecten", "docs/lxc", "docs/vms", "theme") | ForEach-Object {
    if (-not (Test-Path \$_)) {
        New-Item -ItemType Directory -Path \$_ -Force
    }
}



# Toon de actuele status van de lokale Git-werkmap
git status

🏁 De Dagelijkse VS Code Workflow

Zodra de mappenstructuur via PowerShell staat, is het bijwerken van de website een fluitje van een cent: 1. Open de map proxmox-homelab in VS Code [5.5]. 2. Schrijf of bewerk je .md gidsen in de juiste submap (bijv. docs/projecten/) [5.5]. 3. Open de ingebouwde Git-tab links (Source Control), typ een kort commit-bericht en klik op ✓ Commit & Push.

De TrueNAS-runner schiet direct in de actie, compileert de code via mkdocs build, en overschrijft de public_html/ map op Virtualmin via de beveiligde SSH-tunnel op poort 22 [5.5]. Jouw documentatie staat binnen 20 seconden live, foutloos en volledig geautomatiseerd!