Deployment Overview of HunyuanVideo on Server¶

Prerequisites and Basic Requirements¶

To ensure a successful deployment, the server must meet the following requirements:

Operating System: Ubuntu (specifically 22.04 is targeted for HWE kernel support).
Privileges: Root or sudo access is required for package installation and system configuration.
Hardware Requirements: An NVIDIA GPU is required to utilize CUDA acceleration for video generation.
Network/Ports:
Port 443 (HTTPS) must be open for external web access.
Internal application communication occurs on port 8080.

The application is accessible via a specific subdomain template based on your server ID.

Parameter	Value
Prefix	`hvideo`
Domain	`hostkey.in`
Full template	`hvideo{Server_ID_from_Invapi}.hostkey.in`

The deployment utilizes the following directory structure for configuration and data management:

/opt/HunyuanVideo: Main application source code, virtual environment, and model checkpoints.
/root/nginx: Configuration files for the Nginx reverse proxy.
/data/nginx/user_conf.d: User-defined Nginx configuration files.
/data/nginx/nginx-certbot.env: Environment variables for SSL certificate management.

The installation follows a multi-stage process involving system preparation, driver installation, and Python environment setup:

System Preparation: The system is updated, and essential packages (git, python3, curl, wget, etc.) are installed.
NVIDIA Driver & CUDA Setup:
NVIDIA Container Toolkit is installed to allow Docker to utilize the GPU.
CUDA toolkit and drivers are configured via official repositories.
The NVIDIA runtime is set as the default for Docker.
Source Code Acquisition: The HunyuanVideo repository is cloned from GitHub into /opt/HunyuanVideo.
Python Environment Setup:
A Python virtual environment (venv) is created in the application directory.
PyTorch with CUDA 12.4 support is installed via pip.
All required dependencies from requirements.txt are installed.
Model and Checkpoint Acquisition:
The main HunyuanVideo checkpoints are downloaded using huggingface-cli.
CLIP text encoder weights (openai/clip-vit-large-patch14) are downloaded.
LLaVA MLLM components are downloaded for text encoding.
Post-Download Configuration:
A preprocessing script is executed to integrate the LLaVA model into the text encoder directory.
Specific code modifications are applied to ensure certain preprocessing tasks run on the CPU to maintain stability.

Firewall: Only port 443 should be exposed to the public internet for web access.
Permissions: Configuration files in /root/nginx and /data/nginx are owned by root.
Runtime Isolation: The application runs within a controlled Python virtual environment to prevent dependency conflicts with system packages.

The deployment utilizes a Nginx container managed via Docker Compose to handle SSL termination and reverse proxying.

Container Name	Image	Ports	Volumes	Environment Variables	Restart Policy
`nginx`	`jonasal/nginx-certbot:latest`	`443/tcp` (Host)	`- nginx_secrets:/etc/letsencrypt` `- /data/nginx/user_conf.d:/etc/nginx/user_conf.d`	`[email protected]`	`unless-stopped`

The following actions are performed during the initial setup to prepare the environment:

CUDA Environment Configuration: The script adds CUDA paths (PATH and LD_LIBRARY_PATH) to the system profile to ensure nvcc is available in the shell.
NVIDIA Runtime Initialization: The nouveau kernel module is removed, and the NVIDIA driver is initialized to enable GPU acceleration.
Text Encoder Preprocessing: A custom Python command is executed: python hyvideo/utils/preprocess_text_encoder_tokenizer_utils.py --input_dir ckpts/llava-llama-3-8b-v1_1-transformers --output_dir ckpts/text_encoder This script prepares the LLM weights for use within the HunyuanVideo pipeline.

To update the main application, follow these steps:

Port	Service	Access Type
`443`	HTTPS (Nginx Proxy)	External
`8080`	Application Backend	Internal (Localhost only)