Deployment Overview of HunyuanVideo on Server¶

Prerequisites and Basic Requirements¶

The deployment of HunyuanVideo requires a Linux environment based on Ubuntu 22.04. The system must have root privileges to install system packages, configure Docker, and manage services. The following hardware and software prerequisites are necessary:

• Operating System: Ubuntu 22.04 LTS.
• Hardware: NVIDIA GPU with compatible drivers for CUDA acceleration.
• Network Access: Internet connectivity is required to download the repository, Python dependencies, and model checkpoints.
• Ports: Port 8080 is used internally for the application service. Ports 80 and 443 are required for the Nginx proxy and SSL certificate management.

File and Directory Structure¶

The application and its supporting components are organized in specific directories on the server. The primary locations for configuration, data, and application files are as follows:

• Application Source: /opt/HunyuanVideo
• Python Virtual Environment: /opt/HunyuanVideo/venv
• Model Checkpoints: /opt/HunyuanVideo/models
• Nginx Configuration Directory: /root/nginx
• Nginx User Configuration: /data/nginx/user_conf.d
• Docker Daemon Configuration: /etc/docker/daemon.json
• Let's Encrypt Secrets: /etc/letsencrypt (mounted via Docker volume)

Application Installation Process¶

The installation process involves cloning the source code, setting up a Python environment, installing dependencies, and downloading the necessary model weights.

1. System Package Installation: Essential tools such as git, python3, python3-venv, python3-dev, python3-pip, curl, and wget are installed via the apt package manager.
2. Repository Cloning: The HunyuanVideo repository is cloned from https://github.com/Tencent/HunyuanVideo.git to the /opt/HunyuanVideo directory, targeting the main branch.
3. Virtual Environment Setup: A Python virtual environment is created at /opt/HunyuanVideo/venv using the python3 -m venv command.
4. Dependency Installation: Python dependencies listed in /opt/HunyuanVideo/requirements.txt are installed within the virtual environment.
5. Model Download: The huggingface-hub package with CLI support is installed. The model checkpoints are downloaded using the huggingface-cli command to the /opt/HunyuanVideo/models directory, specifically including the hunyuan-video-t2v-720p assets.

Docker Containers and Their Deployment¶

The deployment utilizes Docker containers for the web proxy and SSL management. The NVIDIA Docker runtime is configured to enable GPU acceleration for the application.

• NVIDIA Docker Configuration: The Docker daemon is configured to use the NVIDIA runtime by default. The configuration file /etc/docker/daemon.json is updated with the following content:

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

• Docker Restart: The Docker service is restarted to apply the new runtime configuration.
• Nginx and Certbot Deployment: A Docker Compose setup is used to deploy the Nginx proxy and Certbot for SSL certificate management.
  • The docker compose up -d command is executed from the /root/nginx directory.
  • The compose.yml file defines the nginx service using the jonasal/nginx-certbot:latest image.
  • The service runs in host network mode.
  • Volumes are mounted for nginx_secrets (external) and the user configuration directory /data/nginx/user_conf.d.
  • Environment variables are loaded from /data/nginx/nginx-certbot.env.

Proxy Servers¶

The Nginx proxy server handles incoming traffic and manages SSL certificates via Certbot.

• Image: The proxy uses the jonasal/nginx-certbot:latest Docker image.
• Configuration: Custom server configurations are stored in /data/nginx/user_conf.d.
• Proxy Pass: The Nginx configuration includes a proxy_pass directive that forwards requests to the local application running on http://127.0.0.1:8080.
• SSL Management: Certbot is integrated to automatically obtain and renew SSL certificates. The email address for certificate notifications is configured as [email protected].
• Secrets Storage: SSL certificates and keys are stored in the external Docker volume nginx_secrets, mounted at /etc/letsencrypt inside the container.

Starting, Stopping, and Updating¶

The application and its services are managed through specific commands and Docker operations.

• Application Execution: The HunyuanVideo generation script is executed using the Python interpreter from the virtual environment. The command structure is:

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

• Docker Service Management:
  • To start or restart the proxy services, run docker compose up -d from the /root/nginx directory.
  • To stop the services, run docker compose down from the same directory.
• Docker Daemon Restart: If changes are made to the Docker configuration (e.g., enabling NVIDIA runtime), the Docker service must be restarted using systemctl restart docker.