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.