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 all installation steps.
Hardware Requirement: NVIDIA GPU with appropriate drivers and CUDA support is necessary for video generation.
Network Ports:
Port 80: Used by Nginx/Certbot for SSL certificate validation.
Port 443: External HTTPS access to the application.

FQDN of the final panel on the hostkey.in domain¶

The application is accessible via a specific subdomain template:

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

File and Directory Structure¶

The application uses the following directory structure for configuration, data, and source files:

/opt/HunyuanVideo: Main application directory containing the source code, virtual environment, and model checkpoints.
/root/nginx: Contains the Docker Compose configuration for the Nginx reverse proxy.
/data/nginx/user_conf.d: Stores Nginx user configuration files.
/data/nginx/nginx-certbot.env: Environment file for Certbot container settings.

Application Installation Process¶

The installation process involves several stages to prepare the environment, install dependencies, and download large model files:

System Preparation: The system is updated, and essential packages such as git, python3, curl, and wget are installed.
NVIDIA Driver and CUDA Setup:
NVIDIA Container Toolkit is configured to allow Docker containers to access the GPU.
CUDA toolkit and drivers are installed via the official NVIDIA repositories.
Source Code Acquisition: The HunyuanVideo repository is cloned from GitHub into /opt/HunyuanVideo.
Python Environment Setup:
A Python virtual environment (venv) is created within the application directory.
PyTorch (version 2.6.0 with CUDA 12.4 support) and other required dependencies are installed via pip.
Model Download and Preprocessing:
Large model checkpoints for HunyuanVideo are downloaded using the huggingface-cli.
CLIP text encoder weights (OpenAI) and LLaVA MLLM weights are downloaded.
A preprocessing script is executed to convert the LLaVA models into a compatible format for the text encoder.

Access Rights and Security¶

Firewall: Ensure that ports 80 and 443 are open to allow web traffic and SSL certificate renewal.
User Permissions: Most application files in /opt/HunyuanVideo are managed under the root user or specific service accounts created during installation.
Docker Security: The NVIDIA Container Toolkit is configured as the default runtime for Docker to ensure secure GPU access.

Docker Containers and Their Deployment¶

The deployment utilizes a reverse proxy container to handle SSL termination via Certbot.

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

Custom Scripts and Additional Setup¶

Several automated actions are performed during the setup:

Environment Configuration: The .bashrc file is updated with PATH and LD_LIBRARY_PATH to ensure CUDA commands are available in the shell.
Kernel Module Management: The nouveau driver is removed, and NVIDIA drivers are initialized.
Text Encoder Preprocessing: A custom Python script (preprocess_text_encoder_tokenizer_utils.py) is run within the virtual environment to prepare the LLaVA model for use as a text encoder.
Verification: A test generation command (sample_video.py) is executed at the end of the installation to verify that the GPU and models are functioning correctly.

Application Update Instructions¶

To update the application, follow these steps:

Navigate to the application directory: cd /opt/HunyuanVideo.
Pull the latest changes from the repository: git pull origin main.
Activate the virtual environment: source venv/bin/activate.
Update Python dependencies: pip install -r requirements.txt.

Location of Configuration Files and Data¶

Application Source: /opt/HunyuanVideo
Model Checkpoints: /opt/HunyuanVideo/ckpts
Nginx Configurations: /data/nginx/user_conf.d
SSL Certificates: Managed via the nginx_secrets Docker volume.

Available Ports for Connection¶

HTTPS (Secure): Port 443 (via Nginx proxy).

Starting and Stopping the Application¶

The application logic is managed through Python scripts within a virtual environment, while the web access is managed by Docker.

To manage the Proxy:
Navigate to /root/nginx.
Use docker compose up -d to start or docker compose down to stop the proxy service.

Manual Execution: The application can be run manually via:

source /opt/HunyuanVideo/venv/bin/activate
python /opt/HunyuanVideo/sample_video.py --prompt "Your prompt here"

Proxy Servers¶

The system uses an Nginx container with Certbot integration to provide SSL-encrypted access to the application. The Nginx configuration is set up as a reverse proxy, forwarding traffic from port 443 to the local service on port 8080.