Files
WGDashboard/docker
+1
DaanSelenGitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>neolegshishovunixroLEE Kai-ZeMikhail SolovevEvgeny VolfertsTheroxenestormsdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
8d21152947
CodeQL / Analyze (javascript) (push) Canceled after 0s
CodeQL / Analyze (python) (push) Canceled after 0s
Docker Build and Push / docker_build (push) Canceled after 0s
Docker Build and Push / docker_scan (push) Canceled after 0s
prepare: version 4.3.5 (#1406)
* Fix: batch IP geolocation requests (limit 100), add deduplication and caching (#1232)

- Added batching of IP addresses into chunks of 100 to comply with ip-api limits
- Implemented deduplication to avoid repeated geolocation requests for identical IPs
- Added in-memory cache to reuse results across batches
- Preserved original order and length of geolocation list in API response
- Improved error handling around external API failures

* fix: addPeers uses OverridePeerSettings for DNS and AllowedIPs fallback (#1310)

* fix: addPeers uses OverridePeerSettings for DNS and AllowedIPs fallback

When adding a peer via the API without explicit DNS or endpoint_allowed_ip
values, the endpoint fell back directly to global wg-dashboard.ini defaults,
ignoring any per-configuration OverridePeerSettings. This caused new peers to
be stored with the wrong DNS and AllowedIPs in the database even when the
configuration had overrides set.

Resolve by fetching the configuration's OverridePeerSettings before the global
defaults. The priority is now: request body → OverridePeerSettings → global
default. The existing config lookup that happened later in the function is
removed as it is now done earlier.

Note: downloadPeer already applied OverridePeerSettings at download time, so
client configs were correct; only the stored peer data was affected.

* fix: addPeers applies OverridePeerSettings for MTU and PersistentKeepalive

Extend the peer-settings priority chain (request body → OverridePeerSettings
→ global default) to MTU and PersistentKeepalive, matching the same pattern
already applied to DNS and EndpointAllowedIPs.

* style: align addPeers OverridePeerSettings fallback with project code style

* Fix: backup regex, SQL cleanup, and restore metadata conflict (#1324)

* fix: backup filename regex dot escaping

* fix: delete paired .sql file when removing backup

* fix: restore backup metadata conflict

* Bug fix. Remove redundant break statement in IP allocation loop. (#1294)

* Remove redundant break statement in IP allocation loop.

* Fix: append IP to allowed_ips list instead of overwriting it

* fix: clean up endpoint history tables on rename and delete (#1367)

* Add new AmneziaWG parameters (implemented in 3.0/3.1) (#1363)

* fix: add button type to accountSettingsInputPassword submission button (#1321)

* fix: handle instantiated SQLAlchemy column types (#1400)

* feat(docker): run drop-in scripts from /data/custom-init.d at startup (#1401)

Allows users to install additional packages or apply custom setup
by placing scripts in /data/custom-init.d, executed in alphabetical
order before WGDashboard starts.

* fix: handle existing endpoint history table during AmneziaWG restore (#1368)

* build(deps): bump pydantic from 2.14.1 to 2.14.2 in /src (#1403)

Bumps [pydantic](https://github.com/pydantic/pydantic) from 2.14.1 to 2.14.2.
- [Release notes](https://github.com/pydantic/pydantic/releases)
- [Changelog](https://github.com/pydantic/pydantic/blob/v2.14.2/HISTORY.md)
- [Commits](https://github.com/pydantic/pydantic/compare/v2.14.1...v2.14.2)

---
updated-dependencies:
- dependency-name: pydantic
  dependency-version: 2.14.2
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* build(deps): bump @vue/language-server in /src/static/app (#1404)

Bumps [@vue/language-server](https://github.com/vuejs/language-tools/tree/HEAD/packages/language-server) from 3.3.13 to 3.3.14.
- [Release notes](https://github.com/vuejs/language-tools/releases)
- [Changelog](https://github.com/vuejs/language-tools/blob/master/CHANGELOG.md)
- [Commits](https://github.com/vuejs/language-tools/commits/v3.3.14/packages/language-server)

---
updated-dependencies:
- dependency-name: "@vue/language-server"
  dependency-version: 3.3.14
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* build(deps): bump axios from 1.20.0 to 1.21.0 in /src/static/client (#1405)

Bumps [axios](https://github.com/axios/axios) from 1.20.0 to 1.21.0.
- [Release notes](https://github.com/axios/axios/releases)
- [Changelog](https://github.com/axios/axios/blob/v1.x/CHANGELOG.md)
- [Commits](https://github.com/axios/axios/compare/v1.20.0...v1.21.0)

---
updated-dependencies:
- dependency-name: axios
  dependency-version: 1.21.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: neolegshishov <143963760+neolegshishov@users.noreply.github.com>
Co-authored-by: unixro <mihaivint@users.noreply.github.com>
Co-authored-by: LEE Kai-Ze <mail@leekaize.com>
Co-authored-by: Mikhail Solovev <mike@solovjov.net>
Co-authored-by: Evgeny Volferts <eugene.wolferz@gmail.com>
Co-authored-by: Theroxenes <theroxenes@proton.me>
Co-authored-by: torms <8841885+torms@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-11-02 22:09:06 +01:00
..
2026-11-02 22:09:06 +01:00
2026-11-02 22:09:06 +01:00

WGDashboard Docker Explanation:

Author: @DaanSelen

This document delves into how the WGDashboard Docker container has been built.
Of course there are two stages (simply said), one before run-time and one at/after run-time.
The Dockerfile describes how the container image is made, and the entrypoint.sh is executed after the container is started.
In this example, WireGuard is integrated into the container itself, so it should be a run-and-go(/out-of-the-box) experience.
For more details on the source-code specific to this Docker image, refer to the source files, they have lots of comments.


WG-Dashboard Logo

To get the container running you either pull the pre-made image from a remote repository, there are 2 official options.

  • ghcr.io/wgdashboard/wgdashboard:
  • docker.io/donaldzou/wgdashboard:

tags should be either: latest, main, , (if built) or .

From there either use the environment variables described below as parameters or use the Docker Compose file: compose.yaml.
Be careful, the default generated WireGuard configuration file uses port 51820/udp. So make sure to use this port if you want to use it out of the box.
Otherwise edit the configuration file in WGDashboard under Configuration Settings -> Edit Raw Configuration File.

Otherwise you need to enter the container and edit: /etc/wireguard/wg0.conf.

WGDashboard: 🐳 Docker Deployment Guide

To run the container, you can either pull the image from the Github Container Registry (ghcr.io), Docker Hub (docker.io) or build it yourself. The image is available at:

docker.io is in most cases automatically resolved by the Docker application. Therefor you can ofter specify: donaldzou/wgdashboard:latest

🔧 Quick Docker Run Command

Here's an example to get it up and running quickly:

docker run -d \
  --name wgdashboard \
  --restart unless-stopped \
  -p 10086:10086/tcp \
  -p 51820:51820/udp \
  --cap-add NET_ADMIN \
  ghcr.io/wgdashboard/wgdashboard:latest

⚠️ The default WireGuard port is 51820/udp. If you change this, update the /etc/wireguard/wg0.conf accordingly.


📦 Docker Compose Alternative (see the compose file)

You can also use Docker Compose for easier configuration:

services:
  wgdashboard:
    image: ghcr.io/wgdashboard/wgdashboard:latest
    restart: unless-stopped
    container_name: wgdashboard
    ports:
      - 10086:10086/tcp
      - 51820:51820/udp

    volumes:
      - aconf:/etc/amnezia/amneziawg
      - conf:/etc/wireguard
      - data:/data

    cap_add:
      - NET_ADMIN

volumes:
  aconf:
  conf:
  data:

📁 You can customize the volume paths on the host to fit your needs. The example above uses Docker volumes.


🔄 Updating the Container

Updating the WGDashboard container should be through 'The Docker Way' - by pulling the newest/newer image and replacing this old one.


⚙️ Environment Variables

Variable Accepted Values Default Example Description
dynamic_config true, yes, false, no true true or no Turns on or off the dynamic configuration feature, on by default for Docker
tz Timezone Europe/Amsterdam America/New_York Sets the container's timezone. Useful for accurate logs and scheduling.
global_dns IPv4 and IPv6 addresses 9.9.9.9 8.8.8.8, 1.1.1.1 Default DNS for WireGuard clients.
public_ip Public IP address Retrieved automatically 253.162.134.73 Used to generate accurate client configs. Needed if container is NAT’d.
wgd_port Any port that is allowed for the process 10086 443 This port is used to set the WGDashboard web port.
username Any non‐empty string - admin Username for the WGDashboard web interface account.
password Any non‐empty string - s3cr3tP@ss Password for the WGDashboard web interface account (stored hashed).
enable_totp true, false true false Enable TOTP‐based two‐factor authentication for the account.
wg_autostart Wireguard interface name - wg0 Automatically start the specified WireGuard interface when the container starts
email_server SMTP server address - smtp.gmail.com SMTP server for sending email notifications.
email_port SMTP port number - 587 Port for connecting to the SMTP server.
email_encryption TLS, SSL, etc. - TLS Encryption method for email communication.
email_username Any non-empty string - user@example.com Username for SMTP authentication.
email_password Any non-empty string - app_password Password for SMTP authentication.
email_from Valid email address - noreply@example.com Email address used as the sender for notifications.
email_template Path to template file - your-template Custom template for email notifications.
database_type sqlite, postgresql, mariadb+mariadbconnector, etc. - postgresql Type of sqlalchemy database engine.
database_host Any non-empty string - localhost IP-Address or hostname of the SQL-database server.
database_port Any non-empty string (or int for port) - 5432 Port for the database communication.
database_username Valid database username - database_user Database user username.
database_password Valid database password - database_password Database user password.

🧩 Custom Startup Scripts

Every file placed in /data/custom-init.d/ is executed with bash at container startup, in alphabetical order, right before WGDashboard starts. A failing script is logged but does not stop the container.

This is useful for installing additional packages, for example /data/custom-init.d/apk-add:

apk update > /dev/null 2>&1
apk add --no-cache util-linux openssh-client > /dev/null 2>&1

📁 When using a Docker volume for /data, you can also bind-mount the directory directly, e.g. ./custom-init.d:/data/custom-init.d:ro.


🔐 Port Forwarding Note

When using multiple WireGuard interfaces, remember to open their respective ports on the host.

Examples:

# Individual mapping
- 51821:51821/udp

# Or port range
- 51820-51830:51820-51830/udp

🚨 Security Tip: Only expose ports you actually use.


🛠️ Building the Image Yourself

To build from source:

git clone https://github.com/WGDashboard/WGDashboard.git
cd WGDashboard
docker build . -f docker/Dockerfile -t yourname/wgdashboard:latest

Example output:

docker images

REPOSITORY           TAG       IMAGE ID       CREATED             SIZE
yourname/wgdashboard latest    c96fd96ee3b3   42 minutes ago      314MB

🧱 Dockerfile Overview

Here's a brief overview of the Dockerfile stages used in the image build:

1. Build Tools & Go Compilation

FROM golang:1.24 AS compiler
WORKDIR /go

RUN apt-get update && apt-get install -y ...
RUN git clone ... && make
...

2. Binary Copy to Scratch

FROM scratch AS bins
COPY --from=compiler /go/amneziawg-go/amneziawg-go /amneziawg-go
...

3. Final Alpine Container Setup

FROM alpine:latest
COPY --from=bins ...
RUN apk update && apk add --no-cache ...
COPY ./src ${WGDASH}/src
COPY ./docker/entrypoint.sh /entrypoint.sh
...
EXPOSE 10086
ENTRYPOINT ["/bin/bash", "/entrypoint.sh"]

🚀 Entrypoint Overview

Major Functions:

  • ensure_installation: Sets up the app, database, and Python environment.
  • set_envvars: Writes wg-dashboard.ini and applies environment variables.
  • run_custom_init: Runs user scripts from /data/custom-init.d/.
  • start_core: Starts the main WGDashboard service.
  • ensure_blocking: Tails the error log to keep the container process alive.

✅ Final Notes

  • Use docker logs wgdashboard for troubleshooting.
  • Access the web interface via http://your-ip:10086 (or whichever port you specified in the compose).
  • The first time run will auto-generate WireGuard keys and configs (configs are generated from the template).

🧑‍💻 Local Development with Docker

You can develop against WGDashboard locally by mounting the src/ directory into the container. This lets you edit Python and frontend code on your host and see changes reflected immediately (with a service restart for Python).

Create a docker/compose-local.yaml alongside the existing compose.yaml:

services:
  wgdashboard:
    image: ghcr.io/wgdashboard/wgdashboard:latest
    restart: unless-stopped
    container_name: wgdashboard

    ports:
      - 10086:10086/tcp
      - 51820:51820/udp

    volumes:
      - aconf:/etc/amnezia/amneziawg
      - conf:/etc/wireguard
      - data:/data
      # Mount local src for live editing
      - ../src:/opt/wgdashboard/src
      # Keep venv in a named volume so it isn't overwritten by the mount
      - venv:/opt/wgdashboard/src/venv

    cap_add:
      - NET_ADMIN

volumes:
  aconf:
  conf:
  data:
  venv:

The key additions compared to the production compose file:

  • ../src:/opt/wgdashboard/src — mounts your local src/ directory into the container so code changes are reflected without rebuilding the image.
  • venv:/opt/wgdashboard/src/venv — keeps the Python virtual environment in a named Docker volume. Without this, the host mount would overwrite the venv created during image build.

To start the development container:

cd docker
docker compose -f compose-local.yaml up -d

After editing Python files (e.g. src/dashboard.py), restart the container to pick up changes:

docker restart wgdashboard

For frontend changes, install dependencies and rebuild the Vue app on your host:

cd src/static/app
npm install
npm run build

Then restart the container so it serves the updated dist files:

docker restart wgdashboard

Closing remarks:

For feedback please submit an issue to the repository. Or message dselen@nerthus.nl.