Deployment Overview of WireGuard UI on Server¶

Prerequisites and Basic Requirements¶

To ensure a successful deployment, the server must meet the following requirements:

• Operating System: Compatible with Ubuntu, Debian, CentOS, Rocky Linux, or AlmaLinux.

• Privileges: Root or sudo access is required for installation and configuration.

• Network Configuration:

• IPv4 forwarding must be enabled (net.ipv4.ip_forward = 1).

• IP masquerading must be active to allow traffic routing through the VPN interface.

• Required Ports:

FQDN of the final panel on the hostkey.in domain¶

The web interface is accessible via a specific subdomain template:

File and Directory Structure¶

The application uses the following directory structure for configuration and data persistence:

• /data/wgui/: Database and WireGuard UI application data.

• /root/wgui/: Application deployment files (including compose.yml).

• /data/nginx/user_conf.d/: Nginx virtual host configurations.

• /etc/squid/: Squid proxy configuration files.

• /etc/wireguard/: WireGuard service configuration files.

• /data/nginx/nginx-certbot.env: Environment variables for SSL certificate management.

Application Installation Process¶

The installation process involves several stages to prepare the environment and deploy the application:

1. System Preparation: The system is configured with IPv4 forwarding enabled at the kernel level.

2. Dependency Installation:

3. Docker is installed on the host.

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

5. Service Configuration:

6. A systemd service (wg-iptables.service) is created to manage NAT and firewall rules specifically for WireGuard traffic on Ubuntu/Debian systems.

7. Squid is configured with a custom configuration file located at /etc/squid/squid.conf.

8. Deployment: The application components are deployed using Docker Compose from the /root/wgui directory.

Access Rights and Security¶

Security is managed through both system firewalls and container capabilities:

• Firewall Management:

• On RHEL-based systems, firewalld is used to manage access.

• On Ubuntu/Debian systems, ufw is utilized with custom rules in /etc/iptables/rules.before to handle packet forwarding and NAT masquerading.

• Container Privileges: The WireGuard UI container is granted NET_ADMIN capabilities to allow it to manage network interfaces.

• Network Isolation: The application uses host networking mode for the containers to facilitate direct interaction with the host's network stack.

Databases¶

The application utilizes a local database for storing configuration and client data, which is persisted within the container via a volume mapping:

• Storage Location: /data/wgui (mapped to /app/db inside the container).

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

• Restart Policy: unless-stopped

• Environment Variables:

• WGUI_USERNAME: root

• WGUI_PASSWORD: Set during installation.

• WGUI_DNS: 8.8.8.8

• WGUI_MTU: 1400

• WGUI_SERVER_INTERFACE_ADDRESSES: 10.252.1.1/24

• WGUI_ENDPOINT_ADDRESS: Host IP address.

• Volumes:

• /data/wgui \(\rightarrow\) /app/db

• /etc/wireguard \(\rightarrow\) /etc/wireguard

nginx¶

• Image: jonasal/nginx-certbot:latest

• Restart Policy: unless-stopped

• Environment Variables:

• CERTBOT_EMAIL: [email protected]

• Volumes:

• nginx_secrets (Docker volume) \(\rightarrow\) /etc/letsencrypt

• /data/nginx/user_conf.d \(\rightarrow\) /etc/nginx/user_conf.d

Application Update Instructions¶

To update the main application, navigate to the deployment directory and execute the Docker Compose command:

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