mirror of
http://172.20.10.11:3000/gitadmin/INSIGHT-MVP.git
synced 2026-06-24 22:46:39 +02:00
5f54bde55e
- 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>
257 lines
9.5 KiB
Markdown
257 lines
9.5 KiB
Markdown
# 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
|
|
```
|