wgportal/wg-portal repository overview

⁠WireGuard Portal Docker Image

This repository is where you'll find Docker images of WireGuard Portal⁠ for you to use. There are three types of tags in here:

⁠Semantic versioned tags

For example, 2.0.0 or v2.0.0.

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:2.0.0, 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 v2 or 2.0.

Version 2 is the current stable release. Version 1 has moved to legacy status and is no longer recommended.

⁠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.

⁠About WireGuard Portal

WireGuard Portal is a simple, web based configuration portal for WireGuard⁠. The portal uses the WireGuard wgctrl⁠ library to manage existing VPN interfaces. This allows for seamless activation or deactivation of new users, without disturbing existing VPN connections.

The 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 alerting
• REST API for management and client deployment
• Webhook for custom actions on peer, interface, or user updates

⁠Configuration

You can configure WireGuard Portal using a YAML configuration file. 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.

All available YAML configuration options are available in the official documentation⁠.

A very basic example:

core:
  admin_user: [email protected]
  admin_password: secret

web:
  external_url: http://localhost:8888
  request_logging: true

⁠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:v2
    container_name: wg-portal
    restart: unless-stopped
    logging:
      options:
        max-size: "10m"
        max-file: "3"
    cap_add:
      - NET_ADMIN
    # Use host network mode for WireGuard and the UI. Ensure that access to the UI is properly secured.
    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
#    restart: no
#    command: ["-migrateFrom=/app/data/wg_portal.db"]

By default, the webserver is listening on port 8888 on all interfaces.

Volumes for /app/data and /app/config should be used to ensure data persistence across container restarts.

⁠Contributing / Issues / Help

If you need any assistance or you want to report a bug, please use Github: https://github.com/h44z/wg-portal⁠

⁠License

• MIT License. MIT⁠ or https://opensource.org/licenses/MIT⁠