FORCETOC

Wireguard VPN Deployment Guide: Portainer + Wireguard-UI

This tutorial explains how to deploy a Wireguard VPN server with a graphical user interface using Portainer. This setup allows you to create a secure virtual network where all connected devices can communicate using their VPN internal IPs, regardless of their physical location.

1. Prerequisites

Portainer CE installed on your Host Machine.

Port 51820/UDP opened on your router or firewall (for VPN traffic).

Port 5000/TCP opened (for the Web UI).

A folder created for configuration persistence: ~/wg241103.

2. Deployment via Portainer Stack

Log into Portainer.

Navigate to Stacks > Add stack.

Name the stack wireguard-vpn.

Paste the following configuration:

version: "3"

services:
wireguard:
image: linuxserver/wireguard:v1.0.20210914-ls7
container_name: wireguard
cap_add:
- NET_ADMIN
volumes:
- ~/wg241103/config:/config
ports:
- "5000:5000"
- "51820:51820/udp"

wireguard-ui:
image: ngoduykhanh/wireguard-ui:latest
container_name: wireguard-ui
depends_on:
- wireguard
cap_add:
- NET_ADMIN
network_mode: service:wireguard
environment:
- SENDGRID_API_KEY=your_sendgrid_api_key
- EMAIL_FROM_ADDRESS=your-email@example.com
- EMAIL_FROM_NAME=AdminName
- SESSION_SECRET=YourSecureRandomString123!
- WGUI_USERNAME=admin_user
- WGUI_PASSWORD=your_secure_password
- WGUI_MANAGE_START=true
- WGUI_MANAGE_RESTART=true
logging:
driver: json-file
options:
max-size: 50m
volumes:
- ~/wg241103/db:/app/db
- ~/wg241103/config:/etc/wireguard

Click Deploy the stack.

3. Standard Operating Procedure (SOP)

A. Accessing the UI

Open your browser and go to: http://[Host-IP]:5000

Log in with:

- Username: admin_user
- Password: your_secure_password

B. Global Server Settings (Subnetwork Setup)

Before adding users, configure the internal network:

Go to Wireguard Settings.

Endpoint: Enter your Public IP or DDNS (e.g., https://www.google.com/search?q=yourdomain.com:51820).

Address Range (Subnet): Define your VPN subnet (Default is usually 10.252.1.0/24). This ensures all devices get an IP like 10.252.1.x.

DNS Server: Set to 1.1.1.1 or your local DNS.

Click Save and then click the Apply Config button at the top right.

C. Adding Users (Clients)

Go to New Client.

Name: Enter the device name (e.g., Work-Laptop or Home-PC).

IP Allocation: The UI will automatically pick the next available IP in your subnet (e.g., 10.252.1.2).

Click Submit.

Click Apply Config to restart the Wireguard service with the new user.

D. Installing on Devices

On the Wireguard-UI dashboard, click the QR Code icon for mobile devices or the Download icon for PCs.

For Mobile (Android/iOS): Install the Wireguard app and scan the QR code.

For Windows/Linux/Mac:

Download the Wireguard client from wireguard.com.

Import the downloaded .conf file into the application.

Click Activate.

4. Accessing Devices via VPN

Once connected, your devices are effectively on the same virtual switch.

Ping Test: If your Laptop is 10.252.1.2 and your Host Machine is 10.252.1.1, you can access the Host services using the VPN IP instead of the local or public IP.

Headless Access: Use the VPN IP (e.g., 10.252.1.1) to SSH or RDP into your machines securely from anywhere in the world.

Security: This allows you to close Port 9443 (Portainer) and Port 22 (SSH) to the public internet, only allowing access through the Wireguard tunnel.