Deployment Overview of H-UI on Server¶

Prerequisites and Basic Requirements¶

The deployment of the H-UI application requires the following system specifications and configurations:

• Operating System: Ubuntu 22.04 (Jammy).

• Privileges: Root access is required for installation and service management.

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

• Required Packages:

  • curl

  • sqlite3

• Architecture Support: The installer automatically detects and supports amd64 (x86_64) and arm64 (aarch64) architectures.

FQDN of the Final Panel¶

The application is accessible via the hostkey.in domain. The Fully Qualified Domain Name (FQDN) follows the format:

hui<Server ID>.hostkey.in:443

• Prefix: hui

• Zone: hostkey.in

• External Port: 443

File and Directory Structure¶

The application files, configuration, and data are organized in the following locations:

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

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

• Nginx Configuration Directory: /root/nginx

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

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

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

Application Installation Process¶

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

1. Directory Creation: The installation directory /usr/local/h-ui is created with root ownership and 0755 permissions.

2. Binary Download: The latest H-UI binary is downloaded from the official GitHub repository, matching the server's architecture (amd64 or arm64).

3. Service Configuration:

   • The systemd unit file is downloaded to /etc/systemd/system/h-ui.service.

   • The ExecStart command is modified to run the binary with the port flag -p 8081.

   • The Environment variable is set to TZ=Europe/Amsterdam.

4. Service Activation: The h-ui service is enabled and started.

5. Database Initialization: The application initializes its SQLite database upon the first start.

6. Admin Account Configuration:

   • The default sysadmin account is updated in the SQLite database.

   • Username: useradmin

   • Password: Hashed using SHA-224 based on the SSH password.

   • Connection Password: Set to root.<SSH Password>.

Access Rights and Security¶

Security is enforced through the following mechanisms:

• Firewall: The external port 443 is exposed for HTTPS traffic. The internal application port 8081 is bound to 127.0.0.1 and is not directly accessible from the network.

• User Accounts: The application admin account is configured with the username useradmin.

• Service Isolation: The H-UI service runs as a system daemon, and the Nginx proxy runs within an isolated Docker container.

Databases¶

The application utilizes an embedded SQLite database for data storage.

• Database Type: SQLite

• Storage Location: Located within the /usr/local/h-ui directory (specific filename generated dynamically).

• Connection Method: Local file access by the H-UI binary.

• Configuration: No external database server is required.

Docker Containers and Their Deployment¶

A Docker container is used to run the Nginx reverse proxy and manage SSL certificates.

• Container Image: jonasal/nginx-certbot:latest

• Deployment Method: Docker Compose

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

• Network Mode: host

• Restart Policy: unless-stopped

• Volumes:

  • nginx_secrets (external) mounted to /etc/letsencrypt for SSL certificates.

  • /data/nginx/user_conf.d mounted to /etc/nginx/user_conf.d for custom configurations.

Proxy Servers¶

Nginx acts as a reverse proxy to handle SSL termination and route traffic to the H-UI application.

• Proxy Software: Nginx (via Docker container)

• SSL Management: Certbot (integrated in the nginx-certbot image)

• Email for Certbot: [email protected]

• Routing Configuration:

  • External Path: /

  • Internal Path: /

  • Proxy Target: http://127.0.0.1:8081

• Configuration File: /data/nginx/user_conf.d/hui<Server ID>.hostkey.in.conf

The proxy configuration is updated to include the proxy_pass directive pointing to the internal H-UI port.

Permission Settings¶

File and directory permissions are set as follows:

Location of Configuration Files and Data¶

Key configuration and data files are located in the following paths:

• H-UI Binary: /usr/local/h-ui/h-ui

• H-UI Service Unit: /etc/systemd/system/h-ui.service

• Docker Compose: /root/nginx/compose.yml

• Nginx Site Config: /data/nginx/user_conf.d/hui<Server ID>.hostkey.in.conf

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

• SQLite Database: /usr/local/h-ui/*.db

Available Ports for Connection¶

The following ports are configured for the deployment:

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

• Port 8081: H-UI application internal port (Bound to 127.0.0.1, not exposed externally).

Starting, Stopping, and Updating¶

The H-UI application is managed using systemctl, while the Nginx 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

Nginx Proxy Management:

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

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

• Logs: docker compose logs -f (Run from /root/nginx)