thakares/nx9-wg
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Finalize nx9-wg production release

Browse Source
This commit is contained in:
thakares committed 2026-08-18 22:27:36 +05:30
1 parent 4dfe42fe68
commit d704c1e131
30 files changed
+2502 -370
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/configuration.md
+43 -1
View File
@@ -59,8 +59,50 @@ Every environment variable recognized by `nx9-wg` uses the mandatory `NX9_WG_` n
---
## Persistent WireGuard Server Endpoint Configuration
When generating client `.conf` configurations and QR codes, `nx9-wg` embeds the public or reachable server endpoint address so client devices can reach the server. This is managed through persistent settings in SQLite.
### Settings Keys
| Key | Type | Description | Default | Example |
| :--- | :--- | :--- | :--- | :--- |
| `wireguard.server_host` | String | Public/reachable server hostname or IP address (DNS hostname, IPv4, or IPv6). Must not contain a port. | Empty | `vpn.thakares.com` or `203.0.113.10` or `2001:db8::10` |
| `wireguard.server_port` | u16 | Public reachable UDP port where clients connect. | `51820` | `51820` |
| `wireguard.server_endpoint_enabled` | Boolean | Whether the persistent server endpoint is used as the default for client exports. | `true` | `true` |
| `server_endpoint` | String | Legacy formatted endpoint fallback (`host:port` or `[ipv6]:port`). | Empty | `vpn.thakares.com:51820` |
| `public_endpoint` | String | Legacy secondary fallback. | Empty | `vpn.thakares.com:51820` |
### Important Architectural Invariants
- **Public Endpoint vs. Interface Listen Port**: The public server endpoint (`wireguard.server_host` and `wireguard.server_port`) is the external address that clients use to connect across the Internet or WAN. It is conceptually separate from the WireGuard interface's local kernel UDP `listen_port` (which may sit behind NAT, port-forwarding, or a reverse proxy).
- **Authoritative Resolution Precedence**:
1. **Explicit per-request / per-export override**: Passed via `--endpoint <ENDPOINT>` in the CLI or `?endpoint=<ENDPOINT>` in the REST API.
2. **Persistent structured settings**: `wireguard.server_host` + `wireguard.server_port` when `wireguard.server_endpoint_enabled` is `true` and host is non-empty.
3. **Legacy `server_endpoint` setting**: If present and non-empty.
4. **Legacy `public_endpoint` setting**: If present and non-empty.
5. **Actionable configuration error**: If no endpoint is configured, generation fails with an actionable error directing the administrator to configure the server endpoint in Settings or provide an explicit override.
### Configuring via CLI
```bash
# Configure the persistent server endpoint:
nx9-wg system settings set wireguard.server_host vpn.thakares.com
nx9-wg system settings set wireguard.server_port 51820
nx9-wg system settings set wireguard.server_endpoint_enabled true
# Export a client configuration using the persistent default:
nx9-wg peer config <PEER_UUID>
# Generated output contains: Endpoint = vpn.thakares.com:51820
# Export with a temporary one-off override (does not modify persistent settings):
nx9-wg peer config <PEER_UUID> --endpoint custom.backup-vpn.com:51820
# Generated output contains: Endpoint = custom.backup-vpn.com:51820
```
---
## Secret Handling & Docker Secrets
- **Never Persisted in Cleartext**: `NX9_WG_ADMIN_PASSWORD` is hashed into SQLite using Argon2id during initialization and is never written to disk, config files, or logs.
- **Docker Secrets**: In container environments, mount Docker secrets to `/run/secrets/nx9_wg_admin_password` and specify `NX9_WG_ADMIN_PASSWORD_FILE=/run/secrets/nx9_wg_admin_password`.