mirror of http://172.20.10.11:3000/gitadmin/INSIGHT-MVP.git synced 2026-06-24 21:16:40 +02:00

Thomas Reitz 5f54bde55e chore: project initialization with infrastructure definition and structure

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

2026-03-08 10:22:55 +01:00

9.5 KiB

Raw Blame History

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

# 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

# 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

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

# 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

sudo apt install -y fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

10.6 Projekt deployen

# 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

9.5 KiB Raw Blame History