310 lines
7.7 KiB
Markdown
310 lines
7.7 KiB
Markdown
# 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/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:
|
||
|
||
```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! 🚀
|