/wg-easy

The easiest way to run WireGuard VPN + Web-based Admin UI.

Primary LanguageJavaScriptOtherNOASSERTION

WireGuard Easy

Build & Publish Docker Image to Docker Hub Lint Docker Sponsor GitHub Stars

You have found the easiest way to install & manage WireGuard on any Linux host!

Features

  • All-in-one: WireGuard + Web UI.
  • Easy installation, simple to use.
  • List, create, edit, delete, enable & disable clients.
  • Show a client's QR code.
  • Download a client's configuration file.
  • Statistics for which clients are connected.
  • Tx/Rx charts for each connected client.
  • Gravatar support.
  • Automatic Light / Dark Mode
  • Multilanguage Support
  • UI_TRAFFIC_STATS (default off)

Requirements

  • A host with a kernel that supports WireGuard (all modern kernels).
  • A host with Docker installed.

Versions

We provide more then 1 docker image to get, this will help you decide which one is best for you.
For stable versions instead of nightly or development please read README from the production branch!

tag Branch Example Description
latest production ghcr.io/wg-easy/wg-easy:latest or ghcr.io/wg-easy/wg-easy stable as possbile get bug fixes quickly when needed, deployed against production.
13 production ghcr.io/wg-easy/wg-easy:13 same as latest, stick to a version tag.
nightly master ghcr.io/wg-easy/wg-easy:nightly mostly unstable gets frequent package and code updates, deployed against master.
development pull requests ghcr.io/wg-easy/wg-easy:development used for development, testing code from PRs before landing into master.

Installation

1. Install Docker

If you haven't installed Docker yet, install it by running:

curl -sSL https://get.docker.com | sh
sudo usermod -aG docker $(whoami)
exit

And log in again.

2. Run WireGuard Easy

To automatically install & run wg-easy, simply run:

  docker run -d \
  --name=wg-easy \
  -e LANG=de \
  -e WG_HOST=<🚨YOUR_SERVER_IP> \
  -e PASSWORD_HASH=<🚨YOUR_ADMIN_PASSWORD_HASH> \
  -e PORT=51821 \
  -e WG_PORT=51820 \
  -v ~/.wg-easy:/etc/wireguard \
  -p 51820:51820/udp \
  -p 51821:51821/tcp \
  --cap-add=NET_ADMIN \
  --cap-add=SYS_MODULE \
  --sysctl="net.ipv4.conf.all.src_valid_mark=1" \
  --sysctl="net.ipv4.ip_forward=1" \
  --restart unless-stopped \
  ghcr.io/wg-easy/wg-easy

💡 Replace YOUR_SERVER_IP with your WAN IP, or a Dynamic DNS hostname.

💡 Replace YOUR_ADMIN_PASSWORD_HASH with a bcrypt password hash to log in on the Web UI. See How_to_generate_an_bcrypt_hash.md for know how generate the hash.

The Web UI will now be available on http://0.0.0.0:51821.

💡 Your configuration files will be saved in ~/.wg-easy

WireGuard Easy can be launched with Docker Compose as well - just download docker-compose.yml, make necessary adjustments and execute docker compose up --detach.

3. Sponsor

Are you enjoying this project? Buy Emile a beer! 🍻

Options

These options can be configured by setting environment variables using -e KEY="VALUE" in the docker run command.

Env Default Example Description
PORT 51821 6789 TCP port for Web UI.
WEBUI_HOST 0.0.0.0 localhost IP address web UI binds to.
PASSWORD_HASH - $2y$05$Ci... When set, requires a password when logging in to the Web UI. See How to generate an bcrypt hash.md for know how generate the hash.
WG_HOST - vpn.myserver.com The public hostname of your VPN server.
WG_DEVICE eth0 ens6f0 Ethernet device the wireguard traffic should be forwarded through.
WG_PORT 51820 12345 The public UDP port of your VPN server. WireGuard will listen on that (othwise default) inside the Docker container.
WG_CONFIG_PORT 51820 12345 The UDP port used on Home Assistant Plugin
WG_MTU null 1420 The MTU the clients will use. Server uses default WG MTU.
WG_PERSISTENT_KEEPALIVE 0 25 Value in seconds to keep the "connection" open. If this value is 0, then connections won't be kept alive.
WG_DEFAULT_ADDRESS 10.8.0.x 10.6.0.x Clients IP address range.
WG_DEFAULT_DNS 1.1.1.1 8.8.8.8, 8.8.4.4 DNS server clients will use. If set to blank value, clients will not use any DNS.
WG_ALLOWED_IPS 0.0.0.0/0, ::/0 192.168.15.0/24, 10.0.1.0/24 Allowed IPs clients will use.
WG_PRE_UP ... - See config.js for the default value.
WG_POST_UP ... iptables ... See config.js for the default value.
WG_PRE_DOWN ... - See config.js for the default value.
WG_POST_DOWN ... iptables ... See config.js for the default value.
LANG en de Web UI language (Supports: en, ua, ru, tr, no, pl, fr, de, ca, es, ko, vi, nl, is, pt, chs, cht, it, th, hi).
UI_TRAFFIC_STATS false true Enable detailed RX / TX client stats in Web UI
UI_CHART_TYPE 0 1 UI_CHART_TYPE=0 # Charts disabled, UI_CHART_TYPE=1 # Line chart, UI_CHART_TYPE=2 # Area chart, UI_CHART_TYPE=3 # Bar chart

If you change WG_PORT, make sure to also change the exposed port.

Updating

To update to the latest version, simply run:

docker stop wg-easy
docker rm wg-easy
docker pull ghcr.io/wg-easy/wg-easy

And then run the docker run -d \ ... command above again.

With Docker Compose WireGuard Easy can be updated with a single command: docker compose up --detach --pull always (if an image tag is specified in the Compose file and it is not latest, make sure that it is changed to the desired one; by default it is omitted and defaults to latest).
The WireGuared Easy container will be automatically recreated if a newer image was pulled.

Common Use Cases

For less common or specific edge-case scenarios, please refer to the detailed information provided in the Wiki.