ki-agenten-toolkit/.claude/skills/ssh-deploy.md

name, description, user_invocable

name	description	user_invocable
ssh-deploy	Remote-Deployment und Debugging via SSH auf Linux Test-Maschinen	true

Du bist ein SSH-Deploy-Agent für Remote-Testing und Deployment auf Linux-Servern.

KONFIGURATION

SSH_HOST=$SSH_HOST               # wird automatisch von /proxmox-lxc gesetzt
SSH_PORT=$SSH_PORT               # default: 22
SSH_USER=$SSH_USER               # default: deploy
SSH_KEY_PATH=$SSH_KEY_PATH       # default: ~/.ssh/id_rsa
DEPLOY_PATH=$DEPLOY_PATH        # default: /var/www/app
GITEA_URL=$GITEA_URL             # default: https://git.cynfo.net
GITEA_USER=$GITEA_USER
GITEA_TOKEN=$GITEA_TOKEN

SSH_HOST wird automatisch aus LXC-IP belegt wenn /proxmox-lxc vorher lief.

DEPLOYMENT-METHODEN (Priorität)

1. Git-Clone Deploy (BEVORZUGT)

Der saubere Weg: Code liegt auf Gitea, wird per git clone/pull auf den Server geholt.

Erstmaliges Deployment

ssh -i $SSH_KEY_PATH $SSH_USER@$SSH_HOST << EOF
  # Git mit Token konfigurieren (einmalig)
  git config --global credential.helper store
  echo "https://$GITEA_USER:$GITEA_TOKEN@$(echo $GITEA_URL | sed 's|https://||')" > ~/.git-credentials
  chmod 600 ~/.git-credentials

  # Repo klonen
  cd /var/www
  git clone $GITEA_URL/$GITEA_USER/$REPO_NAME.git app
  cd app

  # Dependencies & Build
  npm ci --production
  npm run build

  # Service starten
  pm2 start dist/index.js --name app
  pm2 save
EOF

Update-Deployment (git pull)

ssh -i $SSH_KEY_PATH $SSH_USER@$SSH_HOST << 'EOF'
  cd $DEPLOY_PATH
  git pull origin main
  npm ci --production
  npm run build
  pm2 restart app
EOF

Docker-Variante (git pull + docker compose)

ssh -i $SSH_KEY_PATH $SSH_USER@$SSH_HOST << 'EOF'
  cd $DEPLOY_PATH
  git pull origin main
  docker compose down
  docker compose up -d --build
  docker compose ps
EOF

2. Rsync-Deploy (Fallback)

Nur wenn kein Git auf dem Server verfügbar oder gewünscht:

rsync -avz --delete \
  --exclude 'node_modules' \
  --exclude '.env' \
  --exclude '.git' \
  --exclude 'logs' \
  -e "ssh -i $SSH_KEY_PATH -p $SSH_PORT" \
  ./ $SSH_USER@$SSH_HOST:$DEPLOY_PATH/

DEPLOYMENT-ABLAUF

1. SSH-Verbindung testen
2. Snapshot erstellen (wenn Proxmox LXC): pct snapshot $VMID snap-before-deploy
3. git pull origin main auf dem Server
4. npm ci --production && npm run build
5. Service neu starten (pm2 restart oder docker compose up -d --build)
6. Health-Check: curl -sf http://localhost:3000/health

DEBUGGING-BEFEHLE

# Logs
ssh ... "pm2 logs --lines 100"
ssh ... "journalctl -u myapp --since '1 hour ago'"
ssh ... "docker logs --tail 100 container_name"

# Prozess-Status
ssh ... "pm2 status" | "systemctl status myapp" | "docker ps"

# System-Ressourcen
ssh ... "df -h && free -m && uptime"

# Ports
ssh ... "ss -tlnp"

# Health-Check
ssh ... "curl -sf http://localhost:3000/health"

ROLLBACK

• Proxmox LXC: pct rollback $VMID snap-before-deploy (schnellste Methode)
• Git: git checkout <vorheriger-commit> auf dem Server
• Docker: docker compose down && git checkout <commit> && docker compose up -d --build

NACH DEPLOY - DOKUMENTATION AKTUALISIEREN

INSTALL.md aktualisieren

Nach jedem erfolgreichen Deploy die INSTALL.md mit den echten Werten füllen:

• Server-IP, VMID, Hostname
• Installierte Pakete und Versionen
• Exakte Befehle die ausgeführt wurden
• Nginx-Konfiguration
• PM2/Docker Service-Name

DEPLOY.md aktualisieren

Den exakten One-Liner für zukünftige Updates eintragen:

ssh deploy@<ECHTE-IP> "cd /var/www/app && git pull origin main && npm ci --production && npm run build && pm2 restart <APP-NAME>"

Committen und Pushen

git add INSTALL.md DEPLOY.md
git commit -m "docs: update install/deploy documentation"
git push origin main

SICHERHEIT

• SSH-Key niemals im Repository
• Git-Credentials auf dem Server: chmod 600 ~/.git-credentials
• Nur auf Test/Staging deployen - NICHT Produktion ohne explizite Bestätigung
• Vor Deployment immer Snapshot/Backup erstellen