From 923d4a618856bb3dad3aede7252ac6ee23e725af Mon Sep 17 00:00:00 2001 From: Christoph Haas Date: Sat, 3 May 2025 22:21:56 +0200 Subject: [PATCH] docs: add reverse-proxy example, improve docker examples, fix slow_query_threshold documentation; feat: allow config.yml and config.yaml as configuration files --- .gitignore | 1 + docker-compose.yml | 1 + docs/documentation/configuration/overview.md | 8 +- docs/documentation/getting-started/docker.md | 6 +- .../getting-started/reverse-proxy.md | 98 +++++++++++++++++++ docs/documentation/upgrade/v1.md | 4 +- internal/config/config.go | 9 +- internal/config/database.go | 2 +- mkdocs.yml | 1 + 9 files changed, 121 insertions(+), 9 deletions(-) create mode 100644 docs/documentation/getting-started/reverse-proxy.md diff --git a/.gitignore b/.gitignore index c4ec70b..b64665a 100644 --- a/.gitignore +++ b/.gitignore @@ -33,6 +33,7 @@ ssh.key wg_portal.db sqlite.db /config.yml +/config.yaml /config/ venv/ .cache/ diff --git a/docker-compose.yml b/docker-compose.yml index a114187..03a59a1 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -12,6 +12,7 @@ services: - NET_ADMIN network_mode: "host" volumes: + # left side is the host path, right side is the container path - /etc/wireguard:/etc/wireguard - ./data:/app/data - ./config:/app/config diff --git a/docs/documentation/configuration/overview.md b/docs/documentation/configuration/overview.md index ca75637..ab099dd 100644 --- a/docs/documentation/configuration/overview.md +++ b/docs/documentation/configuration/overview.md @@ -1,7 +1,7 @@ This page provides an overview of **all available configuration options** for WireGuard Portal. You can supply these configurations in a **YAML** file (e.g. `config.yaml`) when starting the Portal. -The path of the configuration file defaults to **config/config.yml** in the working directory of the executable. +The path of the configuration file defaults to **config/config.yaml** (or config/config.yml) in the working directory of the executable. It is possible to override configuration filepath using the environment variable `WG_PORTAL_CONFIG`. For example: `WG_PORTAL_CONFIG=/etc/wg-portal/config.yaml ./wg-portal`. Also, environment variable substitution in config file is supported. Refer to [syntax](https://github.com/a8m/envsubst?tab=readme-ov-file#docs). @@ -39,7 +39,7 @@ advanced: database: debug: false - slow_query_threshold: 0 + slow_query_threshold: "0" type: sqlite dsn: data/sqlite.db @@ -221,8 +221,8 @@ If sensitive values (like private keys) should be stored in an encrypted format, - **Description:** If `true`, logs all database statements (verbose). ### `slow_query_threshold` -- **Default:** 0 -- **Description:** A time threshold (e.g., `100ms`) above which queries are considered slow and logged as warnings. If empty or zero, slow query logging is disabled. Format uses `s`, `ms` for seconds, milliseconds, see [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration). +- **Default:** "0" +- **Description:** A time threshold (e.g., `100ms`) above which queries are considered slow and logged as warnings. If zero, slow query logging is disabled. Format uses `s`, `ms` for seconds, milliseconds, see [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration). The value must be a string. ### `type` - **Default:** `sqlite` diff --git a/docs/documentation/getting-started/docker.md b/docs/documentation/getting-started/docker.md index 307183a..ab606b1 100644 --- a/docs/documentation/getting-started/docker.md +++ b/docs/documentation/getting-started/docker.md @@ -45,6 +45,7 @@ WireGuard Portal supports managing WireGuard interfaces through three distinct d cap_add: - NET_ADMIN ports: + # host port : container port # WireGuard port, needs to match the port in wg-portal interface config (add one port mapping for each interface) - "51820:51820/udp" # Web UI port @@ -52,6 +53,7 @@ WireGuard Portal supports managing WireGuard interfaces through three distinct d sysctls: - net.ipv4.conf.all.src_valid_mark=1 volumes: + # host path : container path - ./wg/data:/app/data - ./wg/config:/app/config ``` @@ -70,6 +72,7 @@ WireGuard Portal supports managing WireGuard interfaces through three distinct d - NET_ADMIN network_mode: "service:wireguard" # So we ensure to stay on the same network as the wireguard container. volumes: + # host path : container path - ./wg/etc:/etc/wireguard - ./wg/data:/app/data - ./wg/config:/app/config @@ -81,6 +84,7 @@ WireGuard Portal supports managing WireGuard interfaces through three distinct d cap_add: - NET_ADMIN ports: + # host port : container port - "51820:51820/udp" # WireGuard port, needs to match the port in wg-portal interface config - "8888:8888/tcp" # Noticed that the port of the web UI is exposed in the wireguard container. volumes: @@ -133,7 +137,7 @@ For each commit in the master and the stable branch, a corresponding Docker imag ## Configuration You can configure WireGuard Portal using a YAML configuration file. -The filepath of the YAML configuration file defaults to `/app/config/config.yml`. +The filepath of the YAML configuration file defaults to `/app/config/config.yaml`. It is possible to override the configuration filepath using the environment variable **WG_PORTAL_CONFIG**. By default, WireGuard Portal uses an SQLite database. The database is stored in `/app/data/sqlite.db`. diff --git a/docs/documentation/getting-started/reverse-proxy.md b/docs/documentation/getting-started/reverse-proxy.md new file mode 100644 index 0000000..10b689d --- /dev/null +++ b/docs/documentation/getting-started/reverse-proxy.md @@ -0,0 +1,98 @@ +## Reverse Proxy for HTTPS + +For production deployments, always serve the WireGuard Portal over HTTPS. You have two options to secure your connection: + + +### Reverse Proxy + +Let a front‐end proxy handle HTTPS for you. This also frees you from managing certificates manually and is therefore the preferred option. +You can use Nginx, Traefik, Caddy or any other proxy. + +Below is an example using a Docker Compose stack with [Traefik](https://traefik.io/traefik/). +It exposes the WireGuard Portal on `https://wg.domain.com` and redirects initial HTTP traffic to HTTPS. + +```yaml +services: + reverse-proxy: + image: traefik:v3.3 + restart: unless-stopped + command: + #- '--log.level=DEBUG' + - '--providers.docker.endpoint=unix:///var/run/docker.sock' + - '--providers.docker.exposedbydefault=false' + - '--entrypoints.web.address=:80' + - '--entrypoints.websecure.address=:443' + - '--entrypoints.websecure.http3' + - '--certificatesresolvers.letsencryptresolver.acme.httpchallenge=true' + - '--certificatesresolvers.letsencryptresolver.acme.httpchallenge.entrypoint=web' + - '--certificatesresolvers.letsencryptresolver.acme.email=your.email@domain.com' + - '--certificatesresolvers.letsencryptresolver.acme.storage=/letsencrypt/acme.json' + #- '--certificatesresolvers.letsencryptresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory' # just for testing + ports: + - 80:80 # for HTTP + - 443:443/tcp # for HTTPS + - 443:443/udp # for HTTP/3 + volumes: + - acme-certs:/letsencrypt + - /var/run/docker.sock:/var/run/docker.sock:ro + labels: + - 'traefik.enable=true' + # HTTP Catchall for redirecting HTTP -> HTTPS + - 'traefik.http.routers.dashboard-catchall.rule=Host(`wg.domain.com`) && PathPrefix(`/`)' + - 'traefik.http.routers.dashboard-catchall.entrypoints=web' + - 'traefik.http.routers.dashboard-catchall.middlewares=redirect-to-https' + - 'traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https' + + wg-portal: + image: wgportal/wg-portal:latest + container_name: wg-portal + restart: unless-stopped + logging: + options: + max-size: "10m" + max-file: "3" + cap_add: + - NET_ADMIN + ports: + # host port : container port + # WireGuard port, needs to match the port in wg-portal interface config (add one port mapping for each interface) + - "51820:51820/udp" + # Web UI port (only available on localhost, Traefik will handle the HTTPS) + - "127.0.0.1:8888:8888/tcp" + sysctls: + - net.ipv4.conf.all.src_valid_mark=1 + volumes: + # host path : container path + - ./wg/data:/app/data + - ./wg/config:/app/config + labels: + - 'traefik.enable=true' + - 'traefik.http.routers.wgportal.rule=Host(`wg.domain.com`)' + - 'traefik.http.routers.wgportal.entrypoints=websecure' + - 'traefik.http.routers.wgportal.tls.certresolver=letsencryptresolver' + - 'traefik.http.routers.wgportal.service=wgportal' + - 'traefik.http.services.wgportal.loadbalancer.server.port=8888' + +volumes: + acme-certs: +``` + +The WireGuard Portal configuration must be updated accordingly so that the correct external URL is set for the web interface: + +```yaml +web: + external_url: https://wg.domain.com +``` + +### Built-in TLS + +If you prefer to let WireGuard Portal handle TLS itself, you can use the built-in TLS support. +In your `config.yaml`, under the `web` section, point to your certificate and key files: + +```yaml +web: + cert_file: /path/to/your/fullchain.pem + key_file: /path/to/your/privkey.pem +``` + +The web server will then use these files to serve HTTPS traffic directly instead of HTTP. \ No newline at end of file diff --git a/docs/documentation/upgrade/v1.md b/docs/documentation/upgrade/v1.md index 3046d29..4fd2c8a 100644 --- a/docs/documentation/upgrade/v1.md +++ b/docs/documentation/upgrade/v1.md @@ -6,7 +6,7 @@ If you want to use version 2, please be aware that it is still a release candida > :warning: Before upgrading from V1, make sure that you have a backup of your currently working configuration files and database! To start the upgrade process, start the wg-portal binary with the **-migrateFrom** parameter. -The configuration (config.yml) for WireGuard Portal must be updated and valid before starting the upgrade. +The configuration (config.yaml) for WireGuard Portal must be updated and valid before starting the upgrade. To upgrade from a previous SQLite database, start wg-portal like: @@ -21,7 +21,7 @@ For example: ./wg-portal-amd64 -migrateFromType=mysql -migrateFrom='user:pass@tcp(1.2.3.4:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local' ``` -The upgrade will transform the old, existing database and store the values in the new database specified in the **config.yml** configuration file. +The upgrade will transform the old, existing database and store the values in the new database specified in the **config.yaml** configuration file. Ensure that the new database does not contain any data! If you are using Docker, you can adapt the docker-compose.yml file to start the upgrade process: diff --git a/internal/config/config.go b/internal/config/config.go index f4694c1..dedebac 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -174,9 +174,16 @@ func GetConfig() (*Config, error) { // override config values from YAML file - cfgFileName := "config/config.yml" + cfgFileName := "config/config.yaml" + cfgFileNameFallback := "config/config.yml" if envCfgFileName := os.Getenv("WG_PORTAL_CONFIG"); envCfgFileName != "" { cfgFileName = envCfgFileName + cfgFileNameFallback = envCfgFileName + } + + // check if the config file exists, otherwise use the fallback file name + if _, err := os.Stat(cfgFileName); os.IsNotExist(err) { + cfgFileName = cfgFileNameFallback } if err := loadConfigFile(cfg, cfgFileName); err != nil { diff --git a/internal/config/database.go b/internal/config/database.go index 06554a7..2874084 100644 --- a/internal/config/database.go +++ b/internal/config/database.go @@ -18,7 +18,7 @@ type DatabaseConfig struct { // Debug enables logging of all database statements Debug bool `yaml:"debug"` // SlowQueryThreshold enables logging of slow queries which take longer than the specified duration - SlowQueryThreshold time.Duration `yaml:"slow_query_threshold"` // 0 means no logging of slow queries + SlowQueryThreshold time.Duration `yaml:"slow_query_threshold"` // "0" means no logging of slow queries // Type is the database type. Supported: mysql, mssql, postgres, sqlite Type SupportedDatabase `yaml:"type"` // DSN is the database connection string. diff --git a/mkdocs.yml b/mkdocs.yml index c6e418e..5b285fd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -65,6 +65,7 @@ nav: - Docker: documentation/getting-started/docker.md - Helm: documentation/getting-started/helm.md - Sources: documentation/getting-started/sources.md + - Reverse Proxy (HTTPS): documentation/getting-started/reverse-proxy.md - Configuration: - Overview: documentation/configuration/overview.md - Examples: documentation/configuration/examples.md