From d211bed5e47dd019e8a4598c4ebe4db5eb9af3aa Mon Sep 17 00:00:00 2001 From: Martin Eckardt Date: Sun, 28 Dec 2025 16:28:46 +0100 Subject: [PATCH] Gitea Deployment auf Proxmox - Vollstaendige Dokumentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docker-compose.yml aktualisiert fuer Proxmox Bare Metal - Security-Optionen (apparmor/seccomp) - Health-Check - Resource Limits - ROOT_URL fuer externen Zugriff via DuckDNS - README.md mit Architektur und Quick Start - TROUBLESHOOTING.md mit Problemloesungen - nginx-gitea.conf fuer VPS Reverse Proxy Deployment: https://eckardt-vault.duckdns.org/git/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 162 ++++++++++++++++++++++++++++++++++++++ configs/nginx-gitea.conf | 19 +++++ docker/docker-compose.yml | 34 +++++--- docs/TROUBLESHOOTING.md | 153 +++++++++++++++++++++++++++++++++++ 4 files changed, 359 insertions(+), 9 deletions(-) create mode 100644 README.md create mode 100644 configs/nginx-gitea.conf create mode 100644 docs/TROUBLESHOOTING.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e3a62b7 --- /dev/null +++ b/README.md @@ -0,0 +1,162 @@ +# Gitea on Proxmox + +Self-hosted Git Repository Server auf Proxmox VE. + +## Status + +| Service | URL | Status | +|---------|-----|--------| +| Web UI (extern) | https://eckardt-vault.duckdns.org/git/ | Aktiv | +| Web UI (intern) | http://192.168.178.111:3000 | Aktiv | +| Git SSH | ssh://git@192.168.178.111:2222 | Aktiv | + +## Architektur + +``` +Internet + | + v +[Windows VPS: 217.154.65.205] + - nginx Reverse Proxy + - SSL (Let's Encrypt) + - Route: /git/ -> 10.0.0.2:3000 + | + | WireGuard (10.0.0.0/24) + v +[Proxmox: 192.168.178.111 / 10.0.0.2] + - Docker Container: gitea + - Port 3000 (Web) + - Port 2222 (SSH) +``` + +## Deployment + +### Voraussetzungen + +- Proxmox VE Server mit Docker +- WireGuard Tunnel zum VPS (fuer externen Zugriff) +- nginx auf VPS konfiguriert + +### Quick Start + +```bash +# Auf Proxmox Server +mkdir -p /opt/docker/gitea +cd /opt/docker/gitea + +# docker-compose.yml kopieren (aus diesem Repo) +# Dann starten: +docker compose up -d +``` + +### Ersteinrichtung + +1. Browser oeffnen: http://192.168.178.111:3000 +2. Datenbanktyp: **SQLite3** auswaehlen +3. Admin-Account erstellen +4. Fertig! + +## Dateien + +``` +proxmox-gitea/ +├── docker/ +│ └── docker-compose.yml # Docker Compose Konfiguration +├── scripts/ +│ ├── setup.sh # Installations-Script +│ └── backup.sh # Backup-Script +├── docs/ +│ ├── INSTALL.md # Detaillierte Installationsanleitung +│ └── TROUBLESHOOTING.md # Problemloesungen +├── configs/ +│ └── nginx-gitea.conf # nginx Konfiguration fuer VPS +└── README.md # Diese Datei +``` + +## Troubleshooting + +Bei Problemen siehe [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) fuer: +- Container startet nicht +- Permission denied auf Proxmox +- Externer Zugriff funktioniert nicht +- SSH Clone Probleme +- Backup Fehler + +## Konfiguration + +### docker-compose.yml + +Wichtige Einstellungen: + +| Variable | Wert | Beschreibung | +|----------|------|--------------| +| ROOT_URL | https://eckardt-vault.duckdns.org/git/ | Externe URL | +| SSH_DOMAIN | 192.168.178.111 | SSH Host | +| SSH_PORT | 2222 | Git SSH Port | +| DB_TYPE | sqlite3 | Datenbank | + +### Proxmox-spezifisch + +Fuer Bare Metal Proxmox sind diese security_opt erforderlich: + +```yaml +security_opt: + - apparmor=unconfined + - seccomp=unconfined +``` + +## Backup + +Automatisches Backup taeglich um 03:00 Uhr: + +```bash +# Manuell ausfuehren +/opt/gitea/backup.sh + +# Backup-Verzeichnis +ls -la /opt/gitea-backups/ +``` + +## Wartung + +```bash +# Status pruefen +docker ps | grep gitea + +# Logs anzeigen +docker logs gitea -f + +# Update +cd /opt/docker/gitea +docker compose pull +docker compose up -d + +# Neustart +docker compose restart gitea +``` + +## Repository verbinden + +### Neues Repo klonen + +```bash +git clone https://eckardt-vault.duckdns.org/git/USER/REPO.git + +# Oder via SSH (intern) +git clone ssh://git@192.168.178.111:2222/USER/REPO.git +``` + +### Bestehendes Repo pushen + +```bash +cd mein-projekt +git remote add origin https://eckardt-vault.duckdns.org/git/USER/REPO.git +git push -u origin main +``` + +## Changelog + +### 2024-12-28 +- Initial Deployment auf Proxmox 192.168.178.111 +- Externer Zugriff via DuckDNS konfiguriert +- Health-Check und Resource Limits hinzugefuegt diff --git a/configs/nginx-gitea.conf b/configs/nginx-gitea.conf new file mode 100644 index 0000000..4a125d4 --- /dev/null +++ b/configs/nginx-gitea.conf @@ -0,0 +1,19 @@ +# nginx Konfiguration fuer Gitea +# Hinzufuegen zum bestehenden server{} Block auf dem VPS +# +# Pfad auf VPS: C:\nginx\conf\nginx.conf + +# Gitea - Git Repository +location /git/ { + proxy_pass http://10.0.0.2:3000/; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + # WebSocket support fuer Gitea + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + # Large file support fuer Git LFS + client_max_body_size 1G; +} diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index 304469c..9faf6c0 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -1,31 +1,47 @@ -version: "3" +version: "3.8" services: gitea: image: gitea/gitea:latest container_name: gitea + restart: unless-stopped + security_opt: + - apparmor=unconfined + - seccomp=unconfined environment: - USER_UID=1000 - USER_GID=1000 - GITEA__database__DB_TYPE=sqlite3 - - GITEA__server__ROOT_URL=http://git.local:3000/ - - GITEA__server__SSH_DOMAIN=git.local + - GITEA__server__ROOT_URL=https://eckardt-vault.duckdns.org/git/ + - GITEA__server__SSH_DOMAIN=192.168.178.111 - GITEA__server__SSH_PORT=2222 + - GITEA__server__LFS_START_SERVER=true + - GITEA__repository__DEFAULT_BRANCH=main volumes: - - gitea-data:/data + - /opt/docker/gitea:/data - /etc/timezone:/etc/timezone:ro - /etc/localtime:/etc/localtime:ro ports: - "3000:3000" # Web UI - "2222:22" # Git SSH - restart: unless-stopped + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:3000/api/healthz"] + interval: 30s + timeout: 10s + retries: 3 + deploy: + resources: + limits: + cpus: '2.0' + memory: 1G + logging: + driver: "json-file" + options: + max-size: "10m" + max-file: "3" networks: - gitea-net networks: gitea-net: driver: bridge - -volumes: - gitea-data: - driver: local diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..82beda9 --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,153 @@ +# Gitea Troubleshooting + +## Haeufige Probleme und Loesungen + +### 1. Container startet nicht + +**Symptom:** `docker compose up -d` startet, aber Container laeuft nicht + +**Loesung:** +```bash +# Logs pruefen +docker logs gitea + +# Oft: Berechtigungsprobleme +docker exec gitea ls -la /data + +# Oder Volume-Probleme +docker volume inspect gitea_gitea-data +``` + +### 2. "Permission denied" Fehler auf Proxmox + +**Symptom:** `socketpair() failed (13: Permission denied)` + +**Ursache:** Proxmox VE Bare Metal hat strikte Kernel-Hardening + +**Loesung:** security_opt in docker-compose.yml hinzufuegen: +```yaml +security_opt: + - apparmor=unconfined + - seccomp=unconfined +``` + +### 3. Falscher Datenbanktyp bei Ersteinrichtung + +**Symptom:** Fehlermeldung "unable to open tcp connection with host 'localhost:3306'" + +**Loesung:** +- Dropdown "Datenbanktyp" auf **SQLite3** aendern +- NICHT MSSQL oder MySQL auswaehlen + +### 4. Externer Zugriff funktioniert nicht + +**Symptom:** https://eckardt-vault.duckdns.org/git/ nicht erreichbar + +**Checkliste:** +```bash +# 1. Pruefen ob Gitea laeuft +docker ps | grep gitea + +# 2. Pruefen ob Port offen ist (auf Proxmox) +curl http://localhost:3000 + +# 3. WireGuard Tunnel pruefen (auf VPS) +ping 10.0.0.2 + +# 4. nginx Config testen (auf VPS) +cd C:\nginx && nginx.exe -t + +# 5. nginx neu starten (auf VPS) +net stop nginx && net start nginx +``` + +### 5. SSH Clone funktioniert nicht + +**Symptom:** `git clone ssh://...` schlaegt fehl + +**Loesung:** +```bash +# SSH Key in Gitea hinzufuegen +# Settings -> SSH/GPG Keys -> Add Key + +# Public Key anzeigen +cat ~/.ssh/id_ed25519.pub + +# SSH Verbindung testen +ssh -T -p 2222 git@192.168.178.111 +``` + +### 6. Health-Check schlaegt fehl + +**Symptom:** Container Status "unhealthy" + +**Loesung:** +```bash +# Health-Endpoint manuell testen +docker exec gitea curl -f http://localhost:3000/api/healthz + +# Falls curl nicht installiert: +docker exec gitea wget -q --spider http://localhost:3000/api/healthz +``` + +### 7. Backup schlaegt fehl + +**Symptom:** Backup-Script gibt Fehler aus + +**Loesung:** +```bash +# Volume-Pfad pruefen +docker volume inspect gitea_gitea-data + +# Manuelles Backup erstellen +docker exec gitea gitea dump -c /data/gitea/conf/app.ini +``` + +### 8. Nach Update: Gitea startet nicht mehr + +**Symptom:** Nach `docker compose pull` funktioniert nichts mehr + +**Loesung:** +```bash +# Alte Version wiederherstellen +docker compose down +docker image tag gitea/gitea:latest gitea/gitea:backup +docker pull gitea/gitea:1.21 # oder gewuenschte Version +docker compose up -d + +# Oder: Datenbank-Migration manuell ausfuehren +docker exec gitea gitea migrate +``` + +## Diagnose-Befehle + +```bash +# Container Status +docker ps -a | grep gitea + +# Container Ressourcen +docker stats gitea --no-stream + +# Netzwerk pruefen +docker network inspect gitea_gitea-net + +# Alle Logs (letzte 100 Zeilen) +docker logs gitea --tail 100 + +# Live Logs +docker logs gitea -f + +# In Container einloggen +docker exec -it gitea /bin/sh + +# Gitea Version +docker exec gitea gitea --version + +# Gitea Admin-Befehle +docker exec gitea gitea admin user list +``` + +## Kontakt / Weitere Hilfe + +- Gitea Dokumentation: https://docs.gitea.io/ +- Gitea GitHub Issues: https://github.com/go-gitea/gitea/issues