Deployment Overview of H-UI on Server¶

Prerequisites and Basic Requirements¶

The following requirements must be met before deploying the H-UI application:

• Operating System: Ubuntu 22.04 (Jammy)

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

• Architecture Support: The system supports x86_64, amd64, aarch64, and arm64 architectures.

• Required Packages: curl and sqlite3 must be installed on the system.

• Timezone: The server timezone is configured to Europe/Amsterdam.

FQDN of the Final Panel¶

The application is accessible via the following Fully Qualified Domain Name (FQDN) structure:

• Format: hui{ServerID}.hostkey.in:443

• Domain: hostkey.in

• Prefix: hui

• Port: 443 (HTTPS)

File and Directory Structure¶

The application components are organized into the following directories:

• Application Installation Directory: /usr/local/h-ui

• Contains the H-UI binary executable.

• Contains the SQLite database file (.db).

• Systemd Service File: /etc/systemd/system/h-ui.service

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

• Contains the specific configuration file: hui{ServerID}.hostkey.in.conf

• Docker Configuration Directory: /root/nginx

• Contains the Docker Compose file: compose.yml

• SSL Secrets Directory: Mounted via Docker volume at /etc/letsencrypt inside the container, mapped from nginx_secrets external volume.

Application Installation Process¶

The H-UI application is installed as a native binary and managed via systemd. The installation process involves the following steps:

• The latest H-UI binary is downloaded from the official release repository (https://github.com/jonssonyan/h-ui) based on the system architecture.

• The binary is placed in /usr/local/h-ui/h-ui with executable permissions (0755).

• A custom systemd unit file is created at /etc/systemd/system/h-ui.service.

• The service is configured to run on port 8081.

• The service is enabled and started automatically on boot.

• The system initializes the SQLite database within the installation directory.

• The administrator account is updated in the database with the username useradmin.

Access Rights and Security¶

Security measures are implemented through the following configurations:

• Firewall: The application listens on internal port 8081, which is not directly exposed to the public internet. External traffic is routed through Nginx on port 443.

• User Permissions: The application installation directory is owned by root with permissions set to 0755.

• Service Restrictions: The H-UI service runs as a system daemon managed by systemd.

• Proxy Security: All external access is handled by a reverse proxy that terminates SSL/TLS connections, ensuring data is encrypted in transit.

Databases¶

The application uses a local SQLite database with the following characteristics:

• Database Type: SQLite

• Storage Location: Located within the /usr/local/h-ui directory.

• Connection Method: Local file-based access; no external database server is required.

• Administration Account:

• Username: useradmin

• Password: Set via a SHA-224 hash of the configured administrative password.

Docker Containers and Their Deployment¶

A reverse proxy and certificate management solution is deployed using Docker. The deployment includes:

• Image: jonasal/nginx-certbot:latest

• Deployment Method: Docker Compose located at /root/nginx/compose.yml.

• Network Mode: host

• Restart Policy: unless-stopped

• Environment Variables:

• CERTBOT_EMAIL: [email protected]

• Additional variables are loaded from /data/nginx/nginx-certbot.env.

• Volumes:

• nginx_secrets: External volume mapped to /etc/letsencrypt for certificate storage.

• /data/nginx/user_conf.d: Host directory mapped to /etc/nginx/user_conf.d for custom configuration files.

Proxy Servers¶

Nginx is configured as a reverse proxy to handle incoming HTTPS traffic and forward it to the H-UI application.

• Proxy Server: Nginx (via Docker container)

• SSL/TLS: Managed by Certbot integrated with the Nginx container.

• Configuration File: /data/nginx/user_conf.d/hui{ServerID}.hostkey.in.conf

• Routing Rules:

• External port 443 accepts HTTPS traffic.

• Traffic for the path / is proxied to http://127.0.0.1:8081.

• Internal Path: /

• External Path: /

Permission Settings¶

File and directory permissions are strictly defined as follows:

• H-UI Binary: Mode 0755 (-rwxr-xr-x).

• Systemd Service File: Mode 0644 (-rw-r--r--).

• Nginx Compose File: Mode 0644 (-rw-r--r--).

• Nginx Directory (/root/nginx): Mode 0755, owned by root:root.

• Application Directory (/usr/local/h-ui): Mode 0755, owned by root:root.

Location of Configuration Files and Data¶

Available Ports for Connection¶

• Port 443: HTTPS (External access via Nginx proxy).

• Port 8081: HTTP (Internal access, bound to 127.0.0.1, not exposed externally).

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 the service: systemctl start h-ui

• Stop the service: systemctl stop h-ui

• Restart the service: systemctl restart h-ui

• Enable on boot: systemctl enable h-ui

• Check status: systemctl status h-ui

Nginx/Certbot Container Management:

• Start the proxy containers: docker compose up -d (executed from /root/nginx)

• Stop the proxy containers: docker compose down (executed from /root/nginx)

• Update the proxy containers: Pull the latest image and restart using docker compose up -d after pulling the new image.