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