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.

Disclosure: contains an affiliate link to Inferno VPS.

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

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:

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.

  1. Click "+ New Client."
  2. Give it a name ("Phone — Marek", "Laptop — work").
  3. Click "Show QR Code."
  4. Open the WireGuard app on your phone, tap "+", scan the QR.
  5. 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

Doesn't give you

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.

View Inferno plans →

What to do next


Author: Ivo Pärnaste — DevOps, Tallinn. Last tested: 2026-05-22 on wg-easy 14.0, Docker CE 27.3, Ubuntu 22.04.