Skip to content

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:

  1. System Preparation: The installer enables IPv4 forwarding (net.ipv4.ip_forward and net.ipv4.conf.all.forwarding) to allow VPN traffic to route through the host.

  2. Dependency Installation:

  3. Docker is installed on the system to run the application containers.

  4. The Squid proxy package is installed via the system package manager (apt for Debian/Ubuntu or yum for RHEL-based systems).

  5. Network Configuration:

  6. On Ubuntu/Debian: A systemd service named wg-iptables.service is created to manage NAT and firewall rules for the WireGuard interface.

  7. On RHEL-based systems (CentOS, Rocky, AlmaLinux): The Squid service is enabled and started.

  8. Container Deployment: The application is deployed using Docker Compose from the /root/wgui/compose.yml file.

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, and WGUI_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.conf is deployed to /etc/squid to manage proxy traffic.

  • Systemd Integration: On Debian/Ubuntu systems, a custom service wg-iptables.service is 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:

cd /root/wgui
docker compose pull && docker compose up -d

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:

    cd /root/wgui
    docker compose up -d
    

  • Stop:

    cd /root/wgui
    docker compose down
    

question_mark
Is there anything I can help you with?
question_mark
AI Assistant ×