FullStackTemplate/README.md

🚀 Full Stack TypeScript Template

Ein modernes, sicherheitsoptimiertes Full Stack Template mit React Frontend und Express Backend, komplett containerisiert mit Docker.

📋 Übersicht

• Frontend: React 18 + TypeScript + Create React App
• Backend: Express.js + TypeScript + Node.js + Helmet + CORS
• Database: SQLite (Standard) oder PostgreSQL 15 (optional, mit scram-sha-256 Auth)
• Container: Docker + Docker Compose
• Development: Hot Reload für Frontend & Backend
• CI/CD: Gitea Actions mit automatischen Security-Scans
• Security: Non-root Container, Input-Validierung, Security Headers
• Flexibel: PostgreSQL optional - auch für SQLite-only Projekte geeignet

🔐 Sicherheitsfeatures

✅ Non-root Docker Container - Alle Container laufen als nicht-privilegierte User ✅ Security Headers - Helmet.js & moderne CSP-Policies ✅ Input-Validierung - express-validator für alle API-Endpoints ✅ CORS-Whitelist - Konfigurierbare Origin-Beschränkung ✅ Resource Limits - CPU/Memory-Limits gegen DoS ✅ Isolierte Datenbank - PostgreSQL (falls verwendet) nur intern erreichbar ✅ Automatische Scans - Trivy Security Scans in CI/CD ✅ Secrets Management - Keine Hardcoded Credentials ✅ Flexible Architektur - SQLite für einfache Projekte, PostgreSQL für Production

🛠️ Voraussetzungen

• Node.js >= 18.0.0
• npm >= 9.0.0
• Docker & Docker Compose

📦 Installation

1. Repository klonen

git clone <repository-url>
cd fullstack-typescript-template

2. Dependencies installieren

npm run install:all

🏃‍♂️ Development

Lokale Entwicklung (ohne Docker)

# Alle Services starten
npm run dev

# Einzeln starten
npm run dev:backend    # Backend auf Port 3001
npm run dev:frontend   # Frontend auf Port 3000

# Development-Prozesse beenden
npm run kill:dev

Mit Docker (empfohlen)

# Development mit Hot Reload
npm run docker:dev

# Production-ähnliche Umgebung
npm run docker:prod

# Services stoppen
npm run docker:down

🐳 Docker Commands

Build & Start

npm run docker:build    # App Image erstellen
npm run docker:up       # Services im Hintergrund starten
npm run docker:dev      # Development-Modus mit Rebuild
npm run docker:prod     # Production-Modus

Management

npm run docker:stop     # Services stoppen (Container bleiben)
npm run docker:down     # Services stoppen + Container entfernen
npm run docker:restart  # Services neustarten

Logs & Debugging

npm run docker:logs     # Alle Logs anzeigen
npm run docker:logs:app # Nur App-Logs
npm run docker:logs:db  # Nur Datenbank-Logs

Cleanup

npm run docker:clean    # Alles aufräumen (Volumes, Container, Images)

Manuelle Docker Commands

# Image bauen
docker build -t fullstack-app .

# Services starten
docker-compose up -d

# Logs verfolgen
docker-compose logs -f

# Services stoppen
docker-compose down

🏗️ Build

Development Build

npm run build           # Frontend + Backend
npm run build:frontend  # Nur Frontend
npm run build:backend   # Nur Backend

Production Build

# Mit Docker (empfohlen - baut automatisch)
docker-compose up --build -d

# Oder mit npm
npm run docker:build    # Baut das Image
npm run docker:up       # Startet die Services

# Manuell (ohne Docker)
npm run build
NODE_ENV=production npm start

🧪 Testing

npm run test            # Alle Tests
npm run test:frontend   # Frontend Tests
npm run test:backend    # Backend Tests

🧹 Cleanup

npm run clean           # Alle node_modules & Build-Ordner
npm run clean:build     # Nur Build-Ordner
npm run docker:clean    # Docker Cleanup

🌍 Environment Variables

⚠️ WICHTIG: Sicherheitskonfiguration

1. Kopiere die Beispiel-Datei:

   cp .env.example .env
   

2. Generiere sichere Secrets:

   # JWT Secret generieren
   openssl rand -base64 32
   
   # PostgreSQL Passwort generieren
   openssl rand -base64 32
   

3. Fülle die .env Datei mit deinen Werten:

   # Database (⚠️ MUSS geändert werden!)
   POSTGRES_DB=appdb
   POSTGRES_USER=postgres
   POSTGRES_PASSWORD=[DEIN_SICHERES_PASSWORT_HIER]
   
   # Security (⚠️ MUSS geändert werden!)
   JWT_SECRET=[DEIN_SICHERES_SECRET_HIER]
   
   # App
   NODE_ENV=production
   APP_PORT=8080
   

📋 Vollständige Dokumentation

Siehe .env.example für alle verfügbaren Optionen und detaillierte Erklärungen.

🚨 Sicherheitshinweise

• ❌ NIEMALS .env in Git committen (bereits in .gitignore)
• ✅ Verwende unterschiedliche Secrets für Development, Staging und Production
• ✅ Nutze starke, zufällige Passwörter (min. 32 Zeichen)
• ✅ Rotiere Secrets regelmäßig in Production-Umgebungen

🗄️ Datenbank-Konfiguration

Dieses Template ist flexibel und unterstützt verschiedene Datenbanken:

Option 1: SQLite (Standard - keine Konfiguration nötig)

Perfekt für:

• ✅ Einfache Projekte und Prototypen
• ✅ Low-Traffic Anwendungen
• ✅ Development und Testing
• ✅ Keine separate DB-Server benötigt

Keine weiteren Schritte nötig! Die Datenbank wird automatisch im /data Volume erstellt.

Option 2: PostgreSQL (Optional - für Production)

Empfohlen für:

• ✅ Production-Umgebungen
• ✅ High-Traffic Anwendungen
• ✅ Komplexe Datenmodelle
• ✅ Mehrere parallele Connections

Aktivierung:

1. Öffne docker-compose.yml und entkommentiere den postgres-Service (Zeile 82-135)
2. Aktiviere depends_on im app-Service (Zeile 52-54)
3. Entkommentiere postgres_data Volume (Zeile 149-150)
4. Setze in .env: DATABASE_URL=postgresql://postgres:YOUR_PASSWORD@postgres:5432/appdb
5. Setze ein sicheres POSTGRES_PASSWORD

Option 3: Andere Datenbanken

Du kannst auch MySQL, MongoDB, etc. verwenden:

• Füge den entsprechenden Service in docker-compose.yml hinzu
• Passe DATABASE_URL in .env an
• Installiere den entsprechenden Client (mysql2, mongoose, etc.)

📡 Ports

Development (lokal ohne Docker)

• Frontend: http://localhost:3000
• Backend: http://localhost:3001

Production (Docker Container)

• Application: http://localhost:8080 (Nginx + Backend)
• Database (PostgreSQL): Nur intern erreichbar (kein Port-Expose für Sicherheit)
• SQLite: Wird im /data Volume gespeichert (kein Port nötig)

💡 Tipp: Für lokales PostgreSQL-Debugging den Port in docker-compose.yml freigeben (Zeile 127-128)

🏗️ Projekt-Struktur

├── 📁 frontend/          # React App
│   ├── 📁 src/
│   ├── 📁 public/
│   └── 📄 package.json
├── 📁 backend/           # Express API
│   ├── 📁 src/
│   └── 📄 package.json
├── 📁 scripts/           # Helper Scripts
│   └── 🔧 kill-dev-processes.sh
├── 🐳 docker-compose.yml
├── 🐳 Dockerfile
├── ⚙️ .woodpecker.yml    # CI/CD
└── 📦 package.json       # Root Package

🔧 VS Code Tasks

Das Template enthält vorkonfigurierte VS Code Tasks:

• 🖥️ Backend - Backend im Watch-Modus starten
• 🌐 Frontend - Frontend starten
• 🛑 Terminate All Development Processes - Alle Dev-Prozesse beenden
• 📊 Show Development Processes Status - Status anzeigen

Öffne die Command Palette (Ctrl+Shift+P) und tippe "Tasks: Run Task".

🚢 Deployment

Mit Docker (empfohlen)

# Production Image erstellen
docker build -t fullstack-app .

# Mit Environment-Variablen starten
NODE_ENV=production npm run docker:prod

CI/CD mit Woodpecker

Das Template ist ready für Woodpecker CI. Konfiguration in .woodpecker.yml.

🤝 Development Workflow

1. Development starten: npm run docker:dev
2. Code ändern: Hot Reload ist aktiv
3. Tests ausführen: npm run test
4. Build testen: npm run build
5. Production testen: npm run docker:prod
6. Cleanup: npm run docker:clean

📝 Troubleshooting

Port bereits belegt

npm run kill:dev
npm run docker:down

Docker Problems

npm run docker:clean
docker system prune -a

Development-Prozesse hängen

./scripts/kill-dev-processes.sh

🔒 Sicherheits-Best-Practices

Vor dem Deployment

1. Environment-Variablen überprüfen

   • Alle Secrets in .env sind gesetzt und stark
   • NODE_ENV=production ist gesetzt
   • JWT_SECRET ist ein starker, zufälliger String
   • POSTGRES_PASSWORD ist sicher

2. CORS-Konfiguration anpassen

   // backend/src/index.ts - Zeile 36
   const allowedOrigins = [
     'https://your-domain.com',  // ⚠️ Anpassen!
     'https://www.your-domain.com'
   ];
   

3. Gitea Actions konfigurieren

   # .gittea/workflows/build.yaml - Zeile 17
   REGISTRY: git.csnetworkx.dev  # Deine Gitea-Instanz URL
   # Image-Name wird automatisch generiert: REGISTRY/owner/repo
   

   Secrets in Gitea setzen (Repository Settings → Secrets):

   • DOCKER_USERNAME → Dein Gitea Username
   • DOCKER_PASSWORD → Gitea Access Token mit Package-Rechten

Container Security

• ✅ Alle Container laufen als non-root (UID 1000 / 70)
• ✅ no-new-privileges Security Option aktiv
• ✅ Minimale Linux Capabilities (CAP_DROP: ALL)
• ✅ Resource Limits gegen DoS-Angriffe
• ✅ PostgreSQL verwendet scram-sha-256 Authentifizierung

API Security

• ✅ Helmet.js für Security Headers
• ✅ CORS mit Origin-Whitelist
• ✅ Input-Validierung mit express-validator
• ✅ Request Size Limits (10MB max)
• ✅ Error Handling ohne Stacktrace-Leaks in Production

CI/CD Security

Die Gitea Actions Pipeline führt automatisch aus:

• 🔍 Trivy Security Scans (Quellcode, Dependencies, Docker Images)
• 🔍 Dockerfile Lint (IaC-Konfiguration)
• 🔄 Automatische npm audit fix bei Schwachstellen
• 📊 Security Reports nach jedem Scan

Empfohlene Zusatz-Maßnahmen

1. Secrets Management: Verwende Vault oder Docker Secrets in Production
2. TLS/HTTPS: Nutze Traefik mit Let's Encrypt (Labels bereits im Dockerfile)
3. Monitoring: Implementiere Health-Checks und Alerting
4. Backups: Automatisiere PostgreSQL-Backups
5. Updates: Halte Dependencies aktuell (npm audit, npm outdated)
6. Penetration Testing: Führe regelmäßige Security-Audits durch

Weitere Ressourcen

• OWASP Top 10
• Docker Security Best Practices
• Node.js Security Checklist

📄 License

MIT