Deployment Overview of WireGuard UI on Server¶
Prerequisites and Basic Requirements¶
To successfully deploy the WireGuard UI application, the following requirements must be met:
-
Operating System: Compatible with Ubuntu, Debian, CentOS, Rocky Linux, or AlmaLinux.
-
Privileges: Root or sudo access is required for all installation steps.
-
IPv4 Forwarding: Must be enabled on the host system to allow traffic routing.
-
Network Configuration: The server must have a public IPv4 address available for NAT and endpoint configuration.
FQDN of the final panel on the hostkey.in domain¶
The web interface is accessible via a specific subdomain generated based on the server ID.
| Parameter | Value |
|---|---|
| Prefix | ui |
| Domain | hostkey.in |
| Full template | ui{Server_ID_from_Invapi}.hostkey.in |
File and Directory Structure¶
The application uses the following directory structure for configuration, data persistence, and proxy settings:
-
/data/wgui: Stores the WireGuard UI database. -
/root/wgui: Contains the Docker Compose orchestration file. -
/etc/wireguard: Used for storing WireGuard interface configurations. -
/data/nginx/user_conf.d: Location of Nginx virtual host configuration files. -
/data/nginx/nginx-certbot.env: Environment variables for SSL certificate management. -
/etc/squid: Configuration directory for the Squid proxy service.
Application installation process¶
The installation follows a multi-step process depending on the operating system:
-
System Preparation: The installer enables IPv4 forwarding (
net.ipv4.ip_forwardandnet.ipv4.conf.all.forwarding) to allow VPN traffic to route through the host. -
Dependency Installation:
-
Docker is installed on the system to run the application containers.
-
The Squid proxy package is installed via the system package manager (
aptfor Debian/Ubuntu oryumfor RHEL-based systems). -
Network Configuration:
-
On Ubuntu/Debian: A systemd service named
wg-iptables.serviceis created to manage NAT and firewall rules for the WireGuard interface. -
On RHEL-based systems (CentOS, Rocky, AlmaLinux): The Squid service is enabled and started.
-
Container Deployment: The application is deployed using Docker Compose from the
/root/wgui/compose.ymlfile.
Access Rights and Security¶
The system implements security through both ufw (Uncomplicated Firewall) and firewalld, depending on the distribution:
-
Firewall Rules:
-
Port
22/tcp: SSH access. -
Port
80/tcp: HTTP for SSL certificate challenges. -
Port
443/tcp: HTTPS for secure web access. -
Port
51820/udp: WireGuard VPN traffic. -
Port
3128/tcp: Squid proxy service. -
IP Forwarding & NAT: Masquerading is enabled on the public interface to allow VPN clients to access the internet through the host's IP.
Databases¶
The application uses a local database for storing WireGuard configurations and user data. This database is persisted within the Docker container at /app/db and mapped to the host directory /data/wgui.
Docker Containers and Their Deployment¶
The deployment consists of two primary containers running in host network mode:
wireguard-ui¶
-
Image:
ngoduykhanh/wireguard-ui:latest -
Container Name:
wireguard-ui -
Ports: Uses host networking (accesses internal port 5000 via localhost).
-
Volumes:
-
/data/wgui:/app/db -
/etc/wireguard:/etc/wireguard -
Environment Variables: Includes
WGUI_USERNAME,WGUI_PASSWORD,WGUI_ENDPOINT_ADDRESS, andWGUI_DNS. -
Restart Policy:
unless-stopped
nginx¶
-
Image:
jonasal/nginx-certbot:latest -
Container Name: Nginx (managed via Certbot)
-
Ports: Listens on host ports 80 and 443.
-
Volumes:
-
nginx_secrets:/etc/letsencrypt -
/data/nginx/user_conf.d:/etc/nginx/user_conf.d -
Environment Variables:
CERTBOT_EMAIL. -
Restart Policy:
unless-stopped
Custom Scripts and Additional Setup¶
The installation performs several non-standard setup actions:
-
Squid Configuration: A custom
squid.confis deployed to/etc/squidto manage proxy traffic. -
Systemd Integration: On Debian/Ubuntu systems, a custom service
wg-iptables.serviceis installed to handle the complex iptables rules required for WireGuard NAT and packet forwarding.
Application Update Instructions¶
To update the main application, navigate to the deployment directory and run:
Location of configuration files and data¶
-
WireGuard UI Database:
/data/wgui -
Nginx User Configs:
/data/nginx/user_conf.d/ui{Server_ID_from_Invapi}.hostkey.in.conf -
Squid Configuration:
/etc/squid/squid.conf
Available ports for connection¶
| Port | Protocol | Service |
|---|---|---|
| 443 | TCP | Web UI (HTTPS) |
| 51820 | UDP | WireGuard VPN |
| 3128 | TCP | Squid Proxy |
| 80 | TCP | HTTP (SSL Challenge) |
Starting and Stopping the application¶
The application is managed via Docker Compose.
-
Start/Restart:
-
Stop: