NexaPG/README.md

NexaPG - PostgreSQL Monitoring Stack

Docker-basierte Monitoring-Loesung fuer mehrere PostgreSQL-Targets mit FastAPI + React.

Features

• Multi-target PostgreSQL Monitoring (remote)
• Polling Collector fuer:
  • pg_stat_database
  • pg_stat_activity
  • pg_stat_bgwriter
  • pg_locks
  • pg_stat_statements (falls auf Target aktiviert)
• Core-DB fuer:
  • User/Auth/RBAC (admin, operator, viewer)
  • Targets (Credentials verschluesselt via Fernet)
  • Metrics / Query Stats
  • Audit Logs
• Auth mit JWT Access/Refresh Tokens
• FastAPI + SQLAlchemy async + Alembic
• React (Vite) Frontend mit:
  • Login/Logout
  • Dashboard
  • Target Detail mit Charts
  • Query Insights
  • Admin User Management
• Health Endpoints:
  • /api/v1/healthz
  • /api/v1/readyz

Struktur

• backend/ FastAPI App
• frontend/ React (Vite) App
• ops/ Scripts
• docker-compose.yml Stack
• .env.example Konfigurationsvorlage

Schnellstart

1. Env-Datei erstellen:

cp .env.example .env

2. Fernet Key setzen:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Wert in .env bei ENCRYPTION_KEY eintragen.

3. Stack starten:

make up

4. URLs:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000/api/v1
• OpenAPI: http://localhost:8000/docs

Default Admin (aus .env):

• Email: admin@example.com
• Passwort: ChangeMe123!

Commands

make up
make down
make logs
make migrate

API (Minimum)

• POST /api/v1/auth/login
• POST /api/v1/auth/refresh
• POST /api/v1/auth/logout
• GET /api/v1/me
• CRUD: GET/POST/PUT/DELETE /api/v1/targets
• GET /api/v1/targets/{id}/metrics?from=&to=&metric=
• GET /api/v1/targets/{id}/locks
• GET /api/v1/targets/{id}/activity
• GET /api/v1/targets/{id}/top-queries
• Admin-only CRUD users:
  • GET /api/v1/admin/users
  • POST /api/v1/admin/users
  • PUT /api/v1/admin/users/{user_id}
  • DELETE /api/v1/admin/users/{user_id}

Security Notes

• Keine Secrets hardcoded
• Passwoerter als Argon2 Hash
• Target-Credentials verschluesselt (Fernet)
• CORS via Env steuerbar
• Audit Logs fuer Login / Logout / Target- und User-Aenderungen
• Rate limiting: Platzhalter (kann spaeter middleware-basiert ergaenzt werden)

Wichtiger Hinweis zu pg_stat_statements

Auf jedem monitored Target muss pg_stat_statements aktiviert sein, sonst bleiben Query Insights leer. Beispiel:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;