GSM/docs/gitea-setup.md

# Gitea Setup mit CI/CD Runner

Lokale Git-Instanz auf Proxmox LXC mit automatischem Deployment via Gitea Actions.

## Übersicht

```
┌─────────────────┐     git push      ┌─────────────────┐
│  Lokaler PC     │ ───────────────▶  │  Gitea LXC      │
│  (Development)  │                   │  192.168.2.40   │
└─────────────────┘                   └────────┬────────┘
                                               │ trigger
                                               ▼
                                      ┌─────────────────┐
                                      │  Gitea Runner   │
                                      │  (act_runner)   │
                                      └────────┬────────┘
                                               │ SSH deploy
                                               ▼
                                      ┌─────────────────┐
                                      │  GSM Server     │
                                      │  192.168.2.30   │
                                      └─────────────────┘
```

## Teil 1: LXC Container erstellen

### Proxmox Web UI
1. CT Template herunterladen: `Datacenter → pve → local → CT Templates → Templates`
   - Debian 12 (Bookworm) empfohlen
2. Neuen Container erstellen:
   - **CT ID:** 104 (oder nächste freie)
   - **Hostname:** gitea
   - **Password:** sicheres Root-Passwort
   - **Template:** debian-12-standard
   - **Disk:** 16 GB
   - **CPU:** 2 Cores
   - **RAM:** 1024 MB
   - **Network:** vmbr0, DHCP oder statisch 192.168.2.40

### Oder per CLI auf Proxmox Host
```bash
# Template herunterladen falls nicht vorhanden
pveam download local debian-12-standard_12.2-1_amd64.tar.zst

# Container erstellen
pct create 104 local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \
  --hostname gitea \
  --memory 1024 \
  --cores 2 \
  --rootfs local-lvm:16 \
  --net0 name=eth0,bridge=vmbr0,ip=192.168.2.40/24,gw=192.168.2.1 \
  --password \
  --unprivileged 1 \
  --features nesting=1

# Container starten
pct start 104
```

## Teil 2: Gitea Installation

### System vorbereiten
```bash
# In den Container einloggen
pct enter 104

# System updaten
apt update && apt upgrade -y

# Abhängigkeiten installieren
apt install -y git curl wget sudo sqlite3
```

### Git-User erstellen
```bash
adduser --system --shell /bin/bash --group --disabled-password --home /home/git git
```

### Gitea herunterladen
```bash
# Aktuelle Version prüfen: https://github.com/go-gitea/gitea/releases
GITEA_VERSION="1.21.4"

wget -O /usr/local/bin/gitea https://dl.gitea.io/gitea/${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-amd64
chmod +x /usr/local/bin/gitea

# Version prüfen
gitea --version
```

### Verzeichnisse erstellen
```bash
mkdir -p /var/lib/gitea/{custom,data,log}
mkdir -p /etc/gitea
chown -R git:git /var/lib/gitea
chown root:git /etc/gitea
chmod 770 /etc/gitea
```

### Systemd Service
```bash
cat > /etc/systemd/system/gitea.service << 'EOF'
[Unit]
Description=Gitea (Git with a cup of tea)
After=network.target

[Service]
RestartSec=2s
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea/
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable gitea
systemctl start gitea
```

### Web-Setup abschließen
1. Browser öffnen: `http://192.168.2.40:3000`
2. Initial-Setup:
   - **Database:** SQLite3
   - **SSH Port:** 22
   - **HTTP Port:** 3000
   - **Base URL:** `http://192.168.2.40:3000/` (später ändern für Domain)
   - **Admin Account erstellen**

### Berechtigungen nach Setup fixieren
```bash
chmod 750 /etc/gitea
chmod 640 /etc/gitea/app.ini
```

## Teil 3: Gitea Actions aktivieren

### app.ini anpassen
```bash
nano /etc/gitea/app.ini
```

Folgende Sektion hinzufügen/anpassen:
```ini
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = github
```

Gitea neustarten:
```bash
systemctl restart gitea
```

## Teil 4: Gitea Actions Runner

### Runner installieren
```bash
# Als root auf dem Gitea-Server (oder separater Server)
cd /opt
RUNNER_VERSION="0.2.6"
wget https://gitea.com/gitea/act_runner/releases/download/v${RUNNER_VERSION}/act_runner-${RUNNER_VERSION}-linux-amd64
mv act_runner-${RUNNER_VERSION}-linux-amd64 act_runner
chmod +x act_runner
```

### Runner Token generieren
1. Gitea Web UI → `Site Administration → Actions → Runners`
2. `Create new Runner` → Token kopieren

### Runner registrieren
```bash
cd /opt
./act_runner register --no-interactive \
  --instance http://192.168.2.40:3000 \
  --token <DEIN_TOKEN> \
  --name homelab-runner \
  --labels ubuntu-latest:docker://node:20-bookworm,ubuntu-22.04:docker://ubuntu:22.04
```

### Runner als Systemd Service
```bash
cat > /etc/systemd/system/gitea-runner.service << 'EOF'
[Unit]
Description=Gitea Actions Runner
After=network.target gitea.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt
ExecStart=/opt/act_runner daemon
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable gitea-runner
systemctl start gitea-runner
```

### Docker für Runner installieren (falls Labels mit docker:// genutzt)
```bash
apt install -y docker.io
systemctl enable docker
systemctl start docker
```

## Teil 5: SSH Deploy Key einrichten

### Auf dem Gitea-Server (Runner)
```bash
# SSH Key für Deployments erstellen
ssh-keygen -t ed25519 -C "gitea-deploy" -f /root/.ssh/deploy_key -N ""

# Public Key anzeigen
cat /root/.ssh/deploy_key.pub
```

### Auf dem GSM-Server (192.168.2.30)
```bash
# Public Key zu authorized_keys hinzufügen
echo "ssh-ed25519 AAAA... gitea-deploy" >> /root/.ssh/authorized_keys
```

### In Gitea als Secret speichern
1. Repository → `Settings → Actions → Secrets`
2. Neues Secret: `SSH_DEPLOY_KEY`
3. Inhalt: Private Key (`cat /root/.ssh/deploy_key`)

## Teil 6: GSM Repository einrichten

### Auf dem GSM-Server (192.168.2.30)
```bash
cd /opt/gameserver-monitor

# Falls noch kein Git-Repo
git init
git add .
git commit -m "Initial commit"

# Gitea als Remote hinzufügen
git remote add origin http://192.168.2.40:3000/<user>/gameserver-monitor.git
git push -u origin main
```

### Workflow-Datei erstellen
Im Repository `.gitea/workflows/deploy.yml` erstellen:

```yaml
name: Deploy GSM

on:
  push:
    branches: [main]
  workflow_dispatch:  # Manueller Trigger

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy to Server
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: 192.168.2.30
          username: root
          key: ${{ secrets.SSH_DEPLOY_KEY }}
          script: |
            set -e
            cd /opt/gameserver-monitor

            echo "=== Pulling latest changes ==="
            git fetch origin main
            git reset --hard origin/main

            echo "=== Installing backend dependencies ==="
            cd backend
            npm ci --production

            echo "=== Building frontend ==="
            cd ../frontend
            npm ci
            npm run build

            echo "=== Restarting services ==="
            pm2 restart gsm-backend

            echo "=== Deploy complete ==="
```

### Alternative: Separater Frontend/Backend Deploy
```yaml
name: Deploy GSM

on:
  push:
    branches: [main]
    paths:
      - 'backend/**'
      - 'frontend/**'

jobs:
  deploy-backend:
    runs-on: ubuntu-latest
    if: contains(github.event.head_commit.modified, 'backend/')
    steps:
      - uses: actions/checkout@v4
      - name: Deploy Backend
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: 192.168.2.30
          username: root
          key: ${{ secrets.SSH_DEPLOY_KEY }}
          script: |
            cd /opt/gameserver-monitor/backend
            git pull origin main
            npm ci --production
            pm2 restart gsm-backend

  deploy-frontend:
    runs-on: ubuntu-latest
    if: contains(github.event.head_commit.modified, 'frontend/')
    steps:
      - uses: actions/checkout@v4
      - name: Deploy Frontend
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: 192.168.2.30
          username: root
          key: ${{ secrets.SSH_DEPLOY_KEY }}
          script: |
            cd /opt/gameserver-monitor/frontend
            git pull origin main
            npm ci
            npm run build
```

## Teil 7: Reverse Proxy (Optional)

### Nginx Proxy Manager Konfiguration
Falls Gitea über Domain erreichbar sein soll (z.B. `git.zeasy.dev`):

1. Nginx Proxy Manager → Proxy Hosts → Add
2. **Domain:** git.zeasy.dev
3. **Forward Hostname:** 192.168.2.40
4. **Forward Port:** 3000
5. **SSL:** Let's Encrypt aktivieren

### Gitea app.ini anpassen
```ini
[server]
DOMAIN = git.zeasy.dev
ROOT_URL = https://git.zeasy.dev/
SSH_DOMAIN = git.zeasy.dev
```

## Teil 8: Lokale Git-Konfiguration

### Remote für lokales Entwickeln
```bash
# Im lokalen Projekt
cd E:/Projects/homelab-docs/gsm-frontend
git remote add gitea http://192.168.2.40:3000/<user>/gameserver-monitor.git

# Oder mit SSH (wenn SSH-Key eingerichtet)
git remote add gitea git@192.168.2.40:<user>/gameserver-monitor.git
```

### Workflow
```bash
# Entwickeln...
git add .
git commit -m "Feature: xyz"
git push gitea main  # → Triggert automatisch Deploy
```

## Troubleshooting

### Runner-Status prüfen
```bash
systemctl status gitea-runner
journalctl -u gitea-runner -f
```

### Gitea Logs
```bash
journalctl -u gitea -f
# oder
tail -f /var/lib/gitea/log/gitea.log
```

### Actions Debug
- In Gitea Web UI: Repository → Actions → Job auswählen → Logs ansehen

### SSH-Verbindung testen
```bash
# Vom Runner aus
ssh -i /root/.ssh/deploy_key root@192.168.2.30 "echo 'Connection OK'"
```

## Ressourcen

- Gitea Docs: https://docs.gitea.io/
- Gitea Actions: https://docs.gitea.io/en-us/actions/overview/
- Act Runner: https://gitea.com/gitea/act_runner