gitadmin/INSIGHT-MVP
1
0
Fork 0
mirror of http://172.20.10.11:3000/gitadmin/INSIGHT-MVP.git synced 2026-06-24 20:06:39 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

chore: project initialization with infrastructure definition and structure

Browse source 
- Generate SSH deployment key (Ed25519) for server access
- Define complete server infrastructure (ProxmoxVE VM, Docker, networking)
- Create ACCESS.md with all connection details and SSH instructions
- Create INFRASTRUCTURE.md with VM setup guide and service architecture
- Set up project directory structure per briefing specification
- Add .env.example with all required environment variables
- Add .gitignore for Node.js/Docker/TypeScript project
- Create comprehensive README.md for developer onboarding
- Add Summarize.md changelog
- Include concept and briefing documents

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Thomas Reitz 2026-03-08 10:22:55 +01:00
parent e4c72dec21
commit 5f54bde55e
32 changed files with 878 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

77
.env.example Normal file
View file

@ -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=

0
.forgejo/workflows/.gitkeep Normal file
View file

63
.gitignore vendored Normal file
View file

@ -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

7
.keys/deploy_ed25519 Normal file
View file

@ -0,0 +1,7 @@
-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW
QyNTUxOQAAACDLk6asy8o6kyAzCeG8BBOKNiXhx94pi/jXoqXrgX4k6AAAAKBprr69aa6+
vQAAAAtzc2gtZWQyNTUxOQAAACDLk6asy8o6kyAzCeG8BBOKNiXhx94pi/jXoqXrgX4k6A
AAAECki73xblIq6Dx917rd90A5YrQwWVvp4RBMkU+RHsxNncuTpqzLyjqTIDMJ4bwEE4o2
JeHH3imL+NeipeuBfiToAAAAGWluc2lnaHQtZGVwbG95QHhpbmlvbi5sYW4BAgME
-----END OPENSSH PRIVATE KEY-----

1
.keys/deploy_ed25519.pub Normal file
View file

@ -0,0 +1 @@
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMuTpqzLyjqTIDMJ4bwEE4o2JeHH3imL+NeipeuBfiTo insight-deploy@xinion.lan

BIN
CLAUDE_BRIEFING.docx Normal file
View file

Binary file not shown.

BIN
INSIGHT_Konzept_v1.0.docx Normal file
View file

Binary file not shown.

206
README.md
View file

@ -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) |

66
Summarize.md Normal file
View file

@ -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

0
config/prometheus/.gitkeep Normal file
View file

0
config/step-ca/.gitkeep Normal file
View file

0
config/traefik/.gitkeep Normal file
View file

202
docs/ACCESS.md Normal file
View file

@ -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@<SERVER-IP>
# Mit SSH-Config (empfohlen):
# Eintrag in ~/.ssh/config:
Host insight-dev
HostName <SERVER-IP>
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@<SERVER-IP>
# 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@<IP>` |
| 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@<SERVER-IP>
# Grafana oeffnen (SSH-Tunnel)
ssh -L 3001:localhost:3001 -i .keys/deploy_ed25519 deploy@<SERVER-IP>
# 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
```

257
docs/INFRASTRUCTURE.md Normal file
View file

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

0
packages/core-service/prisma/.gitkeep Normal file
View file

0
packages/core-service/src/common/decorators/.gitkeep Normal file
View file

0
packages/core-service/src/common/filters/.gitkeep Normal file
View file

0
packages/core-service/src/common/guards/.gitkeep Normal file
View file

0
packages/core-service/src/common/interceptors/.gitkeep Normal file
View file

0
packages/core-service/src/config/.gitkeep Normal file
View file

0
packages/core-service/src/core/auth/.gitkeep Normal file
View file

0
packages/core-service/src/core/modules/.gitkeep Normal file
View file

0
packages/core-service/src/core/tenants/.gitkeep Normal file
View file

0
packages/core-service/src/core/users/.gitkeep Normal file
View file

0
packages/core-service/src/prisma/.gitkeep Normal file
View file

0
packages/frontend/public/.gitkeep Normal file
View file

0
packages/frontend/src/admin/.gitkeep Normal file
View file

0
packages/frontend/src/auth/.gitkeep Normal file
View file

0
packages/frontend/src/components/HelpPanel/.gitkeep Normal file
View file

0
packages/frontend/src/components/HelpTooltip/.gitkeep Normal file
View file

0
packages/frontend/src/shell/.gitkeep Normal file
View file

0
templates/cv/default/.gitkeep Normal file
View file