docs: Complete setup guide for Staging/Production pipeline with all steps
This commit is contained in:
Sebastian Serfling
@@ -1,22 +1,308 @@
|
|||||||
# Webseite Stines – Hugo + Terraform GitOps
|
# Webseite Stines – Hugo + Terraform GitOps Pipeline
|
||||||
|
|
||||||
## Workflow
|
Eine vollautomatisierte Deployment-Pipeline mit Staging und Production Umgebungen.
|
||||||
|
|
||||||
### Staging (automatisch bei Push auf `main`)
|
**Workflow:**
|
||||||
- Terraform prüft ob Staging-LXC existiert → erstellt ihn falls nicht
|
```
|
||||||
- Hugo baut die Site
|
Push → Gitea Actions → Terraform (Staging) → Hugo Build → Deploy
|
||||||
- Deploy auf `staging.stines.de`
|
Tag → Gitea Actions → Hugo Build → Deploy auf Production
|
||||||
|
|
||||||
### Production (bei Git Tag `v*`)
|
|
||||||
```bash
|
|
||||||
git tag v1.0.0
|
|
||||||
git push origin v1.0.0
|
|
||||||
```
|
```
|
||||||
- Hugo baut die Site
|
|
||||||
- Deploy auf `stines.de`
|
|
||||||
|
|
||||||
## Lokale Entwicklung
|
---
|
||||||
|
|
||||||
|
## 🚀 Quick Start (lokale Entwicklung)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd hugo
|
cd hugo
|
||||||
hugo server -D
|
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! 🚀
|
||||||
|
|||||||
Reference in New Issue
Block a user