OpenVPN-Monitoring-Simple/README.md

# OpenVPN Monitor & Profiler

Web suite for OpenVPN servers: real-time traffic monitoring, history/analytics, PKI and client-profile management, one UI.

| Component | Dir | Stack | Default port |
|---|---|---|---|
| UI | `APP_UI/` | Vue 3 + Vite, served by Nginx | 80 (Docker) / 8088 (native, TLS) |
| Monitoring API | `APP_CORE/` | Flask (gunicorn) | 5001 (internal) |
| Data gatherer | `APP_CORE/` | Python daemon | - |
| Profiler API | `APP_PROFILER/` | FastAPI (uvicorn) | 8000 (internal) |

Nginx is the only public entry point: `/` UI, `/api/` Monitoring API, `/profiles-api/` Profiler API.

## Quick start

- **Containers:** `docker-compose up -d --build`, open `http://<host>`. Details: [Deployment: Docker](DOCS/General/Deployment_Docker.md).
- **System services** (systemd / OpenRC, no containers): [Deployment: native](DOCS/General/Deployment_Native.md).

After the first start: sign in, open **PKI Configuration** → **Initialize PKI**, generate the server config, start OpenVPN, create profiles.

## First login and credentials

No default user is created. Seed the initial admin with `OVPMON_INITIAL_ADMIN_USER` / `OVPMON_INITIAL_ADMIN_PASSWORD` on first start (empty `users` table only), then remove them. Change the username and password and enable 2FA in **Account**.

## Configuration

`config.ini` per component; overridden by `OVPMON_{SECTION}_{KEY}` environment variables.

| Variable | Purpose |
|---|---|
| `OVPMON_API_SECRET_KEY` | JWT secret shared by both APIs (**must be random**) |
| `OVPMON_INITIAL_ADMIN_USER` / `_PASSWORD` | One-time admin seed |
| `OVPMON_CORS_ORIGINS` | Extra allowed CORS origins, comma-separated (empty = same-origin only) |
| `OVPMON_OPENVPN_MONITOR_DB_PATH` | Monitoring DB |
| `OVPMON_PROFILER_DB_PATH` | Profiler DB |
| `OVPMON_OPENVPN_MONITOR_LOG_PATH` | `openvpn-status.log` path |
| `OVPMON_LOGGING_LEVEL` | `INFO` / `DEBUG` |

## Documentation

- Index: [DOCS/General/Index.md](DOCS/General/Index.md)
- Deployment: [Docker](DOCS/General/Deployment_Docker.md) · [System services](DOCS/General/Deployment_Native.md) · [Nginx](DOCS/General/Nginx_Configuration.md) · [Service management](DOCS/General/Service_Management.md)
- Security model: [Security Architecture](DOCS/General/Security_Architecture.md)
- APIs: [Monitoring](DOCS/Core_Monitoring/API_Reference.md) · [Profiler](DOCS/Profiler_Management/API_Reference.md)

## Changes and results

| Date | Change | Document |
|---|---|---|
| 2026-09-30 | Security hardening: path traversal, 2FA token bypass, CORS, log leak, HTTPS, SSH, fail2ban | [Security hardening](DOCS/Changes/2026-09-30_Security_Hardening.md) |
| 2026-09-30 | Admin username change (API + UI), no built-in default admin | [Admin username change](DOCS/Changes/2026-09-30_Admin_Username_Change.md) |
| 2026-09-30 | Route OpenVPN clients through a Hysteria2 tunnel to an exit node | [Egress via Hysteria2](DOCS/Changes/2026-09-30_Egress_via_Hysteria2.md) |

## Notes

- `ovpmon-api` and `ovpmon-profiler` currently run as root (they manage OpenVPN and PKI).
- Keep `easy-rsa/`, `client-config/`, databases and `*.env` out of git: they contain private keys and secrets.