# ProxUI

Multi-Tenant-Konsole fuer Proxmox auf Basis von Go, Supabase Postgres/Auth, Redis/asynq und React.

## Architektur

- `backend/`: HTTP-API, Auth/JWT-Validierung, RBAC, DB-Zugriff und Proxmox-Orchestrierung
- `worker/`: asynchrone Jobs fuer Proxmox-Tasks, Reconciliation und Cleanup
- `console-proxy/`: Websocket-Proxy fuer noVNC/xterm.js ohne direkte Proxmox-Verbindung im Browser
- `platform/`: gemeinsame Go-Bausteine fuer Konfiguration, Logging und spaetere Querschnittsfunktionen
- `frontend/`: React/TypeScript/Vite-App fuer Kunden- und Admin-Workflows
- `migrations/`: versionierte SQL-Migrationen
- `deploy/`: lokale und spaetere Deployment-Artefakte

## Lokales Setup

1. Go >= 1.22 installieren.
2. Node.js >= 20 und npm installieren.
3. Docker Desktop oder kompatible Docker Engine installieren.
4. `.env.example` nach `.env` kopieren und lokale Werte setzen.
5. Abhaengigkeiten installieren: `npm install --prefix frontend`.
6. Go-Abhaengigkeiten installieren: `go work sync`.
7. Lokale Infrastruktur starten: `make dev`.
8. Migrationen ausfuehren: `make migrate`.
9. Backend starten: `go run ./backend/cmd/api`.
10. Console-Proxy starten: `go run ./console-proxy/cmd/console-proxy`.
11. Frontend starten: `npm run dev --prefix frontend`.

Supabase self-hosted liegt unter `deploy/supabase/`. Die lokale `deploy/supabase/.env` wird aus der offiziellen Vorlage erzeugt und nicht committed. Fuer App-`.env` die Werte `POSTGRES_PASSWORD`, `ANON_KEY` und `SERVICE_ROLE_KEY` aus `deploy/supabase/.env` uebernehmen.

Migrationen nutzen `MIGRATE_DATABASE_URL`, falls gesetzt. Andernfalls wird `DATABASE_DIRECT_URL` aus `.env` oder eine lokale Supavisor-URL aus `deploy/supabase/.env` verwendet.

Das Backend validiert Supabase-JWTs ueber `SUPABASE_JWKS_URL` und `SUPABASE_ISSUER`. Fuer das lokale Self-Hosted-Setup mit leerem JWKS wird zusaetzlich `SUPABASE_JWT_SECRET` als HS256-Fallback genutzt. Beim ersten authentifizierten Request synchronisiert das Backend den Supabase-User lazy nach `public.profiles`.

Lokale Dienste:

- Supabase API Gateway: `http://localhost:8000`
- Supabase Studio: `http://localhost:8000/project/default`
- Supavisor Session Pooler: `localhost:5432`
- Supavisor Transaction Pooler: `localhost:6543`

Aktuelle Targets:

- `make test`: Go-Tests
- `make build`: Go-Builds
- `make frontend-build`: Frontend-Production-Build
- `make lint`: Go Vet und Frontend-ESLint
- `make verify`: Lint, Tests und Builds
- `make dev-down`: Supabase-Stack stoppen
- `make dev-logs`: Supabase-Logs verfolgen
- `make migrate`: Migrationen auf den aktuellen Stand bringen
- `make migrate-down`: letzte Migration zurueckrollen
- `make migrate-version`: aktuelle Migrationsversion anzeigen

Backend-Endpunkte:

- `GET /healthz`: oeffentlicher Healthcheck
- `GET /me`: geschuetzt, synchronisiert `profiles` und gibt den authentifizierten Principal aus dem JWT zurueck

Frontend-Prototyp:

- Supabase Login/Registrierung ueber `VITE_SUPABASE_URL` und `VITE_SUPABASE_ANON_KEY`
- Backend-Profilcheck ueber `GET /me`
- Platzhalter-Ansichten fuer Projekte, VMs, SSH-Keys, Audit und Konsole

## CI

Forgejo Actions laufen unter `.forgejo/workflows/ci.yml`.

- `verify`: installiert Go/Node-Abhaengigkeiten und fuehrt `make verify` aus.
- `secret-scan`: fuehrt `zricethezav/gitleaks:v8.28.0` mit `.gitleaks.toml` aus. Die Konfiguration erlaubt nur dokumentierte Beispielwerte aus den offiziellen Supabase-Upstream-Dateien.

## Sicherheitsregeln

- Nur Backend, Worker und Console-Proxy sprechen mit Proxmox.
- Proxmox-Tokens werden nie im Frontend sichtbar und nie unverschluesselt gespeichert.
- Tenant-bezogene Queries muessen immer tenant-gefiltert sein.
- Secrets gehoeren in `.env` oder einen Secret-Manager, nie ins Repo.