Deployment Overview of HunyuanVideo on Server¶

Prerequisites and Basic Requirements¶

The deployment of HunyuanVideo requires a Linux-based environment with specific hardware and software configurations to support GPU-accelerated video generation.

• Operating System: Ubuntu 22.04 LTS (or compatible version with HWE kernel).

• Privileges: Root access or sudo privileges are required for system-wide package installation and Docker configuration.

• Hardware: NVIDIA GPU with compatible drivers and CUDA support.

• Network: Access to the internet for downloading repositories, models, and certificates.

• Ports: Port 443 is required for external HTTPS access.

FQDN of the Final Panel¶

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

• Domain Format: hvideo<Server ID>.hostkey.in

• Port: 443 (HTTPS)

• Path: /

File and Directory Structure¶

The application and its supporting components are organized in the following directory structure:

• Application Source: /opt/HunyuanVideo

• Contains the cloned repository from Tencent.

• Python Environment: /opt/HunyuanVideo/venv

• Virtual environment for Python dependencies.

• Models: /opt/HunyuanVideo/models

• Storage location for downloaded HunyuanVideo checkpoints.

• Nginx Configuration:

• Directory: /root/nginx

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

• User configuration: /data/nginx/user_conf.d/hvideo<Server ID>.hostkey.in.conf

• Docker Secrets: /etc/letsencrypt (mounted volume for SSL certificates).

Application Installation Process¶

The installation involves cloning the repository, setting up a Python virtual environment, installing dependencies, and downloading the necessary AI models.

1. Clone the Repository: The HunyuanVideo repository is cloned from GitHub to the /opt/HunyuanVideo directory.

   git clone https://github.com/Tencent/HunyuanVideo.git /opt/HunyuanVideo
   

2. Create Virtual Environment: A Python 3 virtual environment is created within the application directory.

   python3 -m venv /opt/HunyuanVideo/venv
   

3. Install Dependencies: Python packages are installed using pip from the requirements.txt file.

   source /opt/HunyuanVideo/venv/bin/activate
   pip install -r /opt/HunyuanVideo/requirements.txt
   

4. Install Hugging Face CLI: The huggingface-hub package with CLI support is installed to facilitate model downloads.

   pip install "huggingface-hub[cli]"
   

5. Download Models: Pre-trained checkpoints are downloaded directly to the models directory.

   mkdir -p /opt/HunyuanVideo/models
   huggingface-cli download tencent/HunyuanVideo \
     --local-dir /opt/HunyuanVideo/models \
     --local-dir-use-symlinks False \
     --include "hunyuan-video-t2v-720p/**"
   

Access Rights and Security¶

Security is managed through system-level package installation and Docker runtime configuration.

• System Packages: Essential tools such as git, python3, curl, and wget are installed via apt.

• NVIDIA Drivers: The nvidia-docker2 package is installed to enable GPU passthrough for containers.

• Docker Runtime: The default Docker runtime is configured to use the NVIDIA container runtime.

• Firewall: External access is restricted to port 443 for HTTPS traffic managed by the Nginx proxy.

Databases¶

The provided configuration does not include external database connections or persistent storage for relational data. The application relies on local file storage for models and generated outputs within the /opt/HunyuanVideo directory.

Docker Containers and Their Deployment¶

The deployment utilizes Docker containers for the reverse proxy and SSL management. The application itself runs in the host environment with GPU access configured via the NVIDIA runtime.

• Nginx-Certbot Container:

• Image: jonasal/nginx-certbot:latest

• Restart Policy: unless-stopped

• Network Mode: host

• Volumes:

  • nginx_secrets mounted to /etc/letsencrypt

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

• Environment:

  • CERTBOT_EMAIL: [email protected]

  • Configuration loaded from /data/nginx/nginx-certbot.env

• Docker Compose File: The container orchestration is defined in /root/nginx/compose.yml.

• NVIDIA Runtime Configuration: Docker is configured to use the NVIDIA runtime by default via /etc/docker/daemon.json:

  {
    "default-runtime": "nvidia",
    "runtimes": {
      "nvidia": {
        "path": "nvidia-container-runtime",
        "runtimeArgs": []
      }
    }
  }
  

Proxy Servers¶

Nginx acts as the reverse proxy and SSL terminator for the application.

• Proxy Configuration:

• The Nginx configuration file is located at /data/nginx/user_conf.d/hvideo<Server ID>.hostkey.in.conf.

• The proxy_pass directive forwards requests to the internal application service:

  location / {
      proxy_pass http://127.0.0.1:8080;
  }
  

• SSL/TLS:

• Managed automatically by the nginx-certbot container.

• Certificates are stored in the nginx_secrets volume.

• Custom Domain:

• The domain hvideo<Server ID>.hostkey.in is mapped to the internal service.

Permission Settings¶

File and directory permissions are set to ensure proper access for the root user and the Docker daemon.

• Nginx Directory:

• Path: /root/nginx

• Owner: root:root

• Mode: 0755

• Compose File:

• Path: /root/nginx/compose.yml

• Owner: root:root

• Mode: 0644

• Application Directory:

• Path: /opt/HunyuanVideo

• Permissions are managed by the user executing the Python scripts (typically root or a dedicated service user).

Location of Configuration Files and Data¶

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

Available Ports for Connection¶

The following ports are configured for external and internal communication:

• Port 443: External HTTPS access via Nginx proxy.

• Port 8080: Internal HTTP port used by the application, proxied by Nginx.

Starting, Stopping, and Updating¶

Service management is handled through Docker Compose for the proxy and standard Python commands for the application.

• Start Nginx Proxy:

  cd /root/nginx
  docker compose up -d
  

• Stop Nginx Proxy:

  cd /root/nginx
  docker compose down
  

• Update Nginx Proxy:

  cd /root/nginx
  docker compose pull
  docker compose up -d
  

• Run Application Test: To verify the installation, run the sample generation script:

  cd /opt/HunyuanVideo
  source venv/bin/activate
  python sample_video.py --prompt "A cyberpunk city at night"
  

• Restart Docker Service: Required after modifying /etc/docker/daemon.json:

  systemctl restart docker