Docs: concise README, split deployment guides, add change records
- README: short overview, quick start, config table and links. - DOCS/General: Deployment_Docker.md and Deployment_Native.md (system services, HTTPS, host hardening); refresh Index.md. - DOCS/Changes: security hardening, admin username change and egress via Hysteria2 with results and verification. - Drop mentions of the built-in admin/password account. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
iclaoudezinandClaude Sonnet 5.5 committed
1 parent
11c1b6379b
commit
9b2882d5f4
9 files changed
+294
-46
No files matched your search
@@ -105,6 +105,6 @@ server {
|
||||
|
||||
## 5. First Run & Initialization
|
||||
1. Access the UI via browser.
|
||||
2. Login with default credentials: `admin` / `password`.
|
||||
2. Sign in with the admin seeded via OVPMON_INITIAL_ADMIN_USER / OVPMON_INITIAL_ADMIN_PASSWORD (no built-in default user exists).
|
||||
3. **Immediately** change the password and set up 2FA in the Settings/Profile section.
|
||||
4. If using the Profiler, ensure the `easy-rsa` directory is present and initialized via the UI.
|
||||
@@ -0,0 +1,45 @@
|
||||
# Deployment: Docker
|
||||
|
||||
Uses `docker-compose.yml` from the repository root.
|
||||
|
||||
## Services
|
||||
|
||||
| Service | Container | Ports | Notes |
|
||||
|---|---|---|---|
|
||||
| `app-ui` | `ovp-ui` | 80 | Nginx + built UI; proxies `/api/` and `/profiles-api/` |
|
||||
| `app-api` | `ovp-api` | 5001 | Flask monitoring API |
|
||||
| `app-gatherer` | `ovp-gatherer` | - | Parses `openvpn-status.log` |
|
||||
| `app-profiler` | `ovp-profiler` | 8000, 1194/udp | FastAPI + OpenVPN; needs `NET_ADMIN` and `/dev/net/tun` |
|
||||
|
||||
Volumes: `ovp_logs`, `ovp_config`, `ovp_pki`, `ovp_client_config`, `db_data`.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Set a random JWT secret and the initial admin (compose reads them from the environment / `.env`):
|
||||
```bash
|
||||
cat > .env <<EOT
|
||||
JWT_SECRET=$(openssl rand -hex 32)
|
||||
OVPMON_INITIAL_ADMIN_USER=<login>
|
||||
OVPMON_INITIAL_ADMIN_PASSWORD=<strong password>
|
||||
EOT
|
||||
chmod 600 .env
|
||||
```
|
||||
Pass the two `OVPMON_INITIAL_ADMIN_*` variables to `app-api` (`environment:`) for the first start.
|
||||
2. `docker-compose up -d --build`
|
||||
3. Open `http://<host>`, sign in, **PKI Configuration → Initialize PKI**.
|
||||
4. Remove `OVPMON_INITIAL_ADMIN_*` from `.env` and recreate `app-api`.
|
||||
|
||||
## Hardening
|
||||
|
||||
- Publish only what is needed: in production drop the `5001:5001` and `8000:8000` mappings (Nginx already reaches them on `ovp-net`).
|
||||
- Terminate TLS in front of `app-ui` (reverse proxy or mount a cert into the UI container); see [Nginx configuration](Nginx_Configuration.md).
|
||||
- `ovp-profiler` is privileged (`NET_ADMIN`, TUN): restrict access to its port to the UI network.
|
||||
- Back up the `db_data` and `ovp_pki` volumes.
|
||||
|
||||
## Operations
|
||||
|
||||
```bash
|
||||
docker-compose ps
|
||||
docker-compose logs -f app-api app-profiler
|
||||
docker-compose up -d --build app-ui # after UI changes
|
||||
```
|
||||
@@ -0,0 +1,82 @@
|
||||
# Deployment: system services (no containers)
|
||||
|
||||
Tested on **Alpine 3.23 (OpenRC)**; Debian/Ubuntu (systemd) differs only in service manager. Unit/init templates: [`systemd/`](systemd), [`openrc/`](openrc/INSTALL.md). Generic notes: [Deployment](Deployment.md), [Service management](Service_Management.md), [Nginx](Nginx_Configuration.md).
|
||||
|
||||
## 1. Packages
|
||||
|
||||
- Alpine: `apk add python3 py3-pip nginx nodejs npm openvpn easy-rsa iptables bash`
|
||||
- Debian/Ubuntu: `apt install python3-venv nginx nodejs npm openvpn easy-rsa iptables`
|
||||
|
||||
## 2. Backend
|
||||
|
||||
```bash
|
||||
cd APP_CORE && python3 -m venv venv && venv/bin/pip install -r requirements.txt gunicorn
|
||||
cd APP_PROFILER && python3 -m venv venv && venv/bin/pip install -r requirements.txt
|
||||
mkdir -p APP_PROFILER/easy-rsa && cp -r /usr/share/easy-rsa/* APP_PROFILER/easy-rsa/ # Docker entrypoint does this automatically
|
||||
```
|
||||
|
||||
## 3. Environment file
|
||||
|
||||
`/etc/ovpmon/env` (chmod 600), loaded by the services:
|
||||
|
||||
```
|
||||
OVPMON_API_SECRET_KEY=<openssl rand -hex 32>
|
||||
OVPMON_API_HOST=127.0.0.1
|
||||
OVPMON_API_PORT=5001
|
||||
OVPMON_OPENVPN_MONITOR_DB_PATH=/var/lib/ovpmon/openvpn_monitor.db
|
||||
OVPMON_OPENVPN_MONITOR_LOG_PATH=/var/log/openvpn/openvpn-status.log
|
||||
OVPMON_PROFILER_DB_PATH=/var/lib/ovpmon/ovpn_profiler.db
|
||||
OVPMON_LOGGING_LEVEL=INFO
|
||||
```
|
||||
|
||||
Create `/var/lib/ovpmon`, `/var/log/ovpmon`, `/var/log/openvpn`. For the first start also set `OVPMON_INITIAL_ADMIN_USER` / `OVPMON_INITIAL_ADMIN_PASSWORD`, then remove them.
|
||||
|
||||
## 4. Services
|
||||
|
||||
| Service | Command | Listens |
|
||||
|---|---|---|
|
||||
| `ovpmon-api` | `APP_CORE/venv/bin/gunicorn -w 2 -b 127.0.0.1:5001 openvpn_api_v3:app` (cwd `APP_CORE`) | 127.0.0.1:5001 |
|
||||
| `ovpmon-gatherer` | `APP_CORE/venv/bin/python openvpn_gatherer_v3.py` (cwd `APP_CORE`) | - |
|
||||
| `ovpmon-profiler` | `APP_PROFILER/venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000` (cwd `APP_PROFILER`) | 127.0.0.1:8000 |
|
||||
|
||||
OpenRC (Alpine): `supervisor=supervise-daemon`, `respawn_delay=3`, source `/etc/ovpmon/env` in `start_pre`, then `rc-update add <svc> default && rc-service <svc> start`. systemd: use the units from `systemd/` with `EnvironmentFile=/etc/ovpmon/env`.
|
||||
|
||||
The Profiler restarts OpenVPN through `rc-service openvpn` (Alpine) or `systemctl openvpn`; on Alpine link the config: `ln -s server.conf /etc/openvpn/openvpn.conf` and enable the `openvpn` service.
|
||||
|
||||
## 5. UI and Nginx (HTTPS on 8088)
|
||||
|
||||
```bash
|
||||
cd APP_UI && npm install && npm run build
|
||||
mkdir -p /var/www/ovpmon && cp -r dist/. /var/www/ovpmon/
|
||||
```
|
||||
|
||||
Certificate (self-signed, replace with a real one when a domain is available):
|
||||
|
||||
```bash
|
||||
mkdir -p /etc/ovpmon/tls && cd /etc/ovpmon/tls
|
||||
openssl req -x509 -nodes -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -days 825 \
|
||||
-subj "/CN=ovpmon" -addext "subjectAltName=IP:<HOST-IP>,DNS:ovpmon" -keyout ovpmon.key -out ovpmon.crt
|
||||
chmod 600 ovpmon.key
|
||||
```
|
||||
|
||||
Nginx server (`/etc/nginx/http.d/ovpmon.conf` on Alpine): `listen 8088 ssl`, TLS 1.2/1.3, `error_page 497 =301 https://$host:8088$request_uri`, security headers, `limit_req` (5 r/min) on `/api/auth/login`, `/` → static UI, `/api/` → `127.0.0.1:5001`, `/profiles-api/` → `127.0.0.1:8000/api/`. Full listing: [Nginx configuration](Nginx_Configuration.md). Do not declare a second `ssl_session_cache shared:SSL` zone with a different size than the main `nginx.conf`.
|
||||
|
||||
## 6. First run
|
||||
|
||||
1. `https://<host>:8088/` → sign in with the seeded admin → **Account**: change username/password, enable 2FA.
|
||||
2. **PKI Configuration → Initialize PKI** → generate server config → start OpenVPN → create profiles.
|
||||
|
||||
## 7. Host hardening (recommended)
|
||||
|
||||
- SSH: key-only (`PasswordAuthentication no`, `KbdInteractiveAuthentication no`, `PermitRootLogin prohibit-password`); note that cloud-init drop-ins in `/etc/ssh/sshd_config.d/` can override the main file, so put settings in `00-*.conf`.
|
||||
- fail2ban: jails `sshd` and one for `POST /api/auth/login` (401/429/503) on the Nginx access log.
|
||||
- Backends bound to `127.0.0.1`; only 8088 (UI/API) and the VPN port are public.
|
||||
|
||||
## 8. Verify
|
||||
|
||||
```bash
|
||||
rc-status | grep -E "ovpmon|nginx|openvpn" # or: systemctl status ovpmon-*
|
||||
ss -tlnp | grep -E ":(8088|5001|8000) "
|
||||
curl -sk -o /dev/null -w "%{http_code}\n" https://127.0.0.1:8088/ # 200
|
||||
curl -sk -o /dev/null -w "%{http_code}\n" https://127.0.0.1:8088/profiles-api/config # 401 without token
|
||||
```
|
||||
@@ -3,10 +3,18 @@
|
||||
Welcome to the documentation for the OpenVPN Monitor suite.
|
||||
|
||||
## 📚 General
|
||||
- [Deployment Guide](Deployment.md): How to install and configure the application on a Linux server.
|
||||
- [Deployment: Docker](Deployment_Docker.md): containers with docker-compose.
|
||||
- [Deployment: system services](Deployment_Native.md): systemd/OpenRC, HTTPS, host hardening.
|
||||
- [Deployment Guide](Deployment.md): generic native install notes.
|
||||
- [Service Management](Service_Management.md): Setting up systemd/OpenRC services.
|
||||
- [Nginx Configuration](Nginx_Configuration.md)
|
||||
- [Security Architecture](Security_Architecture.md): Details on Authentication, 2FA, and Security features.
|
||||
|
||||
## 🛠 Changes and results
|
||||
- [Security hardening (2026-09-30)](../Changes/2026-09-30_Security_Hardening.md)
|
||||
- [Admin username change (2026-09-30)](../Changes/2026-09-30_Admin_Username_Change.md)
|
||||
- [Egress via Hysteria2 (2026-09-30)](../Changes/2026-09-30_Egress_via_Hysteria2.md)
|
||||
|
||||
## 🔍 Core Monitoring (`APP_CORE`)
|
||||
The core module responsible for log parsing, real-time statistics, and the primary API.
|
||||
- [API Reference](../Core_Monitoring/API_Reference.md): Endpoints for monitoring data.
|
||||
|
||||
@@ -10,7 +10,7 @@ This includes:
|
||||
|
||||
## User Review Required
|
||||
> [!IMPORTANT]
|
||||
> **Default Credentials**: We will create a default admin user (e.g., `admin` / `password`) on first run if no users exist. The user MUST change this immediately.
|
||||
> **Initial admin**: no default user is created. On first run with an empty users table the admin is seeded only from OVPMON_INITIAL_ADMIN_USER / OVPMON_INITIAL_ADMIN_PASSWORD; the username can be changed in Account (see DOCS/Changes/2026-09-30_Admin_Username_Change.md).
|
||||
|
||||
> [!WARNING]
|
||||
> **Breaking Change**: Access to the current dashboard will be blocked until the user logs in.
|
||||
|
||||
Reference in new issue
Block a user