The WireGuard Portal Docker image is available on both Docker Hub and GitHub Container Registry. It is built on the official Alpine Linux base image and comes pre-packaged with all necessary WireGuard dependencies.
This container allows you to establish WireGuard VPN connections without relying on a host system that supports WireGuard or using the linuxserver/wireguard Docker image.
The recommended method for deploying WireGuard Portal is via Docker Compose for ease of configuration and management.
These are official releases of WireGuard Portal. They correspond to the GitHub tags that we make, and you can see the release notes for them here: https://github.com/h44z/wg-portal/releases.
Once these tags show up in this repository, they will never change.
For production deployments of WireGuard Portal, we strongly recommend using one of these tags, e.g. wgportal/wg-portal:1.0.19, instead of the latest or canary tags.
If you only want to stay at the same major or major+minor version, use either v[MAJOR] or [MAJOR].[MINOR] tags. For example v1 or 1.0.
Version 1 is currently stable, version 2 is in development.
latest
This is the most recent build to master! It changes a lot and is very unstable.
We recommend that you don't use it except for development purposes.
Branch tags
For each commit in the master and the stable branch, a corresponding Docker image is build. These images use the master or stable tags.
Configuration
You can configure WireGuard Portal using a yaml configuration file. The filepath of the yaml configuration file defaults to /app/config/config.yml. It is possible to override the configuration filepath using the environment variable WG_PORTAL_CONFIG.
By default, WireGuard Portal uses a SQLite database. The database is stored in /app/data/sqlite.db.
You should mount those directories as a volume:
/app/data
/app/config
A detailed description of the configuration options can be found here.
Running WireGuard inside Docker
Modern Linux distributions ship with a kernel that supports WireGuard out of the box. This means that you can run WireGuard directly on the host system without the need for a Docker container. WireGuard Portal can then manage the WireGuard interfaces directly on the host.
If you still want to run WireGuard inside a Docker container, you can use the following example docker-compose.yml:
services:
+
By default, the webserver is listening on port 8888.
Volumes for /app/data and /app/config should be used ensure data persistence across container restarts.
WireGuard Interface Handling
WireGuard Portal supports managing WireGuard interfaces through three distinct deployment methods, providing flexibility based on your system architecture and operational preferences:
Directly on the host system: WireGuard Portal can control WireGuard interfaces natively on the host, without using containers. This setup is ideal for environments where direct access to system networking is preferred. To use this method, you need to set the network mode to host in your docker-compose.yml file.
Within the WireGuard Portal Docker container: WireGuard interfaces can be managed directly from within the WireGuard Portal container itself. This is the recommended approach when running WireGuard Portal via Docker, as it encapsulates all functionality in a single, portable container without requiring a separate WireGuard host or image. The sample docker-compose.yml file provided above is configured for this method.
Via a separate Docker container: WireGuard Portal can interface with and control WireGuard running in another Docker container, such as the linuxserver/wireguard image. This method is useful in setups that already use linuxserver/wireguard or where you want to isolate the VPN backend from the portal frontend. For this, you need to set the network mode to service:wireguard in your docker-compose.yml file, wireguard is the service name of your WireGuard container.
services:wg-portal:image:wgportal/wg-portal:latestcontainer_name:wg-portal
-restart:unless-stopped
-logging:
-options:
-max-size:"10m"
-max-file:"3"
+...cap_add:-NET_ADMINnetwork_mode:"service:wireguard"# So we ensure to stay on the same network as the wireguard container.
@@ -33,19 +34,19 @@
-./wg/config:/app/configwireguard:
-image:lscr.io/linuxserver/wireguard:latest
-container_name:wireguard
-restart:unless-stopped
-cap_add:
--NET_ADMIN
-ports:
--"51820:51820/udp"# WireGuard port, needs to match the port in wg-portal interface config
--"127.0.0.1:8888:8888"# Noticed that the port of the web UI is exposed in the wireguard container.
-volumes:
--./wg/etc:/config/wg_confs# We share the configuration (wgx.conf) between wg-portal and wireguard
-sysctls:
--net.ipv4.conf.all.src_valid_mark=1
-
For this to work, you need to have at least the following configuration set in your WireGuard Portal config:
core:
+image:lscr.io/linuxserver/wireguard:latest
+container_name:wireguard
+restart:unless-stopped
+cap_add:
+-NET_ADMIN
+ports:
+-"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:
+-./wg/etc:/config/wg_confs# We share the configuration (wgx.conf) between wg-portal and wireguard
+sysctls:
+-net.ipv4.conf.all.src_valid_mark=1
+
As the linuxserver/wireguard image uses wg-quick to manage the interfaces, you need to have at least the following configuration set for WireGuard Portal:
core:# The WireGuard container uses wg-quick to manage the WireGuard interfaces - this conflicts with WireGuard Portal during startup.# To avoid this, we need to set the restore_state option to false so that wg-quick can create the interfaces.restore_state:false
@@ -54,4 +55,6 @@
advanced:# WireGuard Portal needs to export the WireGuard configuration as wg-quick config files so that the WireGuard container can use them.config_storage_path:/etc/wireguard/
-
Also make sure that you restart the WireGuard container after you create or delete an interface in WireGuard Portal.
These are official releases of WireGuard Portal. They correspond to the GitHub tags that we make, and you can see the release notes for them here: https://github.com/h44z/wg-portal/releases.
Once these tags show up in this repository, they will never change.
For production deployments of WireGuard Portal, we strongly recommend using one of these tags, e.g. wgportal/wg-portal:1.0.19, instead of the latest or canary tags.
If you only want to stay at the same major or major+minor version, use either v[MAJOR] or [MAJOR].[MINOR] tags. For example v1 or 1.0.
Version 1 is currently stable, version 2 is in development.
latest
This is the most recent build to master! It changes a lot and is very unstable.
We recommend that you don't use it except for development purposes.
Branch tags
For each commit in the master and the stable branch, a corresponding Docker image is build. These images use the master or stable tags.
Configuration
You can configure WireGuard Portal using a YAML configuration file. The filepath of the YAML configuration file defaults to /app/config/config.yml. 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.
You should mount those directories as a volume:
/app/data
/app/config
A detailed description of the configuration options can be found here.
If you want to access configuration files in wg-quick format, you can mount the /etc/wireguard directory to a location of your choice. Also enable the config_storage_path option in the configuration file:
advanced:
+config_storage_path:/etc/wireguard
+
\ No newline at end of file
diff --git a/master/search/search_index.json b/master/search/search_index.json
index 9d58bf0..986357a 100644
--- a/master/search/search_index.json
+++ b/master/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"documentation/overview/","title":"Overview","text":"
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.
"},{"location":"documentation/configuration/examples/#ldap-authentication-and-synchronization","title":"LDAP Authentication and Synchronization","text":"
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.
Below you will find sections like core, advanced, database, statistics, mail, auth, web and webhook. Each section describes the individual configuration keys, their default values, and a brief explanation of their purpose.
These are the primary configuration options that control fundamental WireGuard Portal behavior. More advanced options are found in the subsequent Advanced section.
Description: An API token for the admin user. If a token is provided, the REST API can be accessed using this token. If empty, the API is initially disabled for the admin user.
Description: If an LDAP user is created (e.g., through LDAP sync) and has no peers, automatically create a new WireGuard peer for all server interfaces.
Description: Interval after which existing peers are checked if they are expired. Format uses s, m, h, d for seconds, minutes, hours, days, see time.ParseDuration.
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.
Description: Interval between data collection cycles (bytes sent/received, handshake times, etc.). Format uses s, m, h, d for seconds, minutes, hours, days, see time.ParseDuration.
WireGuard Portal supports multiple authentication strategies, including OpenID Connect (oidc), OAuth (oauth), and LDAP (ldap). Each can have multiple providers configured. Below are the relevant keys.
Description: Maps OIDC claims to WireGuard Portal user fields.
Available fields: user_identifier, email, firstname, lastname, phone, department, is_admin, user_groups.
Field Typical OIDC Claim Explanation user_identifiersub or preferred_username A unique identifier for the user. Often the OIDC sub claim is used because it\u2019s guaranteed to be unique for the user within the IdP. Some providers also support preferred_username if it\u2019s unique. emailemail The user\u2019s email address as provided by the IdP. Not always verified, depending on IdP settings. firstnamegiven_name The user\u2019s first name, typically provided by the IdP in the given_name claim. lastnamefamily_name The user\u2019s last (family) name, typically provided by the IdP in the family_name claim. phonephone_number The user\u2019s phone number. This may require additional scopes/permissions from the IdP to access. department Custom claim (e.g., department) If the IdP can provide organizational data, it may store it in a custom claim. Adjust accordingly (e.g., department, org, or another attribute). is_admin Custom claim or derived role If the IdP returns a role or admin flag, you can map that to is_admin. Often this is managed through custom claims or group membership. user_groupsgroups or another custom claim A list of group memberships for the user. Some IdPs provide groups out of the box; others require custom claims or directory lookups.
Description: WgPortal can grant a user admin rights by matching the value of the is_admin claim against a regular expression. Alternatively, a regular expression can be used to check if a user is member of a specific group listed in the user_group claim. The regular expressions are defined in admin_value_regex and admin_group_regex.
admin_value_regex: A regular expression to match the is_admin claim. By default, this expression matches the string \"true\" (^true$).
admin_group_regex: A regular expression to match the user_groups claim. Each entry in the user_groups claim is checked against this regex.
Description: Maps OAuth attributes to WireGuard Portal fields.
Available fields: user_identifier, email, firstname, lastname, phone, department, is_admin, user_groups.
Field Typical Claim Explanation user_identifiersub or preferred_username A unique identifier for the user. Often the OIDC sub claim is used because it\u2019s guaranteed to be unique for the user within the IdP. Some providers also support preferred_username if it\u2019s unique. emailemail The user\u2019s email address as provided by the IdP. Not always verified, depending on IdP settings. firstnamegiven_name The user\u2019s first name, typically provided by the IdP in the given_name claim. lastnamefamily_name The user\u2019s last (family) name, typically provided by the IdP in the family_name claim. phonephone_number The user\u2019s phone number. This may require additional scopes/permissions from the IdP to access. department Custom claim (e.g., department) If the IdP can provide organizational data, it may store it in a custom claim. Adjust accordingly (e.g., department, org, or another attribute). is_admin Custom claim or derived role If the IdP returns a role or admin flag, you can map that to is_admin. Often this is managed through custom claims or group membership. user_groupsgroups or another custom claim A list of group memberships for the user. Some IdPs provide groups out of the box; others require custom claims or directory lookups.
Description: WgPortal can grant a user admin rights by matching the value of the is_admin claim against a regular expression. Alternatively, a regular expression can be used to check if a user is member of a specific group listed in the user_group claim. The regular expressions are defined in admin_value_regex and admin_group_regex.
admin_value_regex: A regular expression to match the is_admin claim. By default, this expression matches the string \"true\" (^true$).
admin_group_regex: A regular expression to match the user_groups claim. Each entry in the user_groups claim is checked against this regex.
Description: Maps LDAP attributes to WireGuard Portal fields.
Available fields: user_identifier, email, firstname, lastname, phone, department, memberof.
WireGuard Portal Field Typical LDAP Attribute Short Description user_identifier sAMAccountName / uid Uniquely identifies the user within the LDAP directory. email mail / userPrincipalName Stores the user's primary email address. firstname givenName Contains the user's first (given) name. lastname sn Contains the user's last (surname) name. phone telephoneNumber / mobile Holds the user's phone or mobile number. department departmentNumber / ou Specifies the department or organizational unit of the user. memberof memberOf Lists the groups and roles to which the user belongs.
Description: How frequently (in duration, e.g. 30m) to synchronize users from LDAP. Empty or 0 disables sync. Format uses s, m, h, d for seconds, minutes, hours, days, see time.ParseDuration. Only users that match the sync_filter are synchronized, if disable_missing is true, users not found in LDAP are disabled.
The web section contains configuration options for the web server, including the listening address, session management, and CSRF protection. It is important to specify a valid external_url for the web server, especially if you are using a reverse proxy. Without a valid external_url, the login process may fail due to CSRF protection.
Description: The URL where a client can access WireGuard Portal. This URL is used for generating links in emails and for performing OAUTH redirects. Important: If you are using a reverse proxy, set this to the external URL of the reverse proxy, otherwise login will fail. If you access the portal via IP address, set this to the IP address of the server.
The webhook section allows you to configure a webhook that is called on certain events in WireGuard Portal. A JSON object is sent in a POST request to the webhook URL with the following structure:
{\n \"event\": \"peer_created\",\n \"entity\": \"peer\",\n \"identifier\": \"the-peer-identifier\",\n \"payload\": {\n // The payload of the event, e.g. peer data.\n // Check the API documentation for the exact structure.\n }\n}\n
Description: The POST endpoint to which the webhook is sent. The URL must be reachable from the WireGuard Portal server. If the URL is empty, the webhook is disabled.
These are official releases of WireGuard Portal. They correspond to the GitHub tags that we make, and you can see the release notes for them here: https://github.com/h44z/wg-portal/releases.
Once these tags show up in this repository, they will never change.
For production deployments of WireGuard Portal, we strongly recommend using one of these tags, e.g. wgportal/wg-portal:1.0.19, instead of the latest or canary tags.
If you only want to stay at the same major or major+minor version, use either v[MAJOR] or [MAJOR].[MINOR] tags. For example v1 or 1.0.
Version 1 is currently stable, version 2 is in development.
You can configure WireGuard Portal using a yaml configuration file. The filepath of the yaml configuration file defaults to /app/config/config.yml. It is possible to override the configuration filepath using the environment variable WG_PORTAL_CONFIG.
By default, WireGuard Portal uses a SQLite database. The database is stored in /app/data/sqlite.db.
You should mount those directories as a volume:
/app/data
/app/config
A detailed description of the configuration options can be found here.
Modern Linux distributions ship with a kernel that supports WireGuard out of the box. This means that you can run WireGuard directly on the host system without the need for a Docker container. WireGuard Portal can then manage the WireGuard interfaces directly on the host.
If you still want to run WireGuard inside a Docker container, you can use the following example docker-compose.yml:
services:\n wg-portal:\n image: wgportal/wg-portal:latest\n container_name: wg-portal\n restart: unless-stopped\n logging:\n options:\n max-size: \"10m\"\n max-file: \"3\"\n cap_add:\n - NET_ADMIN\n network_mode: \"service:wireguard\" # So we ensure to stay on the same network as the wireguard container.\n volumes:\n - ./wg/etc:/etc/wireguard\n - ./wg/data:/app/data\n - ./wg/config:/app/config\n\n wireguard:\n image: lscr.io/linuxserver/wireguard:latest\n container_name: wireguard\n restart: unless-stopped\n cap_add:\n - NET_ADMIN\n ports:\n - \"51820:51820/udp\" # WireGuard port, needs to match the port in wg-portal interface config\n - \"127.0.0.1:8888:8888\" # Noticed that the port of the web UI is exposed in the wireguard container.\n volumes:\n - ./wg/etc:/config/wg_confs # We share the configuration (wgx.conf) between wg-portal and wireguard\n sysctls:\n - net.ipv4.conf.all.src_valid_mark=1\n
For this to work, you need to have at least the following configuration set in your WireGuard Portal config:
core:\n # The WireGuard container uses wg-quick to manage the WireGuard interfaces - this conflicts with WireGuard Portal during startup.\n # To avoid this, we need to set the restore_state option to false so that wg-quick can create the interfaces.\n restore_state: false\n # Usually, there are no existing interfaces in the WireGuard container, so we can set this to false.\n import_existing: false\nadvanced:\n # WireGuard Portal needs to export the WireGuard configuration as wg-quick config files so that the WireGuard container can use them.\n config_storage_path: /etc/wireguard/\n
Also make sure that you restart the WireGuard container after you create or delete an interface in WireGuard Portal.
"},{"location":"documentation/getting-started/helm/","title":"Helm","text":""},{"location":"documentation/getting-started/helm/#installing-the-chart","title":"Installing the Chart","text":"
To install the chart with the release name 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.
"},{"location":"documentation/getting-started/helm/#values","title":"Values","text":"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 10 The 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 false Whether 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 8888 Web 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 false Specifies whether an ingress resource should be created ingress.className string \"\" Ingress class name ingress.annotations object {} Ingress annotations ingress.tls bool false Ingress TLS configuration. Enable certificate resource or add ingress annotation to create required secret certificate.enabled bool false Specifies 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 false Specifies 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 persistence.volumeName string \"\" Persistent Volume Name (optional) serviceAccount.create bool true Specifies whether a service account should be created serviceAccount.annotations object {} Service account annotations serviceAccount.automount bool false Automatically 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 false Enable 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 1m Interval 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 false Enable 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."},{"location":"documentation/getting-started/sources/","title":"Sources","text":"
To build the application from source files, use the Makefile provided in the repository.
By default, WG-Portal exposes Prometheus metrics on port 8787 if interface/peer statistic data collection is enabled.
"},{"location":"documentation/monitoring/prometheus/#exposed-metrics","title":"Exposed Metrics","text":"Metric Type Description wireguard_interface_received_bytes_total gauge Bytes received through the interface. wireguard_interface_sent_bytes_total gauge Bytes sent through the interface. wireguard_peer_last_handshake_seconds gauge Seconds from the last handshake with the peer. wireguard_peer_received_bytes_total gauge Bytes received from the peer. wireguard_peer_sent_bytes_total gauge Bytes sent to the peer. wireguard_peer_up gauge Peer connection state (boolean: 1/0)."},{"location":"documentation/monitoring/prometheus/#prometheus-config","title":"Prometheus Config","text":"
Add following scrape job to your Prometheus config file:
# prometheus.yaml\nscrape_configs:\n - job_name: wg-portal\n scrape_interval: 60s\n static_configs:\n - targets:\n - localhost:8787 # Change localhost to IP Address or hostname with WG-Portal\n
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 a release candidate and not yet fully stable.
"},{"location":"documentation/upgrade/v1/#upgrade-from-v1-to-v2","title":"Upgrade from v1 to v2","text":"
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\n
You can also specify the database type using the parameter -migrateFromType, supported types: mysql, mssql, postgres or sqlite. For example:
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:
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"documentation/overview/","title":"Overview","text":"
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.
"},{"location":"documentation/configuration/examples/#ldap-authentication-and-synchronization","title":"LDAP Authentication and Synchronization","text":"
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.
Below you will find sections like core, advanced, database, statistics, mail, auth, web and webhook. Each section describes the individual configuration keys, their default values, and a brief explanation of their purpose.
These are the primary configuration options that control fundamental WireGuard Portal behavior. More advanced options are found in the subsequent Advanced section.
Description: An API token for the admin user. If a token is provided, the REST API can be accessed using this token. If empty, the API is initially disabled for the admin user.
Description: If an LDAP user is created (e.g., through LDAP sync) and has no peers, automatically create a new WireGuard peer for all server interfaces.
Description: Interval after which existing peers are checked if they are expired. Format uses s, m, h, d for seconds, minutes, hours, days, see time.ParseDuration.
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.
Description: Interval between data collection cycles (bytes sent/received, handshake times, etc.). Format uses s, m, h, d for seconds, minutes, hours, days, see time.ParseDuration.
WireGuard Portal supports multiple authentication strategies, including OpenID Connect (oidc), OAuth (oauth), and LDAP (ldap). Each can have multiple providers configured. Below are the relevant keys.
Description: Maps OIDC claims to WireGuard Portal user fields.
Available fields: user_identifier, email, firstname, lastname, phone, department, is_admin, user_groups.
Field Typical OIDC Claim Explanation user_identifiersub or preferred_username A unique identifier for the user. Often the OIDC sub claim is used because it\u2019s guaranteed to be unique for the user within the IdP. Some providers also support preferred_username if it\u2019s unique. emailemail The user\u2019s email address as provided by the IdP. Not always verified, depending on IdP settings. firstnamegiven_name The user\u2019s first name, typically provided by the IdP in the given_name claim. lastnamefamily_name The user\u2019s last (family) name, typically provided by the IdP in the family_name claim. phonephone_number The user\u2019s phone number. This may require additional scopes/permissions from the IdP to access. department Custom claim (e.g., department) If the IdP can provide organizational data, it may store it in a custom claim. Adjust accordingly (e.g., department, org, or another attribute). is_admin Custom claim or derived role If the IdP returns a role or admin flag, you can map that to is_admin. Often this is managed through custom claims or group membership. user_groupsgroups or another custom claim A list of group memberships for the user. Some IdPs provide groups out of the box; others require custom claims or directory lookups.
Description: WgPortal can grant a user admin rights by matching the value of the is_admin claim against a regular expression. Alternatively, a regular expression can be used to check if a user is member of a specific group listed in the user_group claim. The regular expressions are defined in admin_value_regex and admin_group_regex.
admin_value_regex: A regular expression to match the is_admin claim. By default, this expression matches the string \"true\" (^true$).
admin_group_regex: A regular expression to match the user_groups claim. Each entry in the user_groups claim is checked against this regex.
Description: Maps OAuth attributes to WireGuard Portal fields.
Available fields: user_identifier, email, firstname, lastname, phone, department, is_admin, user_groups.
Field Typical Claim Explanation user_identifiersub or preferred_username A unique identifier for the user. Often the OIDC sub claim is used because it\u2019s guaranteed to be unique for the user within the IdP. Some providers also support preferred_username if it\u2019s unique. emailemail The user\u2019s email address as provided by the IdP. Not always verified, depending on IdP settings. firstnamegiven_name The user\u2019s first name, typically provided by the IdP in the given_name claim. lastnamefamily_name The user\u2019s last (family) name, typically provided by the IdP in the family_name claim. phonephone_number The user\u2019s phone number. This may require additional scopes/permissions from the IdP to access. department Custom claim (e.g., department) If the IdP can provide organizational data, it may store it in a custom claim. Adjust accordingly (e.g., department, org, or another attribute). is_admin Custom claim or derived role If the IdP returns a role or admin flag, you can map that to is_admin. Often this is managed through custom claims or group membership. user_groupsgroups or another custom claim A list of group memberships for the user. Some IdPs provide groups out of the box; others require custom claims or directory lookups.
Description: WgPortal can grant a user admin rights by matching the value of the is_admin claim against a regular expression. Alternatively, a regular expression can be used to check if a user is member of a specific group listed in the user_group claim. The regular expressions are defined in admin_value_regex and admin_group_regex.
admin_value_regex: A regular expression to match the is_admin claim. By default, this expression matches the string \"true\" (^true$).
admin_group_regex: A regular expression to match the user_groups claim. Each entry in the user_groups claim is checked against this regex.
Description: Maps LDAP attributes to WireGuard Portal fields.
Available fields: user_identifier, email, firstname, lastname, phone, department, memberof.
WireGuard Portal Field Typical LDAP Attribute Short Description user_identifier sAMAccountName / uid Uniquely identifies the user within the LDAP directory. email mail / userPrincipalName Stores the user's primary email address. firstname givenName Contains the user's first (given) name. lastname sn Contains the user's last (surname) name. phone telephoneNumber / mobile Holds the user's phone or mobile number. department departmentNumber / ou Specifies the department or organizational unit of the user. memberof memberOf Lists the groups and roles to which the user belongs.
Description: How frequently (in duration, e.g. 30m) to synchronize users from LDAP. Empty or 0 disables sync. Format uses s, m, h, d for seconds, minutes, hours, days, see time.ParseDuration. Only users that match the sync_filter are synchronized, if disable_missing is true, users not found in LDAP are disabled.
The web section contains configuration options for the web server, including the listening address, session management, and CSRF protection. It is important to specify a valid external_url for the web server, especially if you are using a reverse proxy. Without a valid external_url, the login process may fail due to CSRF protection.
Description: The URL where a client can access WireGuard Portal. This URL is used for generating links in emails and for performing OAUTH redirects. Important: If you are using a reverse proxy, set this to the external URL of the reverse proxy, otherwise login will fail. If you access the portal via IP address, set this to the IP address of the server.
The webhook section allows you to configure a webhook that is called on certain events in WireGuard Portal. A JSON object is sent in a POST request to the webhook URL with the following structure:
{\n \"event\": \"peer_created\",\n \"entity\": \"peer\",\n \"identifier\": \"the-peer-identifier\",\n \"payload\": {\n // The payload of the event, e.g. peer data.\n // Check the API documentation for the exact structure.\n }\n}\n
Description: The POST endpoint to which the webhook is sent. The URL must be reachable from the WireGuard Portal server. If the URL is empty, the webhook is disabled.
The WireGuard Portal Docker image is available on both Docker Hub and GitHub Container Registry. It is built on the official Alpine Linux base image and comes pre-packaged with all necessary WireGuard dependencies.
This container allows you to establish WireGuard VPN connections without relying on a host system that supports WireGuard or using the linuxserver/wireguard Docker image.
The recommended method for deploying WireGuard Portal is via Docker Compose for ease of configuration and management.
WireGuard Portal supports managing WireGuard interfaces through three distinct deployment methods, providing flexibility based on your system architecture and operational preferences:
Directly on the host system: WireGuard Portal can control WireGuard interfaces natively on the host, without using containers. This setup is ideal for environments where direct access to system networking is preferred. To use this method, you need to set the network mode to host in your docker-compose.yml file.
Within the WireGuard Portal Docker container: WireGuard interfaces can be managed directly from within the WireGuard Portal container itself. This is the recommended approach when running WireGuard Portal via Docker, as it encapsulates all functionality in a single, portable container without requiring a separate WireGuard host or image. The sample docker-compose.yml file provided above is configured for this method.
Via a separate Docker container: WireGuard Portal can interface with and control WireGuard running in another Docker container, such as the linuxserver/wireguard image. This method is useful in setups that already use linuxserver/wireguard or where you want to isolate the VPN backend from the portal frontend. For this, you need to set the network mode to service:wireguard in your docker-compose.yml file, wireguard is the service name of your WireGuard container.
services:\n wg-portal:\n image: wgportal/wg-portal:latest\n container_name: wg-portal\n ...\n cap_add:\n - NET_ADMIN\n network_mode: \"service:wireguard\" # So we ensure to stay on the same network as the wireguard container.\n volumes:\n - ./wg/etc:/etc/wireguard\n - ./wg/data:/app/data\n - ./wg/config:/app/config\n\n wireguard:\n image: lscr.io/linuxserver/wireguard:latest\n container_name: wireguard\n restart: unless-stopped\n cap_add:\n - NET_ADMIN\n ports:\n - \"51820:51820/udp\" # WireGuard port, needs to match the port in wg-portal interface config\n - \"8888:8888/tcp\" # Noticed that the port of the web UI is exposed in the wireguard container.\n volumes:\n - ./wg/etc:/config/wg_confs # We share the configuration (wgx.conf) between wg-portal and wireguard\n sysctls:\n - net.ipv4.conf.all.src_valid_mark=1\n
As the linuxserver/wireguard image uses wg-quick to manage the interfaces, you need to have at least the following configuration set for WireGuard Portal:
core:\n # The WireGuard container uses wg-quick to manage the WireGuard interfaces - this conflicts with WireGuard Portal during startup.\n # To avoid this, we need to set the restore_state option to false so that wg-quick can create the interfaces.\n restore_state: false\n # Usually, there are no existing interfaces in the WireGuard container, so we can set this to false.\n import_existing: false\nadvanced:\n # WireGuard Portal needs to export the WireGuard configuration as wg-quick config files so that the WireGuard container can use them.\n config_storage_path: /etc/wireguard/\n
All images are hosted on Docker Hub at https://hub.docker.com/r/wgportal/wg-portal or in the GitHub Container Registry. There are three types of tags in the repository:
These are official releases of WireGuard Portal. They correspond to the GitHub tags that we make, and you can see the release notes for them here: https://github.com/h44z/wg-portal/releases.
Once these tags show up in this repository, they will never change.
For production deployments of WireGuard Portal, we strongly recommend using one of these tags, e.g. wgportal/wg-portal:1.0.19, instead of the latest or canary tags.
If you only want to stay at the same major or major+minor version, use either v[MAJOR] or [MAJOR].[MINOR] tags. For example v1 or 1.0.
Version 1 is currently stable, version 2 is in development.
You can configure WireGuard Portal using a YAML configuration file. The filepath of the YAML configuration file defaults to /app/config/config.yml. 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.
You should mount those directories as a volume:
/app/data
/app/config
A detailed description of the configuration options can be found here.
If you want to access configuration files in wg-quick format, you can mount the /etc/wireguard directory to a location of your choice. Also enable the config_storage_path option in the configuration file:
advanced:\n config_storage_path: /etc/wireguard\n
"},{"location":"documentation/getting-started/helm/","title":"Helm","text":""},{"location":"documentation/getting-started/helm/#installing-the-chart","title":"Installing the Chart","text":"
To install the chart with the release name 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.
"},{"location":"documentation/getting-started/helm/#values","title":"Values","text":"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 10 The 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 false Whether 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 8888 Web 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 false Specifies whether an ingress resource should be created ingress.className string \"\" Ingress class name ingress.annotations object {} Ingress annotations ingress.tls bool false Ingress TLS configuration. Enable certificate resource or add ingress annotation to create required secret certificate.enabled bool false Specifies 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 false Specifies 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 persistence.volumeName string \"\" Persistent Volume Name (optional) serviceAccount.create bool true Specifies whether a service account should be created serviceAccount.annotations object {} Service account annotations serviceAccount.automount bool false Automatically 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 false Enable 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 1m Interval 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 false Enable 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."},{"location":"documentation/getting-started/sources/","title":"Sources","text":"
To build the application from source files, use the Makefile provided in the repository.
By default, WG-Portal exposes Prometheus metrics on port 8787 if interface/peer statistic data collection is enabled.
"},{"location":"documentation/monitoring/prometheus/#exposed-metrics","title":"Exposed Metrics","text":"Metric Type Description wireguard_interface_received_bytes_total gauge Bytes received through the interface. wireguard_interface_sent_bytes_total gauge Bytes sent through the interface. wireguard_peer_last_handshake_seconds gauge Seconds from the last handshake with the peer. wireguard_peer_received_bytes_total gauge Bytes received from the peer. wireguard_peer_sent_bytes_total gauge Bytes sent to the peer. wireguard_peer_up gauge Peer connection state (boolean: 1/0)."},{"location":"documentation/monitoring/prometheus/#prometheus-config","title":"Prometheus Config","text":"
Add following scrape job to your Prometheus config file:
# prometheus.yaml\nscrape_configs:\n - job_name: wg-portal\n scrape_interval: 60s\n static_configs:\n - targets:\n - localhost:8787 # Change localhost to IP Address or hostname with WG-Portal\n
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 a release candidate and not yet fully stable.
"},{"location":"documentation/upgrade/v1/#upgrade-from-v1-to-v2","title":"Upgrade from v1 to v2","text":"
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\n
You can also specify the database type using the parameter -migrateFromType, supported types: mysql, mssql, postgres or sqlite. For example:
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: