Deployment Overview of HunyuanVideo on Server¶

Prerequisites and Basic Requirements¶

The deployment of HunyuanVideo requires a Linux server running Ubuntu 22.04. The following requirements must be met before proceeding with the installation:

Operating System: Ubuntu 22.04 (with HWE kernel support recommended).
Privileges: Root access or sudo privileges are required to install system packages, configure Docker, and modify network settings.
Domain and Zone: The application is configured for the hostkey.in zone with the prefix hvideo.
GPU Requirements: NVIDIA GPU with CUDA support is mandatory. The system must have the NVIDIA drivers and the nvidia-docker2 runtime installed.
Network Ports:
- Port 8080: Internal application port.
- Port 443: External HTTPS port for secure access via the proxy.

FQDN of the Final Panel¶

Once deployed, the application is accessible via the following Fully Qualified Domain Name (FQDN):

hvideo<Server ID>.hostkey.in:443

Note: Replace <Server ID> with the specific identifier assigned to your server instance.

File and Directory Structure¶

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

Application Source: /opt/HunyuanVideo
- Contains the cloned repository from Tencent.
- Virtual Environment: /opt/HunyuanVideo/venv
- Models: /opt/HunyuanVideo/models (Stores downloaded checkpoints like hunyuan-video-t2v-720p).
Nginx and Proxy Configuration:
- Directory: /root/nginx
- Compose File: /root/nginx/compose.yml
- User Configuration: /data/nginx/user_conf.d/hvideo<Server ID>.hostkey.in.conf
- Environment File: /data/nginx/nginx-certbot.env
Docker Configuration:
- Runtime Configuration: /etc/docker/daemon.json
SSL Certificates: Stored within the nginx_secrets Docker volume, mapped to /etc/letsencrypt inside the container.

Application Installation Process¶

The HunyuanVideo application is installed via a native script that clones the source code, sets up a Python environment, and downloads the necessary models. The process includes the following steps:

System Preparation: The system is updated, and the High Availability Kernel for Ubuntu 22.04 is installed if the OS version matches.
CUDA and Driver Installation:
- The CUDA toolkit and NVIDIA drivers are installed based on the Ubuntu release version.
- Environment variables (PATH and LD_LIBRARY_PATH) are added to ~/.bashrc to ensure CUDA binaries are accessible.
- The nouveau kernel module is removed, and NVIDIA modules are initialized.
Docker and NVIDIA Runtime:
- The nvidia-docker2 package is installed.
- The Docker daemon is configured to use the NVIDIA runtime by default via /etc/docker/daemon.json.
- The Docker service is restarted.
Python Environment Setup:
- The repository is cloned from https://github.com/Tencent/HunyuanVideo.git to /opt/HunyuanVideo.
- A Python 3 virtual environment is created at /opt/HunyuanVideo/venv.
- Dependencies listed in requirements.txt are installed within the virtual environment.
Model Download:
- The huggingface-hub CLI is installed.
- Pre-trained checkpoints (specifically hunyuan-video-t2v-720p) are downloaded to /opt/HunyuanVideo/models using huggingface-cli.
Verification:
- A test generation is run using sample_video.py with a sample prompt to verify the setup.

Docker Containers and Their Deployment¶

The application utilizes Docker for the reverse proxy and SSL management. The deployment uses a Docker Compose setup located in /root/nginx.

Container Configuration¶

The following table summarizes the container configuration:

Service Name	Image	Network Mode	Volume Mounts
`nginx`	`jonasal/nginx-certbot:latest`	`host`	`nginx_secrets` (external) mapped to `/etc/letsencrypt` `/data/nginx/user_conf.d` mapped to `/etc/nginx/user_conf.d`

Deployment Command¶

The container is deployed using the following command executed from the /root/nginx directory:

docker compose up -d

The compose.yml file defines the service with the environment variable CERTBOT_EMAIL set to [email protected] and loads additional configuration from /data/nginx/nginx-certbot.env.

Proxy Servers¶

Nginx is used as a reverse proxy to handle HTTPS traffic and SSL certificate management via Certbot.

Proxy Target: Incoming traffic on port 443 is proxied to http://127.0.0.1:8080.
Configuration File: The specific proxy rule is written to /data/nginx/user_conf.d/hvideo<Server ID>.hostkey.in.conf.
Location Block: The configuration inserts the following line after the location / { directive:
```
proxy_pass http://127.0.0.1:8080;
```
SSL Management: Certificates are managed automatically by the nginx-certbot container, which stores secrets in the external volume nginx_secrets.

Databases¶

Based on the provided configuration, no external database services (such as PostgreSQL, MySQL, or MongoDB) are defined or deployed for this application instance. The application relies on local file system storage for models and generation outputs.

Permission Settings¶

File and directory permissions are set as follows during the deployment process:

Nginx Directory:
- Path: /root/nginx
- Owner/Group: root:root
- Mode: 0755
Compose File:
- Path: /root/nginx/compose.yml
- Owner/Group: root:root
- Mode: 0644
Docker Daemon Config:
- Path: /etc/docker/daemon.json
- Mode: 0644

The application runs within the /opt/HunyuanVideo directory, where the virtual environment and model files reside. Execution permissions are handled by the shell scripts and Python interpreter within the virtual environment.

Available Ports for Connection¶

The following ports are utilized by the application and proxy infrastructure:

Port 443: HTTPS traffic for external access via the FQDN.
Port 8080: Internal HTTP port used by the HunyuanVideo application, proxied by Nginx.
Port 80: Required for initial SSL certificate validation by Certbot (implicitly handled by the proxy).

Starting, Stopping, and Updating¶

Management of the application components is handled through standard Docker and Linux service commands.

Managing the Proxy (Nginx/Certbot)¶

Start/Restart:
```
cd /root/nginx
docker compose up -d
```
Stop:
```
cd /root/nginx
docker compose down
```

Update: Pull the latest image and restart:

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

Managing the Docker Daemon¶

If the NVIDIA runtime configuration is modified, restart the Docker service:

sudo systemctl restart docker

Running the Application¶

To execute the video generation script manually (after activating the virtual environment):

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

Note: The application itself does not run as a persistent Docker container in this configuration but is executed via the Python environment on the host system, with web access provided solely by the Nginx proxy forwarding requests to port 8080.