OpenVPN-Monitoring-Simple/README.md

# 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. Perfect for both containerized (Docker) and native (Alpine/Debian/Ubuntu) deployments.

## 🏗️ Project Architecture

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 + 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)

The recommended way to deploy is using Docker Compose:

1.  **Clone the repository**
2.  **Start all services**:
    ```bash
    docker-compose up -d --build
    ```
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 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` | 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` |

## 🛠️ Performance & Environment Awareness

- **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`).

## 📚 Development

### 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

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.