nessi/NexaPG
1
0
Fork 0
Code Issues 19 Pull Requests Actions Packages Projects Releases 13 Activity

Standardize English language usage and improve environment configuration

Browse Source 
Replaced German text with English across the frontend UI for consistency and accessibility. Enhanced clarity in `.env.example` and `README.md`, adding detailed comments for environment variables and prerequisites. Improved documentation for setup, security, and troubleshooting.
This commit is contained in:
Sascha Nesterovic
2026-02-12 11:25:02 +01:00
parent 6c660239d0
commit 5b34c08851
9 changed files with 235 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
.env.example
View File

@@ -1,29 +1,57 @@
# App
# ------------------------------
# Application
# ------------------------------
# Display name used in API docs/UI.
APP_NAME=NexaPG Monitor
# Runtime environment: dev | staging | prod | test
ENVIRONMENT=dev
# Backend log level: DEBUG | INFO | WARNING | ERROR
LOG_LEVEL=INFO
# Core DB
# ------------------------------
# Core Database (internal metadata DB)
# ------------------------------
# Database that stores users, targets, metrics, query stats, and audit logs.
DB_NAME=nexapg
DB_USER=nexapg
DB_PASSWORD=nexapg
# Host port mapped to the internal PostgreSQL container port 5432.
DB_PORT=5433
# Backend
# ------------------------------
# Backend API
# ------------------------------
# Host port mapped to backend container port 8000.
BACKEND_PORT=8000
# JWT signing secret. Change this in every non-local environment.
JWT_SECRET_KEY=change_this_super_secret
JWT_ALGORITHM=HS256
# Access token lifetime in minutes.
JWT_ACCESS_TOKEN_MINUTES=15
# Refresh token lifetime in minutes (10080 = 7 days).
JWT_REFRESH_TOKEN_MINUTES=10080
# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
# Key used to encrypt monitored target passwords at rest.
# Generate with:
# python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
ENCRYPTION_KEY=REPLACE_WITH_FERNET_KEY
# Dev: set to * to allow all origins (credentials disabled automatically)
# Allowed CORS origins for browser clients.
# Use comma-separated values, e.g.:
# CORS_ORIGINS=http://localhost:5173,https://nexapg.example.com
# Dev-only shortcut:
# CORS_ORIGINS=*
CORS_ORIGINS=http://localhost:5173,http://localhost:8080
# Target polling interval in seconds.
POLL_INTERVAL_SECONDS=30
# Initial admin bootstrap user (created on first startup if not present).
INIT_ADMIN_EMAIL=admin@example.com
INIT_ADMIN_PASSWORD=ChangeMe123!
# ------------------------------
# Frontend
# ------------------------------
# Host port mapped to frontend container port 80.
FRONTEND_PORT=5173
# For reverse proxy + SSL prefer relative path to avoid mixed-content.
# Base API URL used at frontend build time.
# For reverse proxy + SSL, keep this relative to avoid mixed-content issues.
# Example direct mode: VITE_API_URL=http://localhost:8000/api/v1
VITE_API_URL=/api/v1

169
README.md
View File

@@ -1,113 +1,176 @@
# NexaPG - PostgreSQL Monitoring Stack
Docker-basierte Monitoring-Loesung fuer mehrere PostgreSQL-Targets mit FastAPI + React.
NexaPG is a Docker-based PostgreSQL monitoring platform for multiple remote targets, built with FastAPI + React.
## Features
## What it includes
- Multi-target PostgreSQL Monitoring (remote)
- Polling Collector fuer:
- Multi-target PostgreSQL monitoring (remote instances)
- Polling collector for:
- `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:
- `pg_stat_statements` (if enabled on target)
- Core metadata database for:
- Authentication and RBAC (`admin`, `operator`, `viewer`)
- Monitored target configuration (encrypted credentials)
- Metrics and query stats
- Audit logs
- JWT auth (access + refresh)
- FastAPI + SQLAlchemy async + Alembic migrations
- React (Vite) frontend with:
- Login/logout
- Dashboard overview
- Target detail with charts and database overview
- Query insights
- Admin user management
- Health endpoints:
- `/api/v1/healthz`
- `/api/v1/readyz`
## Struktur
## Repository structure
- `backend/` FastAPI App
- `frontend/` React (Vite) App
- `ops/` Scripts
- `docker-compose.yml` Stack
- `.env.example` Konfigurationsvorlage
- `backend/` FastAPI application
- `frontend/` React (Vite) application
- `ops/` helper scripts and env template copy
- `docker-compose.yml` full stack definition
- `.env.example` environment template
## Schnellstart
## Prerequisites
1. Env-Datei erstellen:
Install these before starting:
- Docker Engine 24+
- Docker Compose v2+
- GNU Make (optional, for `make up/down/logs/migrate`)
- Open ports on your host:
- frontend: `5173` (default)
- backend: `8000` (or your `BACKEND_PORT`)
- core DB: `5433` (or your `DB_PORT`)
Optional but recommended:
- `psql` client for troubleshooting target connectivity
## Quick start
1. Create local env file:
```bash
cp .env.example .env
```
2. Fernet Key setzen:
2. Generate an encryption key and set `ENCRYPTION_KEY` in `.env`:
```bash
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```
Wert in `.env` bei `ENCRYPTION_KEY` eintragen.
3. Stack starten:
3. Start services:
```bash
make up
```
4. URLs:
4. Open:
- Frontend: `http://localhost:5173`
- Backend API: `http://localhost:8000/api/v1`
- OpenAPI: `http://localhost:8000/docs`
- OpenAPI docs: `http://localhost:8000/docs`
Default initial admin (from `.env`):
Default Admin (aus `.env`):
- Email: `admin@example.com`
- Passwort: `ChangeMe123!`
- Password: `ChangeMe123!`
## Commands
## Common commands
```bash
make up
make down
make logs
make migrate
make up # build + start all services
make down # stop all services
make logs # follow logs
make migrate # run Alembic migrations in backend container
```
## API (Minimum)
## Environment variables reference
All variables are defined in `.env.example`.
### Application
- `APP_NAME`: Display name used by backend/docs
- `ENVIRONMENT`: `dev | staging | prod | test`
- `LOG_LEVEL`: `DEBUG | INFO | WARNING | ERROR`
### Core database (internal)
- `DB_NAME`: Internal metadata DB name
- `DB_USER`: Internal metadata DB user
- `DB_PASSWORD`: Internal metadata DB password
- `DB_PORT`: Host port mapped to internal PostgreSQL `5432`
### Backend API
- `BACKEND_PORT`: Host port mapped to backend container `8000`
- `JWT_SECRET_KEY`: JWT signing key (must be changed)
- `JWT_ALGORITHM`: JWT algorithm (default `HS256`)
- `JWT_ACCESS_TOKEN_MINUTES`: access token lifetime
- `JWT_REFRESH_TOKEN_MINUTES`: refresh token lifetime
- `ENCRYPTION_KEY`: Fernet key for encrypting target passwords at rest
- `CORS_ORIGINS`: comma-separated allowed origins or `*` (dev-only)
- `POLL_INTERVAL_SECONDS`: collector polling interval
- `INIT_ADMIN_EMAIL`: bootstrap admin email
- `INIT_ADMIN_PASSWORD`: bootstrap admin password
### Frontend
- `FRONTEND_PORT`: Host port mapped to frontend container `80`
- `VITE_API_URL`: API base URL baked into frontend build
- Proxy/SSL setup: use `/api/v1`
- Direct local setup: use `http://localhost:8000/api/v1`
## API overview (minimum)
- Auth:
- `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`
- Targets:
- `GET/POST /api/v1/targets`
- `GET/PUT/DELETE /api/v1/targets/{id}`
- `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/targets/{id}/overview`
- Admin users (admin-only):
- `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
## 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)
- No secrets are hardcoded in source
- Passwords are hashed with Argon2
- Target credentials are encrypted with Fernet
- CORS is environment-configurable
- Audit logs include auth, target, and user management events
- Rate limiting is currently a placeholder for future middleware integration
## Wichtiger Hinweis zu `pg_stat_statements`
## Important: `pg_stat_statements`
Auf jedem monitored Target muss `pg_stat_statements` aktiviert sein, sonst bleiben Query Insights leer.
Beispiel:
Query Insights requires `pg_stat_statements` on each monitored target.
```sql
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
```
## Reverse proxy and SSL
For production-like deployments behind HTTPS:
- Set frontend API to relative path: `VITE_API_URL=/api/v1`
- Route `/api/` from proxy to backend service
- Keep frontend and API on the same public origin to avoid CORS/mixed-content problems

6
frontend/src/pages/AdminUsersPage.jsx
View File

@@ -16,7 +16,7 @@ export function AdminUsersPage() {
if (me?.role === "admin") load().catch((e) => setError(String(e.message || e)));
}, [me]);
if (me?.role !== "admin") return <div className="card">Nur fuer Admin.</div>;
if (me?.role !== "admin") return <div className="card">Admins only.</div>;
const create = async (e) => {
e.preventDefault();
@@ -47,7 +47,7 @@ export function AdminUsersPage() {
<input
type="password"
value={form.password}
placeholder="passwort"
placeholder="password"
onChange={(e) => setForm({ ...form, password: e.target.value })}
/>
<select value={form.role} onChange={(e) => setForm({ ...form, role: e.target.value })}>
@@ -55,7 +55,7 @@ export function AdminUsersPage() {
<option value="operator">operator</option>
<option value="admin">admin</option>
</select>
<button>User anlegen</button>
<button>Create user</button>
</form>
<div className="card">
<table>

4
frontend/src/pages/DashboardPage.jsx
View File

@@ -26,7 +26,7 @@ export function DashboardPage() {
};
}, [tokens, refresh]);
if (loading) return <div className="card">Lade Dashboard...</div>;
if (loading) return <div className="card">Loading dashboard...</div>;
if (error) return <div className="card error">{error}</div>;
return (
@@ -54,7 +54,7 @@ export function DashboardPage() {
<th>Name</th>
<th>Host</th>
<th>DB</th>
<th>Aktion</th>
<th>Action</th>
</tr>
</thead>
<tbody>

10
frontend/src/pages/LoginPage.jsx
View File

@@ -18,7 +18,7 @@ export function LoginPage() {
await login(email, password);
navigate("/");
} catch {
setError("Login fehlgeschlagen");
setError("Login failed");
} finally {
setLoading(false);
}
@@ -28,12 +28,12 @@ export function LoginPage() {
<div className="login-wrap">
<form className="card login-card" onSubmit={submit}>
<div className="login-eyebrow">NexaPG Monitor</div>
<h2>Willkommen zurück</h2>
<p className="login-subtitle">Melde dich an, um Monitoring und Query Insights zu öffnen.</p>
<h2>Welcome back</h2>
<p className="login-subtitle">Sign in to access monitoring and query insights.</p>
<div className="input-shell">
<input
type="email"
placeholder="E-Mail"
placeholder="Email"
value={email}
onChange={(e) => setEmail(e.target.value)}
autoComplete="username"
@@ -49,7 +49,7 @@ export function LoginPage() {
/>
</div>
{error && <p className="error">{error}</p>}
<button className="login-cta" disabled={loading}>{loading ? "Bitte warten..." : "Einloggen"}</button>
<button className="login-cta" disabled={loading}>{loading ? "Please wait..." : "Sign in"}</button>
</form>
</div>
);

2
frontend/src/pages/QueryInsightsPage.jsx
View File

@@ -36,7 +36,7 @@ export function QueryInsightsPage() {
return (
<div>
<h2>Query Insights</h2>
<p>Hinweis: Benötigt aktivierte Extension <code>pg_stat_statements</code> auf dem Zielsystem.</p>
<p>Note: This section requires the <code>pg_stat_statements</code> extension on the monitored target.</p>
{error && <div className="card error">{error}</div>}
<div className="card">
<label>Target </label>

14
frontend/src/pages/TargetDetailPage.jsx
View File

@@ -135,7 +135,7 @@ export function TargetDetailPage() {
[series]
);
if (loading) return <div className="card">Lade Target Detail...</div>;
if (loading) return <div className="card">Loading target detail...</div>;
if (error) return <div className="card error">{error}</div>;
const role = overview?.instance?.role || "-";
@@ -157,7 +157,7 @@ export function TargetDetailPage() {
<span>Role</span>
<strong className={isPrimary ? "pill primary" : isStandby ? "pill standby" : "pill"}>{role}</strong>
</div>
<div title="Zeit seit Start des Postgres-Prozesses">
<div title="Time since PostgreSQL postmaster start">
<span>Uptime</span><strong>{formatSeconds(overview.instance.uptime_seconds)}</strong>
</div>
<div><span>Database</span><strong>{overview.instance.current_database || "-"}</strong></div>
@@ -165,16 +165,16 @@ export function TargetDetailPage() {
<span>Target Port</span>
<strong>{targetMeta?.port ?? "-"}</strong>
</div>
<div title="Groesse der aktuell verbundenen Datenbank">
<div title="Current database total size">
<span>Current DB Size</span><strong>{formatBytes(overview.storage.current_database_size_bytes)}</strong>
</div>
<div title="Gesamtgroesse der WAL-Dateien (falls verfuegbar)">
<div title="Total WAL directory size (when available)">
<span>WAL Size</span><strong>{formatBytes(overview.storage.wal_directory_size_bytes)}</strong>
</div>
<div title="Optional ueber Agent/SSH ermittelbar">
<div title="Optional metric via future Agent/SSH provider">
<span>Free Disk</span><strong>{formatBytes(overview.storage.disk_space.free_bytes)}</strong>
</div>
<div title="Zeitliche Replikationsverzoegerung auf Standby">
<div title="Replication replay delay on standby">
<span>Replay Lag</span>
<strong className={overview.replication.replay_lag_seconds > 5 ? "lag-bad" : ""}>
{formatSeconds(overview.replication.replay_lag_seconds)}
@@ -262,7 +262,7 @@ export function TargetDetailPage() {
))}
</div>
<div className="card" style={{ height: 320 }}>
<h3>Connections / TPS approx / Cache hit ratio</h3>
<h3>Connections / TPS (approx) / Cache Hit Ratio</h3>
<ResponsiveContainer width="100%" height="85%">
<LineChart data={chartData}>
<XAxis dataKey="ts" hide />

48
frontend/src/pages/TargetsPage.jsx
View File

@@ -51,7 +51,7 @@ export function TargetsPage() {
};
const deleteTarget = async (id) => {
if (!confirm("Target loeschen?")) return;
if (!confirm("Delete target?")) return;
try {
await apiFetch(`/targets/${id}`, { method: "DELETE" }, tokens, refresh);
await load();
@@ -69,42 +69,42 @@ export function TargetsPage() {
<details className="card collapsible" open>
<summary className="collapse-head">
<div>
<h3>Neues Target</h3>
<p>Verbindungsdaten fuer eine PostgreSQL-Instanz.</p>
<h3>New Target</h3>
<p>Connection settings for a PostgreSQL instance.</p>
</div>
<span className="collapse-chevron" aria-hidden="true">?</span>
<span className="collapse-chevron" aria-hidden="true">v</span>
</summary>
<form className="target-form grid two" onSubmit={createTarget}>
<div className="field">
<label>Name</label>
<input placeholder="z.B. Prod-DB" value={form.name} onChange={(e) => setForm({ ...form, name: e.target.value })} required />
<small>Eindeutiger Anzeigename im Dashboard.</small>
<input placeholder="e.g. Prod-DB" value={form.name} onChange={(e) => setForm({ ...form, name: e.target.value })} required />
<small>Unique display name in the dashboard.</small>
</div>
<div className="field">
<label>Host</label>
<input placeholder="z.B. 172.16.0.106 oder db.internal" value={form.host} onChange={(e) => setForm({ ...form, host: e.target.value })} required />
<small>Wichtig: Muss vom Backend-Container aus erreichbar sein.</small>
<input placeholder="e.g. 172.16.0.106 or db.internal" value={form.host} onChange={(e) => setForm({ ...form, host: e.target.value })} required />
<small>Must be reachable from the backend container.</small>
</div>
<div className="field">
<label>Port</label>
<input placeholder="5432" value={form.port} onChange={(e) => setForm({ ...form, port: Number(e.target.value) })} type="number" required />
<small>Standard PostgreSQL Port ist 5432 (oder gemappter Host-Port).</small>
<small>Default PostgreSQL port is 5432 (or your mapped host port).</small>
</div>
<div className="field">
<label>DB Name</label>
<input placeholder="z.B. postgres oder appdb" value={form.dbname} onChange={(e) => setForm({ ...form, dbname: e.target.value })} required />
<small>Name der Datenbank, die ueberwacht werden soll.</small>
<input placeholder="e.g. postgres or appdb" value={form.dbname} onChange={(e) => setForm({ ...form, dbname: e.target.value })} required />
<small>Database name to monitor.</small>
</div>
<div className="field">
<label>Username</label>
<input placeholder="z.B. postgres" value={form.username} onChange={(e) => setForm({ ...form, username: e.target.value })} required />
<small>DB User mit Leserechten auf Stats-Views.</small>
<input placeholder="e.g. postgres" value={form.username} onChange={(e) => setForm({ ...form, username: e.target.value })} required />
<small>DB user with read permissions on stats views.</small>
</div>
<div className="field">
<label>Password</label>
<input placeholder="Passwort" type="password" value={form.password} onChange={(e) => setForm({ ...form, password: e.target.value })} required />
<small>Wird verschluesselt in der Core-DB gespeichert.</small>
<input placeholder="Password" type="password" value={form.password} onChange={(e) => setForm({ ...form, password: e.target.value })} required />
<small>Stored encrypted in the core database.</small>
</div>
<div className="field">
<label>SSL Mode</label>
@@ -114,12 +114,12 @@ export function TargetsPage() {
<option value="require">require</option>
</select>
<small>
Bei Fehler "rejected SSL upgrade" auf <code>disable</code> stellen.
If you see "rejected SSL upgrade", switch to <code>disable</code>.
</small>
</div>
<div className="field">
<label>&nbsp;</label>
<button className="primary-btn">Target anlegen</button>
<button className="primary-btn">Create target</button>
</div>
</form>
</details>
@@ -130,25 +130,25 @@ export function TargetsPage() {
<summary className="collapse-head">
<div>
<h3>Troubleshooting</h3>
<p>Typische Verbindungsfehler schnell erkennen.</p>
<p>Quick checks for the most common connection issues.</p>
</div>
<span className="collapse-chevron" aria-hidden="true">?</span>
<span className="collapse-chevron" aria-hidden="true">v</span>
</summary>
<p>
<code>Connection refused</code>: Host/Port falsch oder DB nicht erreichbar.
<code>Connection refused</code>: host/port is wrong or database is unreachable.
</p>
<p>
<code>rejected SSL upgrade</code>: SSL Mode auf <code>disable</code> setzen.
<code>rejected SSL upgrade</code>: set SSL mode to <code>disable</code>.
</p>
<p>
<code>localhost</code> im Target zeigt aus Backend-Container-Sicht auf den Container selbst.
<code>localhost</code> points to the backend container itself, not your host machine.
</p>
</details>
)}
<div className="card targets-table">
{loading ? (
<p>Lade Targets...</p>
<p>Loading targets...</p>
) : (
<table>
<thead>
@@ -156,7 +156,7 @@ export function TargetsPage() {
<th>Name</th>
<th>Host</th>
<th>DB</th>
<th>Aktionen</th>
<th>Actions</th>
</tr>
</thead>
<tbody>

40
ops/.env.example
View File

@@ -1,27 +1,57 @@
# App
# ------------------------------
# Application
# ------------------------------
# Display name used in API docs/UI.
APP_NAME=NexaPG Monitor
# Runtime environment: dev | staging | prod | test
ENVIRONMENT=dev
# Backend log level: DEBUG | INFO | WARNING | ERROR
LOG_LEVEL=INFO
# Core DB
# ------------------------------
# Core Database (internal metadata DB)
# ------------------------------
# Database that stores users, targets, metrics, query stats, and audit logs.
DB_NAME=nexapg
DB_USER=nexapg
DB_PASSWORD=nexapg
# Host port mapped to the internal PostgreSQL container port 5432.
DB_PORT=5433
# Backend
# ------------------------------
# Backend API
# ------------------------------
# Host port mapped to backend container port 8000.
BACKEND_PORT=8000
# JWT signing secret. Change this in every non-local environment.
JWT_SECRET_KEY=change_this_super_secret
JWT_ALGORITHM=HS256
# Access token lifetime in minutes.
JWT_ACCESS_TOKEN_MINUTES=15
# Refresh token lifetime in minutes (10080 = 7 days).
JWT_REFRESH_TOKEN_MINUTES=10080
# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
# Key used to encrypt monitored target passwords at rest.
# Generate with:
# python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
ENCRYPTION_KEY=REPLACE_WITH_FERNET_KEY
# Allowed CORS origins for browser clients.
# Use comma-separated values, e.g.:
# CORS_ORIGINS=http://localhost:5173,https://nexapg.example.com
# Dev-only shortcut:
# CORS_ORIGINS=*
CORS_ORIGINS=http://localhost:5173,http://localhost:8080
# Target polling interval in seconds.
POLL_INTERVAL_SECONDS=30
# Initial admin bootstrap user (created on first startup if not present).
INIT_ADMIN_EMAIL=admin@example.com
INIT_ADMIN_PASSWORD=ChangeMe123!
# ------------------------------
# Frontend
# ------------------------------
# Host port mapped to frontend container port 80.
FRONTEND_PORT=5173
VITE_API_URL=http://localhost:8000/api/v1
# Base API URL used at frontend build time.
# For reverse proxy + SSL, keep this relative to avoid mixed-content issues.
# Example direct mode: VITE_API_URL=http://localhost:8000/api/v1
VITE_API_URL=/api/v1