Deployment Overview of H-UI VPN Server on Server¶

Prerequisites and Basic Requirements¶

The deployment of the H-UI VPN Server requires a specific operating system environment and root-level privileges. The following conditions must be met before proceeding:

• Operating System: Ubuntu 22.04 (codename: jammy). The installation process will fail on other distributions or versions.

• Privileges: Root access is required to install packages, configure systemd services, and manage Docker containers.

• Architecture Support: The application supports x86_64 (mapped to amd64) and aarch64 (mapped to arm64) architectures.

• Required Packages: The system must have curl and sqlite3 installed.

• Timezone: The server timezone is configured to match the deployment variable h_ui_timezone.

File and Directory Structure¶

The application and its supporting components utilize the following directory structure on the server:

• Application Binary: Located in the installation directory defined by h_ui_install_dir (default path not specified in source, typically /opt or similar). The binary is named h-ui.

• Systemd Service File: Located at h_ui_service_file (path variable).

• Nginx Configuration Directory: /root/nginx

• Nginx Compose File: /root/nginx/compose.yml

• Nginx User Configuration: /data/nginx/user_conf.d/

• Nginx Environment File: /data/nginx/nginx-certbot.env

• Database: An SQLite database file (.db) is generated automatically within the h_ui_install_dir directory.

• SSL Certificates: Stored in the Docker volume nginx_secrets mounted at /etc/letsencrypt inside the container.

Application Installation Process¶

The H-UI VPN Server is installed as a native binary managed by systemd. The installation process involves downloading the latest release and configuring the service unit.

1. Binary Download: The latest h-ui binary is downloaded from the GitHub repository jonssonyan/h-ui based on the server's architecture (amd64 or arm64).

2. Service Unit Configuration:

   • The h-ui.service file is downloaded from the repository.

   • The ExecStart directive is modified to include the custom port defined by h_ui_port.

   • The Environment variable is set to TZ={{ h_ui_timezone }} to ensure correct time handling.

3. Service Activation:

   • The systemd daemon is reloaded.

   • The h-ui service is enabled and started.

4. Database Initialization: The application initializes an SQLite database upon the first start. The installation script waits for this file to appear before proceeding.

5. Admin Account Setup:

   • The default sysadmin account is updated via SQL.

   • The username is changed to useradmin.

   • The password is set to the SHA-224 hash of the SSH password (ansible_ssh_pass).

   • The connection password (con_pass) is set to root. followed by the SSH password.

   • The service is restarted to apply these changes.

Docker Containers and Their Deployment¶

A reverse proxy and SSL certificate management system is deployed using Docker Compose.

• Compose File Location: /root/nginx/compose.yml

• Deployment Command: docker compose up -d executed from the /root/nginx directory.

• Container Details:

  • Image: jonasal/nginx-certbot:latest

  • Restart Policy: unless-stopped

  • Network Mode: host

  • Environment:

    • CERTBOT_EMAIL: Set to [email protected]

    • Loads additional environment variables from /data/nginx/nginx-certbot.env

  • Volumes:

    • nginx_secrets (external volume) mounted to /etc/letsencrypt

    • Host directory /data/nginx/user_conf.d mounted to /etc/nginx/user_conf.d

Proxy Servers¶

The Nginx container acts as a reverse proxy for the H-UI application.

• Proxy Configuration: The proxy pass rule is dynamically injected into the Nginx configuration file located at /data/nginx/user_conf.d/{{ prefix }}{{ server_id }}.hostkey.in.conf.

• Routing Rule:

  • The proxy_pass directive is set to http://127.0.0.1:8081.

  • This rule is inserted immediately after the location / { block.

• SSL/TLS: Managed automatically by the nginx-certbot container using Let's Encrypt.

• Custom Domains: Configuration files are stored in /data/nginx/user_conf.d/ and referenced by the Docker volume mount.

Databases¶

The application uses a local SQLite database for data persistence.

• Database Type: SQLite

• Location: The database file is created automatically within the h_ui_install_dir directory.

• Access Method: The database is accessed directly by the h-ui binary.

• Initial Configuration:

  • The account table is updated to set the username to useradmin.

  • The pass field stores the SHA-224 hash of the configured password.

  • The con_pass field stores the string root. concatenated with the SSH password.

Starting, Stopping, and Updating¶

The H-UI application is managed as a native Linux service, while the proxy is managed via Docker Compose.

• H-UI Service Management:

  • Start: systemctl start h-ui

  • Stop: systemctl stop h-ui

  • Restart: systemctl restart h-ui

  • Enable on Boot: systemctl enable h-ui

  • Status: systemctl status h-ui

• Proxy Service Management:

  • Start/Update: docker compose up -d (run from /root/nginx)

  • Stop: docker compose down (run from /root/nginx)

  • Status: docker compose ps (run from /root/nginx)

Permission Settings¶

The following permissions are applied to ensure secure operation:

• Nginx Directory: /root/nginx is owned by root:root with mode 0755.

• Compose File: /root/nginx/compose.yml is owned by root:root with mode 0644.

• H-UI Installation Directory: Owned by root:root with mode 0755.

• H-UI Binary: Executable permissions are set to 0755.

• Systemd Service File: Mode 0644.