Webseite_Stines/README.md

Webseite Stines – Hugo + Terraform GitOps Pipeline

Eine vollautomatisierte Deployment-Pipeline mit Staging und Production Umgebungen.

Workflow:

Push → Gitea Actions → Terraform (Staging) → Hugo Build → Deploy
Tag   → Gitea Actions → Hugo Build → Deploy auf Production

---

🚀 Quick Start (lokale Entwicklung)

cd hugo
hugo server -D    # Öffnet http://localhost:1313

---

📋 Nächste Schritte – Einmaliges Setup

1️⃣ Gitea Runner installieren

Der Runner führt die Workflows aus. Wähle einen Host (Proxmox-Node, dein PC, oder eine dedizierte VM):

Auf deinem System:

# Binary herunterladen
mkdir -p /opt/gitea-runner && cd /opt/gitea-runner
wget https://dl.gitea.com/act_runner/0.6.1/act_runner-0.6.1-linux-amd64
mv act_runner-0.6.1-linux-amd64 act_runner-linux-amd64
chmod +x act_runner-linux-amd64

# Runner registrieren
# Token holst du hier: https://gitlab.stines.de/sebastian.serfling/Webseite_Stines/settings/actions/runners
./act_runner-linux-amd64 register \
  --instance https://gitlab.stines.de \
  --token DEIN_RUNNER_TOKEN \
  --name webseite-runner \
  --labels ubuntu-latest \
  --no-interactive

# Als Systemd-Service einrichten
sudo tee /etc/systemd/system/gitea-runner.service > /dev/null <<EOF
[Unit]
Description=Gitea Runner
After=network.target

[Service]
WorkingDirectory=/opt/gitea-runner
ExecStart=/opt/gitea-runner/act_runner-linux-amd64 daemon
Restart=always
User=$(whoami)

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now gitea-runner
sudo systemctl status gitea-runner

2️⃣ SSH-Key für Deployment generieren

Der Runner braucht SSH-Zugriff auf deine Production/Staging VMs:

# Key generieren
ssh-keygen -t ed25519 -C "gitea-deploy" -f ~/.ssh/gitea_deploy -N ""

# Public Key auf deine Hugo-VMs kopieren (für user 'deploy')
ssh-copy-id -i ~/.ssh/gitea_deploy.pub deploy@STAGING_IP
ssh-copy-id -i ~/.ssh/gitea_deploy.pub deploy@PROD_IP

# Private Key in Base64 für Gitea Secret
cat ~/.ssh/gitea_deploy | base64 -w0

3️⃣ Secrets in Gitea hinzufügen

Gehe zu: Repo → Settings → Secrets und erstelle diese:

Secret	Wert
PROXMOX_HOST	https://192.168.x.x:8006/api2/json (deine Proxmox URL)
PROXMOX_TOKEN_ID	terraform@pve!deploy (Proxmox API Token)
PROXMOX_TOKEN_SECRET	Dein Proxmox Token Secret
PROXMOX_NODE	z.B. pve (Node wo Staging-LXC erstellt wird)
DEPLOY_SSH_KEY	Base64-codierter Private Key (aus Schritt 2)
STAGING_IP	z.B. 192.168.100.10
STAGING_GW	z.B. 192.168.100.1
PROD_IP	z.B. 192.168.50.20

4️⃣ Proxmox API Token erstellen

Falls du das noch nicht gemacht hast:

# Auf deinem Proxmox-Host:
# Realm → PAM Users → root → Create API Token
# Oder via CLI (als root):
pveum user add terraform@pve
pveum aclmod / -user terraform@pve -role Administrator

5️⃣ VM Templates vorbereiten

Die Staging-VM wird automatisch erstellt. Production-VM musste manuell stehen.

Staging-VM (wird by Terraform created):

• Wird automatisch im Workflow erstellt
• VM-ID: 200 (konfigurierbar in terraform/main.tf)
• OS-Template: Debian 12

Production-VM (manuell vorbereiten):

# Auf der Prod-VM:
sudo apt install -y nginx hugo git rsync

# Deploy-User erstellen
sudo useradd -m -s /bin/bash deploy
sudo -u deploy mkdir -p ~/.ssh
sudo chmod 700 /home/deploy/.ssh

# Public Key von Schritt 2 eintragen:
echo "DEIN_PUBLIC_KEY" | sudo tee -a /home/deploy/.ssh/authorized_keys

# Nginx konfigurieren
sudo mkdir -p /var/www/html
sudo chown -R deploy:deploy /var/www/html

---

🔄 Workflows

📝 .gitea/workflows/staging.yml

Trigger: Jeder Push auf main

✓ Checkout Repo
✓ Terraform init & apply (erstellt Staging-LXC falls nicht da)
✓ Hugo build in ./hugo
✓ rsync public/ → staging-vm:/var/www/html/

Unter der Haube:

• Terraform prüft: Gibt es bereits einen LXC mit ID 200 auf dem Node?
• Falls nein: LXC erstellen, Netzwerk konfigurieren, warten bis Boot
• Falls ja: Skippen, direkt zum Hugo Build
• Danach: Hugo baut den Static-Output
• Deployment: rsync synchronisiert nur die Unterschiede

🏆 .gitea/workflows/production.yml

Trigger: Nur bei Git Tags (v*)

✓ Checkout Repo
✓ Hugo build in ./hugo
✓ rsync public/ → prod-vm:/var/www/html/

Kein Terraform hier – Production-VM läuft stabil, muss nicht recreated werden.

---

📤 Deployment Flow

Staging deployen (sofort):

# Änderungen machen
nano hugo/content/_index.md

# Commit & Push
git add .
git commit -m "feat: neue Sektion hinzugefügt"
git push origin main

# ↓ Automatisch:
# - Runner lädt Repo
# - Terraform erstellt/prüft Staging-LXC
# - Hugo baut
# - Deploy → staging.stines.de (nach ~2 Minuten live)

Production deployen (kontrolliert):

# Nachdem Staging getestet wurde:
git tag v1.0.1
git push origin v1.0.1

# ↓ Automatisch:
# - Hugo baut
# - Deploy → stines.de (nach ~1 Minute live)

---

🔍 Debugging & Logs

Workflow-Logs anschauen:

1. Gehe zu: Repo → Actions
2. Klick auf den Workflow-Run
3. Expandiere die Step-Details

Runner manuell testen:

# Test ob Runner läuft:
systemctl status gitea-runner

# SSH zu Staging testen:
ssh -i ~/.ssh/gitea_deploy deploy@STAGING_IP "ls -la /var/www/html/"

# Manuelle Hugo Build (lokal):
cd hugo && hugo --minify

---

📁 Verzeichnis-Struktur

Webseite_Stines/
├── .gitea/
│   └── workflows/
│       ├── staging.yml         # Staging: Terraform + Hugo Build + Deploy
│       └── production.yml       # Production: Hugo Build + Deploy
├── hugo/
│   ├── config.toml
│   ├── content/                # Deine Inhalte
│   ├── themes/
│   ├── static/
│   └── public/                 # (in .gitignore) – wird vom Build generiert
├── terraform/
│   ├── main.tf                 # Proxmox Provider + LXC Ressource
│   ├── variables.tf
│   ├── outputs.tf
│   └── terraform.tfvars        # (in .gitignore) – braucht du nur lokal
├── .gitignore                  # hugo/public/, *.tfvars, etc.
└── README.md                   # Diese Datei

---

🛠 Troubleshooting

Runner läuft nicht

systemctl restart gitea-runner
journalctl -u gitea-runner -f     # Live Logs

SSH-Zugriff schlägt fehl

# Test SSH-Key:
ssh -i ~/.ssh/gitea_deploy -vvv deploy@STAGING_IP whoami

# Key in Gitea überprüfen:
cat ~/.ssh/gitea_deploy | base64 -w0   # Muss mit Secret Match

Terraform-Fehler im Workflow

# Proxmox-Credentials testen:
curl -H "Authorization: PVEAPIToken=terraform@pve!deploy=DEIN_TOKEN_SECRET" \
  https://192.168.x.x:8006/api2/json/nodes

Hugo Build schlägt fehl

# Lokal testen:
cd hugo && hugo --minify --verbose

---

📚 Weitere Informationen

• Hugo Docs: https://gohugo.io/documentation/
• Terraform Proxmox: https://github.com/Telmate/proxmox
• Gitea Actions: https://docs.gitea.io/en-us/actions/
• Git Tags erklärung: git tag --help

---

✅ Checkliste zum Go-Live

• Gitea Runner installiert und läuft (systemctl status gitea-runner)
• SSH-Keys generiert und auf VMs deployed
• Alle Secrets in Gitea hinterlegt
• Production-VM manuell vorbereitet (nginx, deploy-user, SSH-Key)
• Test-Push auf main durchgeführt → Staging aktiv?
• Test-Tag gesetzt (git tag v0.0.1 && git push origin v0.0.1) → Production aktiv?
• Domains DNS konfiguriert (staging.stines.de, stines.de)

---

Bei Fragen oder Problemen: SSH-Key überprüfen, Logs anschauen, SSH-Test machen.

Happy Deploying! 🚀