Examples
Below are some sample YAML configurations demonstrating how to override some default values.
Basic
core:
+ Examples - WireGuard Portal Examples
Below are some sample YAML configurations demonstrating how to override some default values.
Basic
core:
admin_user: test@example.com
admin_password: password
admin_api_token: super-s3cr3t-api-token-or-a-UUID
diff --git a/master/documentation/configuration/overview/index.html b/master/documentation/configuration/overview/index.html
index 16fb3a1..230433a 100644
--- a/master/documentation/configuration/overview/index.html
+++ b/master/documentation/configuration/overview/index.html
@@ -1,5 +1,5 @@
- Overview - WireGuard Portal Overview
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.
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.
Configuration examples are available on the Examples page.
Default configuration
core:
+ Overview - WireGuard Portal Overview
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.
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.
Configuration examples are available on the Examples page.
Default configuration
core:
admin_user: admin@wgportal.local
admin_password: wgportal
editable_keys: true
diff --git a/master/documentation/getting-started/binaries/index.html b/master/documentation/getting-started/binaries/index.html
index 523929f..cc86f40 100644
--- a/master/documentation/getting-started/binaries/index.html
+++ b/master/documentation/getting-started/binaries/index.html
@@ -1,5 +1,5 @@
- Binaries - WireGuard Portal Binaries
Starting from v2, each release includes compiled binaries for supported platforms. These binary versions can be manually downloaded and installed.
Download
With curl:
curl -L -o wg-portal https://github.com/h44z/wg-portal/releases/download/${WG_PORTAL_VERSION}/wg-portal_linux_amd64
+ Binaries - WireGuard Portal Binaries
Starting from v2, each release includes compiled binaries for supported platforms. These binary versions can be manually downloaded and installed.
Download
With curl:
curl -L -o wg-portal https://github.com/h44z/wg-portal/releases/download/${WG_PORTAL_VERSION}/wg-portal_linux_amd64
With wget:
wget -O wg-portal https://github.com/h44z/wg-portal/releases/download/${WG_PORTAL_VERSION}/wg-portal_linux_amd64
with gh cli:
gh release download ${WG_PORTAL_VERSION} --repo h44z/wg-portal --output wg-portal --pattern '*amd64'
Install
sudo mkdir -p /opt/wg-portal
diff --git a/master/documentation/getting-started/docker/index.html b/master/documentation/getting-started/docker/index.html
index 44789c3..023b53d 100644
--- a/master/documentation/getting-started/docker/index.html
+++ b/master/documentation/getting-started/docker/index.html
@@ -1,5 +1,5 @@
- Docker - WireGuard Portal Docker
Image Usage
The preferred way to start WireGuard Portal as Docker container is to use Docker Compose.
A sample docker-compose.yml:
---
+ Docker - WireGuard Portal Docker
Image Usage
The preferred way to start WireGuard Portal as Docker container is to use Docker Compose.
A sample docker-compose.yml:
---
services:
wg-portal:
image: wgportal/wg-portal:latest
diff --git a/master/documentation/getting-started/helm/index.html b/master/documentation/getting-started/helm/index.html
index 7ded1c9..ae39fcd 100644
--- a/master/documentation/getting-started/helm/index.html
+++ b/master/documentation/getting-started/helm/index.html
@@ -1,5 +1,5 @@
- Helm - WireGuard Portal Helm
Installing the Chart
To install the chart with the release name wg-portal:
helm install wg-portal oci://ghcr.io/h44z/charts/wg-portal
+ Helm - WireGuard Portal Helm
Installing the Chart
To install the chart with the release name wg-portal:
helm install wg-portal oci://ghcr.io/h44z/charts/wg-portal
This command deploy wg-portal on the Kubernetes cluster in the default configuration. The Values section lists the parameters that can be configured during installation.
Values
Key Type Default Description nameOverride string ""Partially override resource names (adds suffix) fullnameOverride string ""Fully override resource names extraDeploy list []Array of extra objects to deploy with the release config.advanced tpl/object {}Advanced configuration options. config.auth tpl/object {}Auth configuration options. config.core tpl/object {}Core configuration options.
If external admins in auth are defined and there are no admin_user and admin_password defined here, the default admin account will be disabled. config.database tpl/object {}Database configuration options config.mail tpl/object {}Mail configuration options config.statistics tpl/object {}Statistics configuration options config.web tpl/object {}Web configuration options.
listening_address will be set automatically from service.web.port. external_url is required to enable ingress and certificate resources. revisionHistoryLimit string 10The number of old ReplicaSets to retain to allow rollback. workloadType string "Deployment"Workload type - Deployment or StatefulSet strategy object {"type":"RollingUpdate"}Update strategy for the workload Valid values are: RollingUpdate or Recreate for Deployment, RollingUpdate or OnDelete for StatefulSet image.repository string "ghcr.io/h44z/wg-portal"Image repository image.pullPolicy string "IfNotPresent"Image pull policy image.tag string ""Overrides the image tag whose default is the chart appVersion imagePullSecrets list []Image pull secrets podAnnotations tpl/object {}Extra annotations to add to the pod podLabels object {}Extra labels to add to the pod podSecurityContext object {}Pod Security Context securityContext.capabilities.add list ["NET_ADMIN"]Add capabilities to the container initContainers tpl/list []Pod init containers sidecarContainers tpl/list []Pod sidecar containers dnsPolicy string "ClusterFirst"Set DNS policy for the pod. Valid values are ClusterFirstWithHostNet, ClusterFirst, Default or None. restartPolicy string "Always"Restart policy for all containers within the pod. Valid values are Always, OnFailure or Never. hostNetwork string false.Use the host's network namespace. resources object {}Resources requests and limits command list []Overwrite pod command args list []Additional pod arguments env tpl/list []Additional environment variables envFrom tpl/list []Additional environment variables from a secret or configMap livenessProbe object {}Liveness probe configuration readinessProbe object {}Readiness probe configuration startupProbe object {}Startup probe configuration volumes tpl/list []Additional volumes volumeMounts tpl/list []Additional volumeMounts nodeSelector object {"kubernetes.io/os":"linux"}Node Selector configuration tolerations list []Tolerations configuration affinity object {}Affinity configuration service.mixed.enabled bool falseWhether to create a single service for the web and wireguard interfaces service.mixed.type string "LoadBalancer"Service type service.web.annotations object {}Annotations for the web service service.web.type string "ClusterIP"Web service type service.web.port int 8888Web service port Used for the web interface listener service.web.appProtocol string "http"Web service appProtocol. Will be auto set to https if certificate is enabled. service.wireguard.annotations object {}Annotations for the WireGuard service service.wireguard.type string "LoadBalancer"Wireguard service type service.wireguard.ports list [51820]Wireguard service ports. Exposes the WireGuard ports for created interfaces. Lowerest port is selected as start port for the first interface. Increment next port by 1 for each additional interface. service.metrics.port int 8787 ingress.enabled bool falseSpecifies whether an ingress resource should be created ingress.className string ""Ingress class name ingress.annotations object {}Ingress annotations ingress.tls bool falseIngress TLS configuration. Enable certificate resource or add ingress annotation to create required secret certificate.enabled bool falseSpecifies whether a certificate resource should be created. If enabled, certificate will be used for the web. certificate.issuer.name string ""Certificate issuer name certificate.issuer.kind string ""Certificate issuer kind (ClusterIssuer or Issuer) certificate.issuer.group string "cert-manager.io"Certificate issuer group certificate.duration string ""Optional. Documentation certificate.renewBefore string ""Optional. Documentation certificate.commonName string ""Optional. Documentation certificate.emailAddresses list []Optional. Documentation certificate.ipAddresses list []Optional. Documentation certificate.keystores object {}Optional. Documentation certificate.privateKey object {}Optional. Documentation certificate.secretTemplate object {}Optional. Documentation certificate.subject object {}Optional. Documentation certificate.uris list []Optional. Documentation certificate.usages list []Optional. Documentation persistence.enabled bool falseSpecifies whether an persistent volume should be created persistence.annotations object {}Persistent Volume Claim annotations persistence.storageClass string ""Persistent Volume storage class. If undefined (the default) cluster's default provisioner will be used. persistence.accessMode string "ReadWriteOnce"Persistent Volume Access Mode persistence.size string "1Gi"Persistent Volume size serviceAccount.create bool trueSpecifies whether a service account should be created serviceAccount.annotations object {}Service account annotations serviceAccount.automount bool falseAutomatically mount a ServiceAccount's API credentials serviceAccount.name string ""The name of the service account to use. If not set and create is true, a name is generated using the fullname template monitoring.enabled bool falseEnable Prometheus monitoring. monitoring.apiVersion string "monitoring.coreos.com/v1"API version of the Prometheus resource. Use azmonitoring.coreos.com/v1 for Azure Managed Prometheus. monitoring.kind string "PodMonitor"Kind of the Prometheus resource. Could be PodMonitor or ServiceMonitor. monitoring.labels object {}Resource labels. monitoring.annotations object {}Resource annotations. monitoring.interval string 1mInterval at which metrics should be scraped. If not specified config.statistics.data_collection_interval interval is used. monitoring.metricRelabelings list []Relabelings to samples before ingestion. monitoring.relabelings list []Relabelings to samples before scraping. monitoring.scrapeTimeout string ""Timeout after which the scrape is ended If not specified, the Prometheus global scrape interval is used. monitoring.jobLabel string ""The label to use to retrieve the job name from. monitoring.podTargetLabels object {}Transfers labels on the Kubernetes Pod onto the target. monitoring.dashboard.enabled bool falseEnable Grafana dashboard. monitoring.dashboard.annotations object {}Annotations for the dashboard ConfigMap. monitoring.dashboard.labels object {}Additional labels for the dashboard ConfigMap. monitoring.dashboard.namespace string ""Dashboard ConfigMap namespace Overrides the namespace for the dashboard ConfigMap.
Sources
To build the application from source files, use the Makefile provided in the repository.
Requirements
- Git
- Make
- Go:
>=1.23.0 - NodeJS with npm:
node>=18, npm>=9
Build
# Get source code
+ Sources - WireGuard Portal Sources
To build the application from source files, use the Makefile provided in the repository.
Requirements
- Git
- Make
- Go:
>=1.23.0 - NodeJS with npm:
node>=18, npm>=9
Build
# Get source code
git clone https://github.com/h44z/wg-portal -b ${WG_PORTAL_VERSION:-master} --depth 1
cd wg-portal
# Build the frontend
diff --git a/master/documentation/monitoring/prometheus/index.html b/master/documentation/monitoring/prometheus/index.html
index a574979..1cd65c1 100644
--- a/master/documentation/monitoring/prometheus/index.html
+++ b/master/documentation/monitoring/prometheus/index.html
@@ -1,5 +1,5 @@
- Monitoring - WireGuard Portal By default WG-Portal exposes Prometheus metrics on port 8787 if interface/peer statistic data collection is enabled.
Exposed Metrics
Metric Type Description wireguard_interface_received_bytes_totalgauge Bytes received through the interface. wireguard_interface_sent_bytes_totalgauge Bytes sent through the interface. wireguard_peer_last_handshake_secondsgauge Seconds from the last handshake with the peer. wireguard_peer_received_bytes_totalgauge Bytes received from the peer. wireguard_peer_sent_bytes_totalgauge Bytes sent to the peer. wireguard_peer_upgauge Peer connection state (boolean: 1/0).
Prometheus Config
Add following scrape job to your Prometheus config file:
# prometheus.yaml
+ Monitoring - WireGuard Portal By default WG-Portal exposes Prometheus metrics on port 8787 if interface/peer statistic data collection is enabled.
Exposed Metrics
Metric Type Description wireguard_interface_received_bytes_totalgauge Bytes received through the interface. wireguard_interface_sent_bytes_totalgauge Bytes sent through the interface. wireguard_peer_last_handshake_secondsgauge Seconds from the last handshake with the peer. wireguard_peer_received_bytes_totalgauge Bytes received from the peer. wireguard_peer_sent_bytes_totalgauge Bytes sent to the peer. wireguard_peer_upgauge Peer connection state (boolean: 1/0).
Prometheus Config
Add following scrape job to your Prometheus config file:
# prometheus.yaml
scrape_configs:
- job_name: wg-portal
scrape_interval: 60s
diff --git a/master/documentation/overview/index.html b/master/documentation/overview/index.html
index e19a614..08184d1 100644
--- a/master/documentation/overview/index.html
+++ b/master/documentation/overview/index.html
@@ -1,5 +1,5 @@
- Overview - WireGuard Portal Overview
WireGuard Portal is a simple, web-based configuration portal for WireGuard server management. The portal uses the WireGuard wgctrl library to manage existing VPN interfaces. This allows for the seamless activation or deactivation of new users without disturbing existing VPN connections.
The configuration portal supports using a database (SQLite, MySQL, MsSQL or Postgres), OAuth or LDAP (Active Directory or OpenLDAP) as a user source for authentication and profile data.
Features
- Self-hosted - the whole application is a single binary
- Responsive multi-language web UI written in Vue.JS
- Automatically selects IP from the network pool assigned to the client
- QR-Code for convenient mobile client configuration
- Sends email to the client with QR-code and client config
- Enable / Disable clients seamlessly
- Generation of wg-quick configuration file (
wgX.conf) if required - User authentication (database, OAuth, or LDAP)
- IPv6 ready
- Docker ready
- Can be used with existing WireGuard setups
- Support for multiple WireGuard interfaces
- Peer Expiry Feature
- Handles route and DNS settings like wg-quick does
- Exposes Prometheus metrics for monitoring and alertingt
- REST API for management and client deployment
Overview
WireGuard Portal is a simple, web-based configuration portal for WireGuard server management. The portal uses the WireGuard wgctrl library to manage existing VPN interfaces. This allows for the seamless activation or deactivation of new users without disturbing existing VPN connections.
The configuration portal supports using a database (SQLite, MySQL, MsSQL or Postgres), OAuth or LDAP (Active Directory or OpenLDAP) as a user source for authentication and profile data.
Features
- Self-hosted - the whole application is a single binary
- Responsive multi-language web UI written in Vue.JS
- Automatically selects IP from the network pool assigned to the client
- QR-Code for convenient mobile client configuration
- Sends email to the client with QR-code and client config
- Enable / Disable clients seamlessly
- Generation of wg-quick configuration file (
wgX.conf) if required - User authentication (database, OAuth, or LDAP)
- IPv6 ready
- Docker ready
- Can be used with existing WireGuard setups
- Support for multiple WireGuard interfaces
- Peer Expiry Feature
- Handles route and DNS settings like wg-quick does
- Exposes Prometheus metrics for monitoring and alertingt
- REST API for management and client deployment
REST API
REST API
Upgrade
For production deployments of WireGuard Portal, we strongly recommend using version 1. If you want to use version 2, please be aware that it is still in beta and not feature complete.
Upgrade from v1 to v2
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.
To upgrade from a previous SQLite database, start wg-portal like:
./wg-portal-amd64 -migrateFrom=old_wg_portal.db
+ Upgrade - WireGuard Portal Upgrade
For production deployments of WireGuard Portal, we strongly recommend using version 1. If you want to use version 2, please be aware that it is still in beta and not feature complete.
Upgrade from v1 to v2
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.
To upgrade from a previous SQLite database, start wg-portal like:
./wg-portal-amd64 -migrateFrom=old_wg_portal.db
You can also specify the database type using the parameter -migrateFromType, supported types: mysql, mssql, postgres or sqlite. 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. 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:
services:
wg-portal:
diff --git a/master/index.html b/master/index.html
index d76de9c..3d7b72a 100644
--- a/master/index.html
+++ b/master/index.html
@@ -1,5 +1,5 @@
- WireGuard Portal - WireGuard Portal