Install wg-easy: web UI for WireGuard
wg-easy is a small, single-container WireGuard manager with a clean web UI. Add and remove peers in clicks, generate QR codes for phones, watch live RX/TX. This guide deploys it the production way — bound to localhost, fronted by Nginx with HTTPS.
When to use wg-easy
If you've never touched WireGuard before, start with our bare-metal install first — understanding what's happening makes the UI useful. Once you have more than three clients and the thought of hand-editing wg0.conf for every phone is tedious, wg-easy is the answer.
Prerequisites
- Ubuntu 22.04 or 24.04 with Docker + Compose (see Docker install).
- A domain pointing at the VPS (we'll use
vpn.example.com). - An open UDP port for WireGuard itself — typically
51820.
Tested on Ubuntu 22.04, Docker CE 27.3, wg-easy 14.0, on a 2 GB Inferno VPS.
Step 1 — The Compose file
mkdir -p ~/wg-easy && cd ~/wg-easy
nano docker-compose.yml
name: wg-easy
services:
wg-easy:
image: ghcr.io/wg-easy/wg-easy:14
restart: unless-stopped
ports:
- "51820:51820/udp" # WireGuard data plane — public
- "127.0.0.1:51821:51821" # web UI — localhost only
volumes:
- wg_easy_data:/etc/wireguard
cap_add:
- NET_ADMIN
- SYS_MODULE
sysctls:
- net.ipv4.ip_forward=1
- net.ipv4.conf.all.src_valid_mark=1
environment:
LANG: en
WG_HOST: vpn.example.com
PASSWORD_HASH: "$$2a$$12$$REPLACE_WITH_BCRYPT_HASH"
WG_DEFAULT_DNS: "1.1.1.1,9.9.9.9"
WG_DEFAULT_ADDRESS: "10.8.0.x"
WG_PERSISTENT_KEEPALIVE: "25"
UI_TRAFFIC_STATS: "true"
UI_CHART_TYPE: "2"
deploy:
resources:
limits:
memory: 256M
volumes:
wg_easy_data:
Two ports for two different planes:
- 51820/udp: the actual WireGuard data path. Must be public so clients can connect.
- 127.0.0.1:51821: the web UI. Bound to localhost only. We'll put Nginx in front with HTTPS — never expose this port directly.
Step 2 — Generate the password hash
docker run --rm -it ghcr.io/wg-easy/wg-easy:14 \
wgpw 'your-strong-admin-password-here'
# Output: PASSWORD_HASH='$2a$12$abc...'
# Copy the value into docker-compose.yml.
# CRITICAL: escape every $ as $$ in the Compose file — otherwise Compose
# interprets it as variable substitution and the hash is silently wrong.
Step 3 — Bring it up
docker compose up -d
docker compose logs -f wg-easy
You should see wg-easy create the wg0 interface, bind UDP 51820, and serve the UI on 51821. No errors.
Step 4 — Nginx + HTTPS in front of the UI
Reuse the pattern from our Nginx + SSL guide:
sudo nano /etc/nginx/sites-available/vpn
server {
listen 80;
server_name vpn.example.com;
location /.well-known/acme-challenge/ {
root /var/www/html;
}
location / {
proxy_pass http://127.0.0.1:51821;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
sudo ln -s /etc/nginx/sites-available/vpn /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d vpn.example.com --redirect
Step 5 — Firewall
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 51820/udp
sudo ufw enable
Note: only 51820/udp needs to be open for VPN clients. 80/443 are for the management UI. SSH stays open for you.
Step 6 — Log in and add the first client
Visit https://vpn.example.com/. Enter the password you set the hash for. The UI opens.
- Click "+ New Client."
- Give it a name ("Phone — Marek", "Laptop — work").
- Click "Show QR Code."
- Open the WireGuard app on your phone, tap "+", scan the QR.
- Toggle the tunnel on. You're connected.
The client list shows live throughput per peer and the time of the last handshake. Disable or delete a peer with two clicks — the change is applied immediately, no server restart needed.
What wg-easy gives you (and doesn't)
Gives you
- One-click client creation with QR codes — phones onboard in seconds.
- Per-peer enable/disable without editing config files.
- Live RX/TX graphs.
- Automatic key generation per client (no manual
wg genkeydance).
Doesn't give you
- Multi-user access control. There's a single admin password; everyone with it can add and remove clients. For multi-tenant or team setups look at wg-portal.
- Granular per-peer allowed-IPs (split tunneling at the server level). For that, you still edit configs manually — see split tunneling.
- IPv6. As of v14, dual-stack support is partial — fine for IPv4-only setups, awkward otherwise.
Upgrading wg-easy
cd ~/wg-easy
# edit docker-compose.yml — bump the tag, e.g. 14 -> 15 when it ships
docker compose pull
docker compose up -d
The wg_easy_data volume holds your peer list and keys — preserved across image updates within the same major version. Read release notes before a major bump.
Backing up wg-easy
The only state worth backing up is the wg_easy_data volume, which contains both wg0.conf and all the per-peer key files. Lose this and every connected client needs to be re-registered.
docker run --rm \
-v wg-easy_wg_easy_data:/data:ro \
-v "$(pwd)":/backup \
alpine tar czf /backup/wg-easy-$(date +%Y%m%d).tar.gz -C /data .
Same backup pattern as our n8n guide.
Common wg-easy mistakes
Admin login fails with the right password
The $ characters in the bcrypt hash weren't escaped as $$ in the Compose YAML. Re-paste the hash with proper escaping and recreate the container.
UI loads but clients can't connect
UFW isn't allowing 51820/udp, or the VPS provider's external firewall is blocking UDP. Confirm with sudo ufw status and nc -u -l 51820 on the server while another machine tries to reach it.
"Wireguard module not loaded"
Some VPS providers run a stripped kernel without the WireGuard module. Almost all major providers (Inferno, Hetzner, Vultr, DigitalOcean) ship the module by default; if yours doesn't, install wireguard-dkms on the host and reboot.
Throughput is much lower than expected
You're seeing CPU saturation on a single core. WireGuard is fast but still single-threaded per peer. Test with multiple parallel connections; the per-connection cap is normal.
VPS for a family or small-team VPN?
A 2 GB Inferno plan handles wg-easy + Nginx + 20+ concurrent peers with headroom. Eight EU/Asia locations let you pick a privacy-friendly jurisdiction.
What to do next
- Client setup guide with screenshots for every OS.
- Split tunneling if you don't want to route everything through the VPN.
- WireGuard vs OpenVPN for the design trade-offs.
- fail2ban on the Nginx admin endpoint — defense in depth.
Author: Ivo Pärnaste — DevOps, Tallinn. Last tested: 2026-05-22 on wg-easy 14.0, Docker CE 27.3, Ubuntu 22.04.