From f6a81b3d7c9f5c1698f3303d862db88d7a944d91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D0=BD=D1=82=D0=BE=D0=BD?= Date: Sat, 7 Feb 2026 15:23:23 +0300 Subject: [PATCH] update main README.md --- README.md | 68 ++++++++++++++++++++----------------------------------- 1 file changed, 25 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 7bdc230..effdce4 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,17 @@ # OpenVPN Monitor & Profiler -A modern, full-stack management solution for OpenVPN servers. It combines real-time traffic monitoring, historical analytics, and comprehensive user profile/PKI management into a unified web interface. +A modern, full-stack management solution for OpenVPN servers. It combines real-time traffic monitoring, historical analytics, and comprehensive user profile/PKI management into a unified web interface. Perfect for both containerized (Docker) and native (Alpine/Debian/Ubuntu) deployments. ## 🏗️ Project Architecture -The project is modularized into four core microservices: +The project is modularized into four core microservices, split between **Monitoring (Core)** and **Management (Profiler)**: | Component | Directory | Service Name | Description | | :--- | :--- | :--- | :--- | -| **User Interface** | `APP_UI/` | `ovp-ui` | Vue 3 + Vite SPA served via Nginx. | -| **Monitoring API** | `APP_CORE/` | `ovp-api` | Flask API for real-time stats and sessions. | -| **Data Gatherer** | `APP_CORE/` | `ovp-gatherer` | Background service for traffic log aggregation & TSDB. | -| **Profiler** | `APP_PROFILER/` | `ovp-profiler` | FastAPI module for PKI, Certificates, and VPN control. | +| **User Interface** | `APP_UI/` | `ovp-ui` | Vue 3 + Vite SPA + Nginx. Communicates with both APIs. | +| **Monitoring API** | `APP_CORE/` | `ovp-api` | Flask API for real-time stats, sessions, and bandwidth data. | +| **Data Gatherer** | `APP_CORE/` | `ovp-gatherer` | Background service for traffic log aggregation & TSDB logic. | +| **Profiler API** | `APP_PROFILER/` | `ovp-profiler` | FastAPI module for PKI management, User Profiles, and VPN control. | ## 📦 Quick Start (Docker) @@ -22,58 +22,40 @@ The recommended way to deploy is using Docker Compose: ```bash docker-compose up -d --build ``` -3. **Access the Dashboard**: Open `http://localhost` in your browser. +3. **Access the Dashboard**: Open `http://localhost` (or your server IP) in your browser. +4. **Initialize PKI**: On the first run, navigate to the **PKI Configuration** page in the UI and click **Initialize PKI**. This sets up the CA and Easy-RSA workspace. ## ⚙️ Configuration -The system is highly configurable via environment variables in `docker-compose.yml`. All variables follow the `OVPMON_{SECTION}_{KEY}` format. +The system uses a unified configuration approach. Settings can be defined in `config.ini` files or overridden by environment variables following the `OVPMON_{SECTION}_{KEY}` format. ### Key Environment Variables | Variable | Description | Default Value | | :--- | :--- | :--- | -| `OVPMON_API_SECRET_KEY` | JWT Secret Key | `ovpmon-secret-change-me` | -| `OVPMON_API_PORT` | Monitoring API Port | `5001` | -| `OVPMON_OPENVPN_MONITOR_DB_PATH` | Path to SQLite DB | `/app/db/openvpn_monitor.db` | +| `OVPMON_API_SECRET_KEY` | Unified JWT Secret Key (used by both APIs) | `supersecret` | +| `OVPMON_PROFILER_DB_PATH` | Path to Profiler (users/pki) SQLite DB | `/app/db/ovpn_profiler.db` | +| `OVPMON_OPENVPN_MONITOR_DB_PATH` | Path to Monitoring (traffic) SQLite DB | `/app/db/openvpn_monitor.db` | | `OVPMON_OPENVPN_MONITOR_LOG_PATH`| Path to OpenVPN status log | `/var/log/openvpn/openvpn-status.log` | | `OVPMON_LOGGING_LEVEL` | Logging level (INFO/DEBUG) | `INFO` | -## 📚 Documentation +## 🛠️ Performance & Environment Awareness -Detailed documentation is available in the `DOCS/` directory: +- **Container Transparency**: When running in Docker, the Profiler manages OpenVPN directly to bypass cgroups restrictions. +- **Host Integration**: When running natively on Alpine or Debian/Ubuntu, it automatically switches to `rc-service` or `systemctl`. +- **Persistent Data**: Logs, Certificates (PKI), and Databases are stored in Docker volumes (`ovp_logs`, `ovp_pki`, `db_data`). -- **[Deployment Guide](DOCS/General/Deployment.md)**: Manual setup for Linux. -- **[Security Architecture](DOCS/General/Security_Architecture.md)**: 2FA, JWT, and Security. -- **[API Reference](DOCS/Core_Monitoring/API_Reference.md)**: Core Monitoring endpoints. +## 📚 Development -## 🛠️ Development (Manual) - -If you wish to run services manually for development: - -### 1. Core API & Gatherer -```bash -cd APP_CORE -pip install -r requirements.txt -python3 openvpn_api_v3.py # APP_CORE API (:5001) -python3 openvpn_gatherer_v3.py # APP_CORE Gatherer -``` - -### 2. Profiler API -```bash -cd APP_PROFILER -pip install -r requirements.txt -python3 main.py # APP_PROFILER API (:8000) -``` - -### 3. Frontend -```bash -cd APP_UI -npm install && npm run dev # UI (:5173) -``` +### Component Development +- **UI**: Uses `composables/useApi.js` to route requests to the appropriate backend service based on URL. +- **Profiler**: Clean Python/FastAPI code with SQLAlchemy models. Supports "staging" local mode for development without root access. +- **Core**: Lightweight Flask services focused on high-performance log parsing. --- -## ⚠️ Important Notes +### ⚠️ Important Notes -1. **Permissions**: The Profiler container requires `NET_ADMIN` capabilities and access to `/dev/net/tun`. -2. **Cleanup**: Certificate management and legacy visualization settings have been moved or removed from the Core module. +1. **Privileged Mode**: The `ovp-profiler` container requires `NET_ADMIN` capabilities for iptables and TUN management. +2. **Network Setup**: Ensure `net.ipv4.ip_forward=1` is enabled (handled automatically in the docker-compose `sysctls` section). +3. **JWT Safety**: Always change the `OVPMON_API_SECRET_KEY` in production.