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

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

### 2. Dependencies installieren

```bash
npm run install:all
```

## 🏃‍♂️ Development

### Lokale Entwicklung (ohne Docker)

```bash
# 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)

```bash
# 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

```bash
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

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

### Logs & Debugging

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

### Cleanup

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

### Manuelle Docker Commands

```bash
# 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

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

### Production Build

```bash
# 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

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

## 🧹 Cleanup

```bash
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**:
   ```bash
   cp .env.example .env
   ```

2. **Generiere sichere Secrets**:
   ```bash
   # JWT Secret generieren
   openssl rand -base64 32

   # PostgreSQL Passwort generieren
   openssl rand -base64 32
   ```

3. **Fülle die `.env` Datei mit deinen Werten**:
   ```bash
   # 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](.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](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)

```bash
# 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

```bash
npm run kill:dev
npm run docker:down
```

### Docker Problems

```bash
npm run docker:clean
docker system prune -a
```

### Development-Prozesse hängen

```bash
./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**
   ```typescript
   // backend/src/index.ts - Zeile 36
   const allowedOrigins = [
     'https://your-domain.com',  // ⚠️ Anpassen!
     'https://www.your-domain.com'
   ];
   ```

3. **Gitea Actions konfigurieren**
   ```yaml
   # .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](https://owasp.org/www-project-top-ten/)
- [Docker Security Best Practices](https://docs.docker.com/develop/security-best-practices/)
- [Node.js Security Checklist](https://blog.risingstack.com/node-js-security-checklist/)

## 📄 License

[MIT](LICENSE)