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`)
|
||||
- Terraform prüft ob Staging-LXC existiert → erstellt ihn falls nicht
|
||||
- Hugo baut die Site
|
||||
- Deploy auf `staging.stines.de`
|
||||
|
||||
### Production (bei Git Tag `v*`)
|
||||
```bash
|
||||
git tag v1.0.0
|
||||
git push origin v1.0.0
|
||||
**Workflow:**
|
||||
```
|
||||
Push → Gitea Actions → Terraform (Staging) → Hugo Build → Deploy
|
||||
Tag → Gitea Actions → Hugo Build → Deploy auf Production
|
||||
```
|
||||
- Hugo baut die Site
|
||||
- Deploy auf `stines.de`
|
||||
|
||||
## Lokale Entwicklung
|
||||
---
|
||||
|
||||
## 🚀 Quick Start (lokale Entwicklung)
|
||||
|
||||
```bash
|
||||
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