Spaces:

Hwandji
/

saap-deploy

Paused

# 1. .env Datei erstellen
cp .env.example .env

# 2. .env mit echten Werten füllen (mindestens für Tests)
nano .env

# Mindestens diese Werte setzen:
# OPENROUTER_API_KEY=dein-echter-key
# COLOSSUS_API_KEY=dein-echter-key
# SECRET_KEY=test-secret-key-123

1.2 Development Build testen

# Docker Compose Development Build
docker-compose up --build

# In separatem Terminal:
# Backend Health Check
curl http://localhost:8000/health

# Erwartete Ausgabe:
# {"status":"healthy","timestamp":"2025-11-18T10:38:00.000000"}

# Frontend erreichbar?
curl http://localhost:5173

# API Docs erreichbar?
curl http://localhost:8000/docs

Erwartetes Ergebnis:

✅ Backend startet ohne Fehler
✅ Frontend startet ohne Fehler
✅ PostgreSQL läuft
✅ Health Check returns {"status":"healthy"}

1.3 Production Build testen

# Docker Compose Production Build
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up --build

# Health Checks
curl http://localhost:8000/health  # Backend
curl http://localhost/             # Frontend (Port 80!)

# API Docs (Production)
curl http://localhost:8000/docs

Wichtige Unterschiede:

Frontend läuft auf Port 80 (nicht 5173)
Production builds sind optimiert (keine dev dependencies)
Uvicorn läuft mit 4 Workers

🔐 Stufe 2: Security & Quality Checks (Lokal)

2.1 Gitleaks Secret Scanning

# Vollständiger Scan des Repositories
gitleaks detect --source . --verbose

# Erwartete Ausgabe:
# ○
# ████████╗██████╗ ██╗   ██╗███████╗███████╗██╗     ███████╗ █████╗ ██╗  ██╗███████╗
# ╚══██╔══╝██╔══██╗██║   ██║██╔════╝██╔════╝██║     ██╔════╝██╔══██╗██║ ██╔╝██╔════╝
#    ██║   ██████╔╝██║   ██║█████╗  █████╗  ██║     █████╗  ███████║█████╔╝ ███████╗
# ...
# 
# No leaks found ✅

# Mit Report-Datei
gitleaks detect --source . --report-path gitleaks-report.json

Was wird gescannt:

API Keys (OpenRouter, Colossus, etc.)
Database Passwords
Secret Keys
JWT Tokens
SSH Private Keys

Bei Fund:

# Secrets gefunden!
# Ausgabe zeigt Datei + Zeile + Secret-Typ

# Sofort beheben:
# 1. Secret aus Datei entfernen
# 2. .gitignore prüfen
# 3. Erneut scannen

2.2 Dependency Security Audit

# Frontend Dependencies
cd frontend
npm audit --audit-level=moderate

# Erwartete Ausgabe:
# found 0 vulnerabilities ✅

# Bei Vulnerabilities:
npm audit fix

# Backend Dependencies
cd ../backend
pip install pip-audit
pip-audit

# Erwartete Ausgabe:
# No known vulnerabilities found ✅

2.3 Linting & Formatting

# Frontend (ESLint + Prettier)
cd frontend
npm run lint              # ESLint Check
npm run format:check      # Prettier Check

# Auto-Fix
npm run lint:fix
npm run format

# Backend (Ruff)
cd ../backend
ruff check .              # Lint Check
ruff format .             # Format Code

# TypeScript Check
cd ../frontend
npm run type-check

Erwartetes Ergebnis:

✅ 0 ESLint errors
✅ 0 Ruff errors
✅ 0 TypeScript errors
✅ Code korrekt formatiert

🎬 Stufe 3: GitHub Actions Simulation (mit `act`)

3.1 `act` installieren (GitHub Actions lokal ausführen)

# Installation (Linux/macOS)
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# Oder via Package Manager
# Ubuntu/Debian
sudo apt install act

# macOS
brew install act

# Arch Linux
sudo pacman -S act

# Version prüfen
act --version

3.2 GitHub Actions Workflow lokal testen

# Alle Jobs auflisten
act -l

# Erwartete Ausgabe:
# Stage  Job ID            Job name          Workflow name              Workflow file
# 0      security          security          SAAP CI/CD Pipeline       ci-cd-pipeline.yml
# 0      lint-backend      lint-backend      SAAP CI/CD Pipeline       ci-cd-pipeline.yml
# 0      lint-frontend     lint-frontend     SAAP CI/CD Pipeline       ci-cd-pipeline.yml
# 1      test-backend      test-backend      SAAP CI/CD Pipeline       ci-cd-pipeline.yml
# 1      test-frontend     test-frontend     SAAP CI/CD Pipeline       ci-cd-pipeline.yml
# 2      build-backend     build-backend     SAAP CI/CD Pipeline       ci-cd-pipeline.yml
# 2      build-frontend    build-frontend    SAAP CI/CD Pipeline       ci-cd-pipeline.yml

# Komplette Pipeline ausführen (ohne Docker Build/Push)
act push

# Einzelnen Job testen
act -j security     # Nur Security Checks
act -j lint-backend # Nur Backend Linting
act -j lint-frontend # Nur Frontend Linting

# Mit GitHub Secrets (simuliert)
act -s GITHUB_TOKEN=fake-token-for-testing

# Dry-Run (zeigt was passieren würde)
act -n

3.3 Docker Build lokal simulieren

# Backend Build testen
docker build -t saap-backend-test \
  --build-arg PYTHON_VERSION=3.10 \
  -f backend/Dockerfile \
  ./backend

# Frontend Build testen
docker build -t saap-frontend-test \
  --build-arg NODE_VERSION=20 \
  -f frontend/Dockerfile \
  ./frontend

# Multi-Architecture Build simulieren (buildx)
docker buildx create --use --name multiarch
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t saap-backend-multiarch \
  -f backend/Dockerfile \
  ./backend \
  --load

# Images prüfen
docker images | grep saap

Erwartetes Ergebnis:

✅ Backend Image: ~200-300 MB
✅ Frontend Image: ~50-100 MB
✅ Keine Build-Fehler
✅ Health Check im Container funktioniert

🚀 Stufe 4: Live Test auf GitHub

4.1 Vorbereitung

# 1. Sicherstellen, dass .env NICHT committed ist
git status | grep .env

# Wenn .env gelistet wird:
git reset HEAD backend/.env
echo "backend/.env" >> .gitignore

# 2. Letzte Security-Checks
gitleaks detect --source . --verbose
npm audit --audit-level=moderate

# 3. Alle Änderungen committen
git add .
git commit -m "feat: add CI/CD pipeline and Docker deployment"

# 4. Feature Branch erstellen (NICHT direkt auf main)
git checkout -b feature/cicd-pipeline

4.2 Ersten Push testen

# Push zu GitHub
git push origin feature/cicd-pipeline

# GitHub öffnen und Pipeline beobachten:
# https://github.com/satwareAG/saap/actions

Was passiert auf GitHub:

✅ Security Job läuft (Gitleaks, npm audit)
✅ Lint Jobs laufen (ESLint, Ruff, Prettier)
✅ Test Jobs laufen (Unit Tests, Falls vorhanden)
✅ Build Jobs laufen (Docker Multi-Arch Build)
✅ Push to Registry (ghcr.io) - NUR wenn auf main/develop Branch

4.3 Pull Request erstellen

# PR von feature/cicd-pipeline → main erstellen
# GitHub Web UI verwenden ODER:

gh pr create \
  --title "Add CI/CD Pipeline and Docker Deployment" \
  --body "Adds complete CI/CD pipeline with GitHub Actions" \
  --base main \
  --head feature/cicd-pipeline

CI/CD Workflow bei PR:

Läuft ALLE Checks (Security, Lint, Test, Build)
Baut Docker Images (aber pusht NICHT zu Registry)
Zeigt Ergebnisse im PR

4.4 GitHub Container Registry prüfen

# Nach erfolgreichem Push zu main/develop:
# Images sollten verfügbar sein:

# Backend Image
docker pull ghcr.io/satwareag/saap/backend:latest

# Frontend Image
docker pull ghcr.io/satwareag/saap/frontend:latest

# Spezifische Version (Commit SHA)
docker pull ghcr.io/satwareag/saap/backend:abc1234

# Images lokal testen
docker run -p 8000:8000 ghcr.io/satwareag/saap/backend:latest

✅ Vollständige Test-Checkliste

Pre-Push Checklist

# 1. Environment Setup
[ ] .env erstellt und konfiguriert
[ ] .env in .gitignore

# 2. Lokale Docker Tests
[ ] docker-compose up --build funktioniert
[ ] Backend Health Check: curl http://localhost:8000/health
[ ] Frontend erreichbar: curl http://localhost:5173
[ ] Production Build: docker-compose -f docker-compose.yml -f docker-compose.prod.yml up

# 3. Security Checks
[ ] gitleaks detect --source . --verbose → No leaks found
[ ] npm audit --audit-level=moderate → 0 vulnerabilities
[ ] pip-audit → No vulnerabilities

# 4. Quality Checks
[ ] npm run lint (Frontend)
[ ] ruff check . (Backend)
[ ] npm run type-check (TypeScript)
[ ] npm run format:check (Prettier)

# 5. Docker Build Tests
[ ] docker build backend/Dockerfile funktioniert
[ ] docker build frontend/Dockerfile funktioniert
[ ] Images starten ohne Fehler

# 6. GitHub Actions Simulation (optional)
[ ] act -j security funktioniert
[ ] act -j lint-backend funktioniert
[ ] act -j lint-frontend funktioniert

Post-Push Checklist

# Nach Push zu GitHub
[ ] GitHub Actions Workflow startet
[ ] Alle Jobs grün (Security, Lint, Test, Build)
[ ] Keine Fehler in Logs
[ ] Docker Images in ghcr.io verfügbar (bei main/develop)
[ ] Images können gepullt werden
[ ] Production Deployment funktioniert

🚨 Troubleshooting

Problem: `act` findet Docker nicht

# Docker läuft?
docker ps

# Docker Socket Permission
sudo usermod -aG docker $USER
newgrp docker

Problem: GitHub Actions schlägt fehl (lokaler Test OK)

# Secrets in GitHub konfiguriert?
# Settings → Secrets and variables → Actions

# Branch Protection Rules checken
# Settings → Branches → Branch protection rules

Problem: Docker Build schlägt fehl im CI/CD

# .dockerignore prüfen
cat backend/.dockerignore
cat frontend/.dockerignore

# Build Logs in GitHub Actions ansehen
# Actions → Workflow → Failed Job → Logs

Problem: Images können nicht gepusht werden

# GitHub Package Permission
# Settings → Actions → General → Workflow permissions
# ✅ Read and write permissions

# Container Registry Visibility
# GitHub → Packages → saap/backend → Package settings

📊 Erwartete Test-Ergebnisse

Erfolgreicher Lokaler Test

✅ docker-compose up → Alle Services starten
✅ Health Check → {"status":"healthy"}
✅ Gitleaks → No leaks found
✅ npm audit → 0 vulnerabilities
✅ ESLint → 0 errors
✅ Ruff → 0 errors
✅ Docker Build → Images erstellt
✅ act → Alle Jobs grün

Erfolgreicher GitHub Test

✅ Push → Workflow startet automatisch
✅ Security Job → Passed (30s)
✅ Lint Backend → Passed (45s)
✅ Lint Frontend → Passed (1min)
✅ Test Backend → Passed (2min)
✅ Test Frontend → Passed (1min)
✅ Build Backend → Passed (5min)
✅ Build Frontend → Passed (4min)
✅ Push to Registry → Passed (2min)

Total: ~15 Minuten

🎯 Quick Start Testing

# Minimales Testing (5 Minuten)
docker-compose up --build                           # 2min
curl http://localhost:8000/health                   # 1s
gitleaks detect --source . --verbose                # 30s
npm audit --audit-level=moderate                    # 30s
docker-compose down                                 # 10s

# Vollständiges Testing (30 Minuten)
# Alle Schritte aus Pre-Push Checklist + act Simulation

📚 Weitere Ressourcen

act Documentation: https://github.com/nektos/act
GitHub Actions Docs: https://docs.github.com/en/actions
Docker Buildx: https://docs.docker.com/buildx/working-with-buildx/
Gitleaks: https://github.com/gitleaks/gitleaks

🆘 Support

Bei Problemen:

GitHub Actions Logs analysieren
Lokale Docker Logs prüfen: docker-compose logs
Issue erstellen: https://github.com/satwareAG/saap/issues

CI/CD Pipeline Testing Guide

📋 Übersicht

🧪 Testing-Strategie

Stufe 1: Lokale Docker Tests (OHNE GitHub)

Stufe 2: Security & Quality Checks (Lokal)

Stufe 3: GitHub Actions Simulation (mit act)

Stufe 4: Live Test auf GitHub (Push/PR)

🔧 Stufe 1: Lokale Docker Tests

1.1 Environment Setup testen

1.2 Development Build testen

1.3 Production Build testen

🔐 Stufe 2: Security & Quality Checks (Lokal)

2.1 Gitleaks Secret Scanning

2.2 Dependency Security Audit

2.3 Linting & Formatting

🎬 Stufe 3: GitHub Actions Simulation (mit act)

3.1 act installieren (GitHub Actions lokal ausführen)

3.2 GitHub Actions Workflow lokal testen

3.3 Docker Build lokal simulieren

🚀 Stufe 4: Live Test auf GitHub

4.1 Vorbereitung

4.2 Ersten Push testen

4.3 Pull Request erstellen

4.4 GitHub Container Registry prüfen

✅ Vollständige Test-Checkliste

Pre-Push Checklist

Post-Push Checklist

🚨 Troubleshooting

Problem: act findet Docker nicht

Problem: GitHub Actions schlägt fehl (lokaler Test OK)

Problem: Docker Build schlägt fehl im CI/CD

Problem: Images können nicht gepusht werden

📊 Erwartete Test-Ergebnisse

Erfolgreicher Lokaler Test

Erfolgreicher GitHub Test

🎯 Quick Start Testing

📚 Weitere Ressourcen

🆘 Support

Stufe 3: GitHub Actions Simulation (mit `act`)

🎬 Stufe 3: GitHub Actions Simulation (mit `act`)

3.1 `act` installieren (GitHub Actions lokal ausführen)

Problem: `act` findet Docker nicht