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)

```bash
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:**

```bash
# Binary herunterladen
mkdir -p /opt/gitea-runner && cd /opt/gitea-runner
wget https://dl.gitea.com/act_runner/latest/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:

```bash
# 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:

```bash
# 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):
```bash
# 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):

```bash
# Ä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):

```bash
# 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:**

```bash
# 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
```bash
systemctl restart gitea-runner
journalctl -u gitea-runner -f     # Live Logs
```

### SSH-Zugriff schlägt fehl
```bash
# 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
```bash
# 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
```bash
# 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! 🚀