diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..4b5c5be --- /dev/null +++ b/.env.example @@ -0,0 +1,77 @@ +# ============================================================ +# INSIGHT MVP - Umgebungsvariablen +# ============================================================ +# Kopiere diese Datei nach .env und befuelle die Werte. +# .env wird NIEMALS in Git committed! +# ============================================================ + +# --- Allgemein --- +NODE_ENV=development +APP_PORT=3000 +APP_URL=https://insight-dev.xinion.lan +FRONTEND_URL=https://insight-dev.xinion.lan +LOG_LEVEL=info + +# --- PostgreSQL --- +DB_HOST=pgbouncer +DB_PORT=6432 +DB_USER=insight +DB_PASSWORD= # Sicheres Passwort setzen! +DB_NAME=platform_core +DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME} + +# Direktverbindung (fuer Prisma Migrate, umgeht PgBouncer) +DB_DIRECT_HOST=postgres +DB_DIRECT_PORT=5432 +DATABASE_URL_DIRECT=postgresql://${DB_USER}:${DB_PASSWORD}@${DB_DIRECT_HOST}:${DB_DIRECT_PORT}/${DB_NAME} + +# --- Redis --- +REDIS_HOST=redis +REDIS_PORT=6379 +REDIS_PASSWORD= # Optional, aber empfohlen + +# --- JWT (RS256) --- +JWT_PRIVATE_KEY_PATH=/app/keys/jwt-private.pem +JWT_PUBLIC_KEY_PATH=/app/keys/jwt-public.pem +JWT_ACCESS_TOKEN_EXPIRY=15m +JWT_REFRESH_TOKEN_EXPIRY=7d +JWT_ISSUER=insight-platform + +# --- Bcrypt --- +BCRYPT_COST=12 + +# --- CORS --- +CORS_ORIGINS=https://insight-dev.xinion.lan + +# --- Rate Limiting --- +THROTTLE_TTL=60000 +THROTTLE_LIMIT=200 + +# --- Traefik --- +TRAEFIK_DASHBOARD_USER=admin +TRAEFIK_DASHBOARD_PASSWORD= # htpasswd Hash + +# --- step-ca (mTLS) --- +STEP_CA_URL=https://step-ca:9000 +STEP_CA_FINGERPRINT= # step-ca Root CA Fingerprint + +# --- SMTP (fuer Einladungs-E-Mails) --- +SMTP_HOST= +SMTP_PORT=587 +SMTP_USER= +SMTP_PASSWORD= +SMTP_FROM=noreply@xinion.de + +# --- Observability --- +GRAFANA_ADMIN_USER=admin +GRAFANA_ADMIN_PASSWORD= # Sicheres Passwort setzen! + +# --- MS SSO (Beta - noch nicht aktiv) --- +# MS_SSO_CLIENT_ENCRYPTION_KEY= # AES-256 Key fuer Client Secret Verschluesselung + +# --- KI-Hilfe-Chat (optional) --- +# ANTHROPIC_API_KEY= # Claude API Key +# AI_CHAT_ENABLED=false + +# --- DeepL (optional, fuer Hilfesystem-Uebersetzungen) --- +# DEEPL_API_KEY= diff --git a/.forgejo/workflows/.gitkeep b/.forgejo/workflows/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..1017fdd --- /dev/null +++ b/.gitignore @@ -0,0 +1,63 @@ +# Dependencies +node_modules/ +.pnp +.pnp.js + +# Build output +dist/ +build/ +*.tsbuildinfo + +# Environment (NIEMALS committen!) +.env +.env.local +.env.*.local + +# IDE +.idea/ +.vscode/ +*.swp +*.swo +*~ + +# OS +.DS_Store +Thumbs.db + +# Docker volumes (lokal) +docker-data/ +postgres-data/ +redis-data/ +media-uploads/ + +# Logs +logs/ +*.log +npm-debug.log* + +# Test coverage +coverage/ + +# Prisma +packages/core-service/prisma/*.db +packages/core-service/prisma/*.db-journal + +# Generated Prisma Client +packages/core-service/node_modules/.prisma/ + +# Temporary files +tmp/ +temp/ +*.tmp + +# Certificates (generierte Zertifikate, nicht die CA-Config) +config/step-ca/secrets/ +config/step-ca/db/ +*.pem +*.key +*.crt +!config/step-ca/*.example + +# Backup files +*.bak +*.backup diff --git a/.keys/deploy_ed25519 b/.keys/deploy_ed25519 new file mode 100644 index 0000000..2e0d3f9 --- /dev/null +++ b/.keys/deploy_ed25519 @@ -0,0 +1,7 @@ +-----BEGIN OPENSSH PRIVATE KEY----- +b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW +QyNTUxOQAAACDLk6asy8o6kyAzCeG8BBOKNiXhx94pi/jXoqXrgX4k6AAAAKBprr69aa6+ +vQAAAAtzc2gtZWQyNTUxOQAAACDLk6asy8o6kyAzCeG8BBOKNiXhx94pi/jXoqXrgX4k6A +AAAECki73xblIq6Dx917rd90A5YrQwWVvp4RBMkU+RHsxNncuTpqzLyjqTIDMJ4bwEE4o2 +JeHH3imL+NeipeuBfiToAAAAGWluc2lnaHQtZGVwbG95QHhpbmlvbi5sYW4BAgME +-----END OPENSSH PRIVATE KEY----- diff --git a/.keys/deploy_ed25519.pub b/.keys/deploy_ed25519.pub new file mode 100644 index 0000000..1356590 --- /dev/null +++ b/.keys/deploy_ed25519.pub @@ -0,0 +1 @@ +ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMuTpqzLyjqTIDMJ4bwEE4o2JeHH3imL+NeipeuBfiTo insight-deploy@xinion.lan diff --git a/CLAUDE_BRIEFING.docx b/CLAUDE_BRIEFING.docx new file mode 100644 index 0000000..bb4b3a7 Binary files /dev/null and b/CLAUDE_BRIEFING.docx differ diff --git a/INSIGHT_Konzept_v1.0.docx b/INSIGHT_Konzept_v1.0.docx new file mode 100644 index 0000000..71b2ebf Binary files /dev/null and b/INSIGHT_Konzept_v1.0.docx differ diff --git a/README.md b/README.md index 6aa298a..a48c4ac 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,206 @@ -# INSIGHT-MVP +# INSIGHT MVP +Erweiterbare, mandantenfaehige SaaS-Business-Plattform der Xinion IT GmbH. + +--- + +## Inhaltsverzeichnis + +- [Projektuebersicht](#projektuebersicht) +- [Voraussetzungen](#voraussetzungen) +- [Setup (Entwicklungsumgebung)](#setup-entwicklungsumgebung) +- [Services & Ports](#services--ports) +- [Projektstruktur](#projektstruktur) +- [Branching & Commits](#branching--commits) +- [Dokumentation](#dokumentation) + +--- + +## Projektuebersicht + +INSIGHT ist eine Infrastruktur-Shell, auf die fachliche Module (erstes Modul: CRM) als isolierte Docker-Container aufgesetzt werden. Das System ist Cloud-Native und Kubernetes-ready. + +**Kernprinzipien:** +- Zero-Trust (mTLS intern) +- Stateless Backend-Services +- Separate Datenbank pro Mandant (Tenant-Isolation) +- Provider-Modell fuer Authentifizierung (lokal + MS SSO) + +**Tech Stack:** +TypeScript | NestJS | React + Vite | PostgreSQL | Prisma | Redis | Traefik | Docker + +--- + +## Voraussetzungen + +### Fuer lokale Entwicklung (MacBook) +- Git mit SSH-Zugang zu `git.xinion.lan` +- Docker Desktop oder Docker Engine +- Node.js >= 20 LTS +- npm oder yarn + +### Fuer den Server (ProxmoxVE VM) +- Ubuntu 24.04 LTS +- Docker Engine + Compose Plugin (kein Docker Desktop) +- SSH-Key aus `.keys/deploy_ed25519.pub` im `authorized_keys` des `deploy`-Users + +--- + +## Setup (Entwicklungsumgebung) + +### 1. Repository klonen +```bash +git clone ssh://git@git.xinion.lan/gitadmin/INSIGHT-MVP.git +cd INSIGHT-MVP +``` + +### 2. Environment konfigurieren +```bash +cp .env.example .env +# .env oeffnen und alle Werte befuellen (Passwoerter, Keys, etc.) +``` + +### 3. JWT-Schluessel generieren +```bash +# RS256 Schluessel fuer JWT-Signierung +mkdir -p packages/core-service/keys +openssl genpkey -algorithm RSA -out packages/core-service/keys/jwt-private.pem -pkeyopt rsa_keygen_bits:2048 +openssl rsa -pubout -in packages/core-service/keys/jwt-private.pem -out packages/core-service/keys/jwt-public.pem +``` + +### 4. Services starten +```bash +# Basis-Services +docker compose up -d + +# Mit Observability-Stack +docker compose -f docker-compose.yml -f docker-compose.observability.yml up -d +``` + +### 5. Datenbank-Migration +```bash +# Core-Schema +docker compose exec core npx prisma migrate deploy --schema=./prisma/core.schema.prisma + +# Tenant-Schema (wird beim Onboarding automatisch ausgefuehrt) +``` + +### 6. Health-Checks pruefen +```bash +curl http://localhost:3000/health # Core-Service +curl http://localhost:8080 # Frontend +``` + +### 7. Erster Login +- URL: https://insight-dev.xinion.lan (oder http://localhost) +- Initialer Admin-Account wird beim ersten Start via Seed-Script angelegt + +--- + +## Services & Ports + +| Service | Port (intern) | URL (extern via Traefik) | Beschreibung | +|---------------|---------------|----------------------------------|------------------------| +| Traefik | 80/443 | https://insight-dev.xinion.lan | API Gateway | +| Core-Service | 3000 | /api/v1/* | NestJS Backend | +| Frontend | 8080 | /* | React App | +| PostgreSQL | 5432 | - | Datenbank | +| PgBouncer | 6432 | - | Connection Pooler | +| Redis | 6379 | - | Cache & Event Bus | +| step-ca | 9000 | - | Interne CA (mTLS) | +| Grafana | 3001 | SSH-Tunnel | Monitoring Dashboards | + +--- + +## Projektstruktur + +``` +INSIGHT-MVP/ + docker-compose.yml # Basis-Services + docker-compose.observability.yml # Monitoring-Stack + .env.example # Alle Umgebungsvariablen (keine Werte!) + .gitignore + README.md # <- Du bist hier + + .keys/ # SSH Deployment Keys + deploy_ed25519 + deploy_ed25519.pub + + docs/ # Projektdokumentation + INFRASTRUCTURE.md # Server & VM Konfiguration + ACCESS.md # Zugangsdaten & SSH-Infos + + packages/ + core-service/ # NestJS Backend + src/ + core/ + auth/ # Auth-Service (Provider-Modell) + users/ # User-Verwaltung + tenants/ # Tenant-Verwaltung + modules/ # Module-Registry + common/ + guards/ # JwtGuard, RolesGuard, ScopeGuard + decorators/ # @Public(), @Roles(), @RequireScope() + filters/ # GlobalExceptionFilter + interceptors/ # Logging, Response-Transformation + config/ # Env-Validierung (class-validator) + prisma/ # PrismaService + TenantPrismaService + prisma/ + core.schema.prisma # platform_core Tabellen + tenant.schema.prisma # Tenant-DB Tabellen + + frontend/ # React + Vite + src/ + shell/ # App-Shell (Layout, Routing) + auth/ # Login, 2FA, Token-Management + admin/ # Admin-Bereich + components/ # Shared UI-Komponenten + + config/ # Service-Konfigurationen + traefik/ + prometheus/ + step-ca/ + + .forgejo/ + workflows/ # CI/CD Pipelines + ci.yml + develop.yml + release.yml +``` + +--- + +## Branching & Commits + +### Branching-Strategie: GitFlow + +| Branch | Zweck | +|------------- |------------------------------------------| +| `main` | Produktion (nur via Merge, geschuetzt) | +| `develop` | Integration (nur via Merge, geschuetzt) | +| `feature/*` | Neue Features | +| `fix/*` | Bugfixes | +| `hotfix/*` | Kritische Fixes auf main | + +### Commit-Format: Conventional Commits +``` +feat: Neues Feature +fix: Bugfix +chore: Tooling, Dependencies +docs: Dokumentation +refactor: Refactoring ohne Funktionsaenderung +``` + +--- + +## Dokumentation + +| Dokument | Beschreibung | +|---------------------------------|-------------------------------------------| +| `README.md` | Dieses Dokument (Onboarding) | +| `docs/INFRASTRUCTURE.md` | Server-Infrastruktur & VM-Setup | +| `docs/ACCESS.md` | Zugangsdaten & SSH-Verbindungen | +| `INSIGHT_Konzept_v1.0.docx` | Vollstaendiges Konzeptdokument (23 Kap.) | +| `CLAUDE_BRIEFING.docx` | Entwickler-Briefing (Kurzreferenz) | +| `Summarize.md` | Aenderungsprotokoll (aktueller Stand) | +| `RUNBOOK.md` | Disaster Recovery Anleitung (folgt) | diff --git a/Summarize.md b/Summarize.md new file mode 100644 index 0000000..ccab691 --- /dev/null +++ b/Summarize.md @@ -0,0 +1,66 @@ +# INSIGHT MVP - Aenderungsprotokoll + +## Stand: 2026-03-08 + +### Aktueller Sprint: Sprint 1 (Alpha) + +--- + +### Aenderungen in dieser Session + +#### Projektinitialisierung & Infrastruktur-Definition + +**Was wurde gemacht:** + +1. **SSH Deployment Key erstellt** + - Ed25519-Schluessel unter `.keys/deploy_ed25519` generiert + - Public Key muss auf dem Entwicklungsserver und in Forgejo hinterlegt werden + - Key-Kommentar: `insight-deploy@xinion.lan` + +2. **Infrastruktur-Definition erstellt** (`docs/INFRASTRUCTURE.md`) + - ProxmoxVE VM-Spezifikation: Ubuntu 24.04 LTS, 4 vCPU, 8 GB RAM, 60 GB SSD + - Docker-Netzwerk-Architektur mit 3 isolierten Netzwerken + - Komplette Service-Landschaft definiert (Traefik, Core, Frontend, PostgreSQL, PgBouncer, Redis, step-ca) + - Observability-Stack definiert (Prometheus, Grafana, Loki, Tempo, Promtail, cAdvisor) + - Schritt-fuer-Schritt VM-Setup Anleitung + +3. **Zugangsdaten-Dokument erstellt** (`docs/ACCESS.md`) + - Git Repository Zugangsdaten + - SSH-Key Dokumentation und Verwendung + - Server-Zugangsdaten (Platzhalter fuer IP) + - Alle Service-Ports dokumentiert + - Deployment-Pfad dokumentiert + - Wichtige Befehle (MacBook & Server) + +4. **Projektstruktur aufgesetzt** + - Verzeichnisstruktur gemaess Briefing angelegt + - packages/core-service/ (NestJS Backend) + - packages/frontend/ (React + Vite) + - config/ (Traefik, Prometheus, step-ca) + - .forgejo/workflows/ (CI/CD) + +5. **Basis-Konfigurationsdateien erstellt** + - `.gitignore` - alle relevanten Ausschluesse + - `.env.example` - alle Umgebungsvariablen dokumentiert (ohne Werte) + - `README.md` - vollstaendiges Onboarding-Dokument + +--- + +### Naechste Schritte + +- [ ] VM in ProxmoxVE erstellen und konfigurieren +- [ ] SSH Deploy Key auf Server und in Forgejo hinterlegen +- [ ] `docker-compose.yml` erstellen (alle Basis-Services) +- [ ] `docker-compose.observability.yml` erstellen +- [ ] NestJS Core-Service implementieren (Auth, Users, Tenants) +- [ ] Prisma-Schemas erstellen (core + tenant) +- [ ] React Frontend-Shell implementieren +- [ ] CI/CD Pipelines in Forgejo Actions definieren + +--- + +### Offene Fragen / Abhaengigkeiten + +- Server-IP wird erst bei VM-Erstellung vergeben +- DNS-Eintraege (insight-dev.xinion.lan) muessen konfiguriert werden +- Forgejo Deploy Key muss manuell hinterlegt werden diff --git a/config/prometheus/.gitkeep b/config/prometheus/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/config/step-ca/.gitkeep b/config/step-ca/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/config/traefik/.gitkeep b/config/traefik/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/ACCESS.md b/docs/ACCESS.md new file mode 100644 index 0000000..69b8998 --- /dev/null +++ b/docs/ACCESS.md @@ -0,0 +1,202 @@ +# INSIGHT MVP - Zugangsdaten & Server-Zugriff + +> **Dieses Dokument wird laufend aktualisiert und enthaelt alle relevanten +> Zugangsinformationen fuer das Projekt.** + +--- + +## 1. Git Repository + +| Parameter | Wert | +|------------------|-----------------------------------------------------| +| Git-Server | Forgejo (self-hosted) | +| URL | `git.xinion.lan` | +| Repository (SSH) | `ssh://git@git.xinion.lan/gitadmin/INSIGHT-MVP.git` | +| Repository (HTTP)| `https://git.xinion.lan/gitadmin/INSIGHT-MVP` | +| Organisation | `gitadmin` | +| Zugriff | SSH Key-basiert | +| CI/CD | Forgejo Actions (GitHub Actions kompatibel) | +| Container Registry | `git.xinion.lan` (Forgejo built-in) | + +--- + +## 2. SSH Deployment Key + +Der Deployment Key liegt im Repository unter `.keys/`: + +| Datei | Beschreibung | +|------------------------------|-----------------------| +| `.keys/deploy_ed25519` | Private Key (Ed25519) | +| `.keys/deploy_ed25519.pub` | Public Key | + +### Public Key (zur Hinterlegung auf Servern) +``` +ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMuTpqzLyjqTIDMJ4bwEE4o2JeHH3imL+NeipeuBfiTo insight-deploy@xinion.lan +``` + +### SSH-Verbindung zum Server +```bash +# Verbindung zum Entwicklungsserver: +ssh -i .keys/deploy_ed25519 deploy@ + +# Mit SSH-Config (empfohlen): +# Eintrag in ~/.ssh/config: +Host insight-dev + HostName + User deploy + IdentityFile ~/git.xinion.lan/INSIGHT-MVP/.keys/deploy_ed25519 + StrictHostKeyChecking accept-new +``` + +### Wo der Public Key hinterlegt werden muss +1. **Entwicklungsserver (VM)**: `/home/deploy/.ssh/authorized_keys` +2. **Forgejo**: Repository Settings > Deploy Keys (fuer CI/CD) + +--- + +## 3. Entwicklungsserver (ProxmoxVE VM) + +| Parameter | Wert | +|------------------|-----------------------------------------| +| **Hostname** | `insight-dev-01` | +| **OS** | Ubuntu 24.04 LTS | +| **IP** | _wird bei VM-Erstellung vergeben_ | +| **SSH-Port** | 22 | +| **SSH-User** | `deploy` | +| **SSH-Key** | `.keys/deploy_ed25519` | +| **Docker** | Docker Engine + Compose Plugin | +| **Projekt-Pfad** | `/home/deploy/insight/` | + +### Schnellzugriff nach VM-Setup +```bash +# SSH auf den Server +ssh -i .keys/deploy_ed25519 deploy@ + +# Status aller Container pruefen +docker compose ps + +# Logs eines Services +docker compose logs -f core + +# Neustart aller Services +docker compose restart + +# Nur Backend neustarten +docker compose restart core +``` + +--- + +## 4. Service-Ports (auf der VM) + +| Service | Interner Port | Externer Port | URL | +|-----------------|---------------|---------------|----------------------------------| +| Traefik (HTTP) | 80 | 80 | http://insight-dev.xinion.lan | +| Traefik (HTTPS) | 443 | 443 | https://insight-dev.xinion.lan | +| Traefik Dashboard | 8080 | - | Nur intern | +| Core-Service | 3000 | - | Via Traefik: /api/v1/* | +| Frontend | 8080 | - | Via Traefik: /* | +| PostgreSQL | 5432 | - | Nur intern (Docker-Netzwerk) | +| PgBouncer | 6432 | - | Nur intern (Docker-Netzwerk) | +| Redis | 6379 | - | Nur intern (Docker-Netzwerk) | +| step-ca | 9000 | - | Nur intern (Docker-Netzwerk) | + +### Observability (nur intern, kein oeffentlicher Zugriff) + +| Service | Port | Zugriff | +|-----------------|-------|----------------------------------| +| Grafana | 3001 | SSH-Tunnel: `ssh -L 3001:localhost:3001 deploy@` | +| Prometheus | 9090 | Nur intern | +| Loki | 3100 | Nur intern | +| Tempo | 3200 | Nur intern | + +--- + +## 5. Datenbank-Zugangsdaten + +> **Echte Passwoerter stehen in der `.env`-Datei auf dem Server. +> Niemals in Git committen!** + +| Parameter | Wert (Platzhalter) | +|-------------------|---------------------------------| +| DB-Host | `pgbouncer` (via Docker-Netzwerk) | +| DB-Port | `6432` | +| Core-DB-Name | `platform_core` | +| Tenant-DB-Schema | `tenant_{slug}` | +| DB-User | Siehe `.env` -> `DB_USER` | +| DB-Passwort | Siehe `.env` -> `DB_PASSWORD` | + +--- + +## 6. Container Registry + +| Parameter | Wert | +|------------------|-----------------------------------------------------| +| Registry-URL | `git.xinion.lan` | +| Image-Prefix | `git.xinion.lan/gitadmin/insight-{service}` | +| Authentifizierung| Forgejo Login-Credentials | + +### Image-Namen +``` +git.xinion.lan/gitadmin/insight-core:latest +git.xinion.lan/gitadmin/insight-core:develop +git.xinion.lan/gitadmin/insight-core:v0.1.0 +git.xinion.lan/gitadmin/insight-frontend:latest +``` + +--- + +## 7. Deployment-Pfad + +``` +MacBook (Entwicklung) + | + | git push + v +Forgejo (git.xinion.lan) + | + | Forgejo Actions CI/CD + | - Lint, Type-Check, Tests, Build + | - Docker Image bauen & pushen + v +Server (insight-dev-01) + | + | docker compose pull && docker compose up -d + v +Laufende Anwendung +``` + +--- + +## 8. Wichtige Befehle + +### Vom MacBook aus +```bash +# Code pushen +git push origin develop + +# SSH auf Server +ssh -i .keys/deploy_ed25519 deploy@ + +# Grafana oeffnen (SSH-Tunnel) +ssh -L 3001:localhost:3001 -i .keys/deploy_ed25519 deploy@ +# Dann im Browser: http://localhost:3001 +``` + +### Auf dem Server +```bash +# Alle Services starten +docker compose up -d + +# Mit Observability +docker compose -f docker-compose.yml -f docker-compose.observability.yml up -d + +# Health-Check +curl http://localhost:3000/health + +# Datenbank-Migration +docker compose exec core npx prisma migrate deploy + +# Logs folgen +docker compose logs -f --tail=100 +``` diff --git a/docs/INFRASTRUCTURE.md b/docs/INFRASTRUCTURE.md new file mode 100644 index 0000000..71d2c44 --- /dev/null +++ b/docs/INFRASTRUCTURE.md @@ -0,0 +1,257 @@ +# INSIGHT MVP - Infrastruktur-Definition + +## 1. Uebersicht + +Die gesamte INSIGHT-Plattform laeuft auf einer ProxmoxVE-VM im internen Netzwerk. +Alle Services werden als Docker-Container betrieben. + +--- + +## 2. VM-Konfiguration (ProxmoxVE) + +| Komponente | Spezifikation | +|-----------------|----------------------------------------| +| **Hostname** | `insight-dev-01` | +| **OS** | Ubuntu 24.04 LTS (Server) | +| **CPU** | 4 vCPUs | +| **RAM** | 8 GB (16 GB empfohlen) | +| **Storage** | 60 GB SSD | +| **Netzwerk** | Feste interne IP (wird bei Setup vergeben) | +| **SSH-Zugang** | Key-basiert (Ed25519), kein Passwort-Login | +| **User** | `deploy` (non-root, Mitglied der `docker`-Gruppe) | + +### Betriebssystem-Hardening + +- SSH: nur Key-basiert (`PasswordAuthentication no`) +- Firewall (ufw): + - Port 22 (SSH) - nur internes Netzwerk + - Port 80 (HTTP -> Redirect auf HTTPS) + - Port 443 (HTTPS) + - Alle anderen Ports: DENY +- Automatische Sicherheitsupdates: `unattended-upgrades` aktiviert +- Fail2ban fuer SSH-Brute-Force-Schutz + +--- + +## 3. Software auf der VM + +| Software | Version | Installationsmethode | +|---------------------|-------------|--------------------------------| +| Docker Engine | >= 27.x | Official Docker APT Repository | +| Docker Compose | Plugin | Mitgeliefert mit Docker Engine | +| Git | >= 2.x | APT | +| ufw | Aktuell | APT (vorinstalliert) | +| fail2ban | Aktuell | APT | +| unattended-upgrades | Aktuell | APT (vorinstalliert) | + +**Kein** Docker Desktop, kein Node.js, kein npm auf der VM. +Alles laeuft in Containern. + +--- + +## 4. Docker-Netzwerk-Architektur + +``` + Internet / Internes Netz + | + [ Port 80/443 ] + | + +-------v--------+ + | Traefik | API Gateway, SSL-Terminierung, + | (Gateway) | Rate Limiting, mTLS-Terminierung + +---+-------+----+ + | | + +---------+ +---------+ + | | + +-------v--------+ +-------v--------+ + | Core-Service | | Frontend | + | (NestJS) | | (React/Vite) | + | Port: 3000 | | Port: 8080 | + +---+--------+----+ +----------------+ + | | + +-----v--+ +--v------+ + | Redis | | PgBouncer| + | :6379 | | :6432 | + +----+----+ +----+-----+ + | | + | +----v------+ + | | PostgreSQL | + | | :5432 | + +-------+------------+ +``` + +### Docker-Netzwerke + +| Netzwerk | Zweck | +|---------------|-------------------------------------------------| +| `insight-web` | Traefik <-> Core-Service, Frontend (extern erreichbar) | +| `insight-db` | Core-Service <-> PgBouncer <-> PostgreSQL (intern) | +| `insight-cache`| Core-Service <-> Redis (intern) | + +### mTLS (step-ca) + +Alle interne Kommunikation zwischen Containern wird ueber mTLS abgesichert. +step-ca (Smallstep) fungiert als interne Certificate Authority. + +| Komponente | Zertifikat | +|---------------|-------------------------------| +| Traefik | Wildcard fuer externe Domain | +| Core-Service | `core-service.insight.local` | +| Frontend | `frontend.insight.local` | +| PostgreSQL | `postgres.insight.local` | +| Redis | `redis.insight.local` | +| PgBouncer | `pgbouncer.insight.local` | + +--- + +## 5. Container-Services (docker-compose.yml) + +| Service | Image | Port (intern) | Port (extern) | Beschreibung | +|---------------|--------------------------------|---------------|---------------|-------------------------------| +| `traefik` | traefik:3 | 80, 443, 8080 | 80, 443 | API Gateway, Reverse Proxy | +| `core` | insight-core:latest | 3000 | - | NestJS Backend | +| `frontend` | insight-frontend:latest | 8080 | - | React App (Nginx served) | +| `postgres` | postgres:16-alpine | 5432 | - | Datenbank | +| `pgbouncer` | edoburu/pgbouncer:latest | 6432 | - | Connection Pooler | +| `redis` | redis:7-alpine | 6379 | - | Cache, Sessions, Event Bus | +| `step-ca` | smallstep/step-ca:latest | 9000 | - | Interne Certificate Authority | + +--- + +## 6. Observability-Stack (docker-compose.observability.yml) + +| Service | Image | Port (intern) | Beschreibung | +|------------------|---------------------------------|---------------|-----------------------------| +| `prometheus` | prom/prometheus:latest | 9090 | Metrics-Storage | +| `grafana` | grafana/grafana:latest | 3001 | Dashboards & Alerting | +| `loki` | grafana/loki:latest | 3100 | Log-Storage | +| `tempo` | grafana/tempo:latest | 3200, 4317 | Tracing-Backend | +| `promtail` | grafana/promtail:latest | - | Log-Collector | +| `cadvisor` | gcr.io/cadvisor/cadvisor:latest | 8081 | Container-Metrics | +| `postgres-exp` | prometheuscommunity/postgres-exporter | 9187 | DB-Metrics | + +**Grafana ist NICHT oeffentlich erreichbar** - nur ueber SSH-Tunnel oder internes Netz. + +--- + +## 7. Datenbank-Struktur + +``` +PostgreSQL-Server + platform_core <- Einmalig: Tenants, Users, Roles, Modules, Help + tenant_{slug} <- Pro Mandant (z.B. tenant_acme_corp) +``` + +| Datenbank | Zweck | +|-----------------|-----------------------------------------------------| +| `platform_core` | Plattform-Verwaltung (Users, Tenants, Roles, Modules) | +| `tenant_{slug}` | Mandant-Daten (Profile, Stammdaten, Moduldaten) | + +--- + +## 8. DNS / Domains + +| Eintrag | Ziel | Zweck | +|----------------------------|--------------------|-------------------------------| +| `insight-dev.xinion.lan` | VM-IP | Entwicklungs-Frontend | +| `api.insight-dev.xinion.lan` | VM-IP | API-Endpunkt | +| `git.xinion.lan` | Forgejo-Server | Git Repository & CI/CD | + +--- + +## 9. Backup (Alpha/Dev) + +| Was | Wohin | Frequenz | +|----------------------|----------------------------------------|-----------| +| PostgreSQL (alle DBs)| Separates ProxmoxVE Volume | Taeglich | +| Media-Dateien | Separates ProxmoxVE Volume | Taeglich | +| Konfiguration | Git Repository (ohne .env) | Per Commit| + +--- + +## 10. VM-Setup Anleitung (Schritt fuer Schritt) + +### 10.1 VM in ProxmoxVE erstellen +```bash +# ProxmoxVE Web-UI oder CLI: +# - Template: Ubuntu 24.04 LTS Cloud-Init +# - CPU: 4 Cores +# - RAM: 8192 MB +# - Disk: 60 GB (SCSI, SSD-backed) +# - Network: vmbr0, DHCP oder feste IP +``` + +### 10.2 Basis-Setup nach Erstinstallation +```bash +# System aktualisieren +sudo apt update && sudo apt upgrade -y + +# Deploy-User anlegen +sudo adduser --disabled-password deploy +sudo usermod -aG sudo deploy + +# SSH-Key fuer Deploy-User hinterlegen +sudo mkdir -p /home/deploy/.ssh +sudo cp /path/to/deploy_ed25519.pub /home/deploy/.ssh/authorized_keys +sudo chown -R deploy:deploy /home/deploy/.ssh +sudo chmod 700 /home/deploy/.ssh +sudo chmod 600 /home/deploy/.ssh/authorized_keys + +# SSH haerten +sudo sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config +sudo sed -i 's/PermitRootLogin yes/PermitRootLogin no/' /etc/ssh/sshd_config +sudo systemctl restart sshd +``` + +### 10.3 Firewall +```bash +sudo ufw default deny incoming +sudo ufw default allow outgoing +sudo ufw allow 22/tcp # SSH +sudo ufw allow 80/tcp # HTTP +sudo ufw allow 443/tcp # HTTPS +sudo ufw enable +``` + +### 10.4 Docker installieren +```bash +# Docker Official GPG Key +sudo apt install -y ca-certificates curl +sudo install -m 0755 -d /etc/apt/keyrings +sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \ + -o /etc/apt/keyrings/docker.asc +sudo chmod a+r /etc/apt/keyrings/docker.asc + +# Docker Repo hinzufuegen +echo "deb [arch=$(dpkg --print-architecture) \ + signed-by=/etc/apt/keyrings/docker.asc] \ + https://download.docker.com/linux/ubuntu \ + $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + +# Docker installieren +sudo apt update +sudo apt install -y docker-ce docker-ce-cli containerd.io \ + docker-buildx-plugin docker-compose-plugin + +# Deploy-User zur docker-Gruppe +sudo usermod -aG docker deploy +``` + +### 10.5 Fail2ban +```bash +sudo apt install -y fail2ban +sudo systemctl enable fail2ban +sudo systemctl start fail2ban +``` + +### 10.6 Projekt deployen +```bash +# Als deploy-User: +su - deploy +git clone git@git.xinion.lan:gitadmin/INSIGHT-MVP.git ~/insight +cd ~/insight +cp .env.example .env +# .env befuellen mit echten Werten +docker compose up -d +``` diff --git a/packages/core-service/prisma/.gitkeep b/packages/core-service/prisma/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/core-service/src/common/decorators/.gitkeep b/packages/core-service/src/common/decorators/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/core-service/src/common/filters/.gitkeep b/packages/core-service/src/common/filters/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/core-service/src/common/guards/.gitkeep b/packages/core-service/src/common/guards/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/core-service/src/common/interceptors/.gitkeep b/packages/core-service/src/common/interceptors/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/core-service/src/config/.gitkeep b/packages/core-service/src/config/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/core-service/src/core/auth/.gitkeep b/packages/core-service/src/core/auth/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/core-service/src/core/modules/.gitkeep b/packages/core-service/src/core/modules/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/core-service/src/core/tenants/.gitkeep b/packages/core-service/src/core/tenants/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/core-service/src/core/users/.gitkeep b/packages/core-service/src/core/users/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/core-service/src/prisma/.gitkeep b/packages/core-service/src/prisma/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/frontend/public/.gitkeep b/packages/frontend/public/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/frontend/src/admin/.gitkeep b/packages/frontend/src/admin/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/frontend/src/auth/.gitkeep b/packages/frontend/src/auth/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/frontend/src/components/HelpPanel/.gitkeep b/packages/frontend/src/components/HelpPanel/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/frontend/src/components/HelpTooltip/.gitkeep b/packages/frontend/src/components/HelpTooltip/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/packages/frontend/src/shell/.gitkeep b/packages/frontend/src/shell/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/templates/cv/default/.gitkeep b/templates/cv/default/.gitkeep new file mode 100644 index 0000000..e69de29