Deployment Overview of Hallo3 on Server¶

Prerequisites and Basic Requirements¶

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

Operating System: Ubuntu 22.04 (recommended).
Privileges: Root or sudo access is required for package installation and system configuration.
Hardware Acceleration: NVIDIA GPU with compatible drivers is required for CUDA support.
Network Ports:
443/TCP: External HTTPS access via Nginx proxy.
7860/TCP: Internal application port (Gradio).

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

The application is accessible via a specific subdomain template on the hostkey.in domain.

Parameter	Value
Prefix	`hallo`
Domain	`hostkey.in`
Full template	`hallo{Server_ID}.hostkey.in`

File and Directory Structure¶

The application utilizes several specific directories for configuration, source code, and data storage:

/opt/hallo3: Main application directory containing the repository and pretrained models.
/opt/miniconda3: Installation directory for the Miniconda environment.
/root/nginx: Configuration directory for the Nginx reverse proxy.
/data/nginx/user_conf.d: Directory containing Nginx virtual host configurations.
/data/nginx/nginx-certbot.env: Environment file for Certbot/Nginx configuration.

Application Installation Process¶

The installation of Hallo3 involves a multi-stage process including system preparation, environment setup, and model downloading:

System Preparation: The system is updated, and essential build tools like gcc are installed.
NVIDIA Driver and CUDA Setup:
NVIDIA utilities (nvidia-utils-550-server) are installed.
The CUDA repository keyring is added to the system.
The CUDA toolkit is installed to enable GPU acceleration.
Miniconda Installation: Miniconda is installed in /opt/miniconda3 to manage isolated Python environments.
Repository Deployment: The Hallo3 source code is cloned from GitHub into /opt/hallo3.
Environment Configuration:
A dedicated Conda environment named hallo is created using Python 3.10.
Required Python dependencies are installed via pip, including gradio and huggingface-hub.
Dependency Installation: System-level multimedia libraries, specifically ffmpeg, are installed.
Model Acquisition: Pretrained models from the fudan-generative-ai/hallo3 Hugging Face repository are downloaded directly into /opt/hallo3/pretrained_models.

Access Rights and Security¶

Firewall: Only port 443 is exposed to the external network via the Nginx proxy.
Internal Networking: The application runs on port 7860, which is restricted to local traffic through the reverse proxy.
User Permissions: Directories such as /root/nginx and /opt/hallo3 are managed with specific ownership (root) and permissions (0755 or 0644).

Docker Containers and Their Deployment¶

The deployment utilizes a Docker container to manage SSL certificates and reverse proxying.

Nginx Proxy Container

Image: jonasal/nginx-certbot:latest
Ports: Uses host network mode (maps directly to host ports).
Volumes:
nginx_secrets:/etc/letsencrypt: For SSL certificate storage.
/data/nginx/user_conf.d:/etc/nginx/user_conf.d: For Nginx configuration files.
Environment Variables:
[email protected]
Restart Policy: unless-stopped

Custom Scripts and Additional Setup¶

The deployment performs several automated setup actions:

CUDA Environment Configuration: The installation script appends the CUDA binary paths to the system .bashrc file, specifically updating PATH and LD_LIBRARY_PATH.
NVIDIA Driver Initialization: The process includes removing the nouveau driver to allow the NVIDIA proprietary drivers to load.
Docker/NVIDIA Integration: If Docker is present, nvidia-docker2 is installed to enable GPU passthrough for containers.

Application Update Instructions¶

To update the Hallo3 application, follow these steps:

Navigate to the application directory:
```
cd /opt/hallo3
```
Pull the latest changes from the repository:
```
git pull origin main
```

Restart the Python service (manually re-running the execution command):

source /opt/miniconda3/etc/profile.d/conda.sh
conda activate hallo
python hallo3/app.py

Location of Configuration Files and Data¶

Component	Path
Nginx Compose File	`/root/nginx/compose.yml`
Nginx User Configs	`/data/nginx/user_conf.d/`
Application Source	`/opt/hallo3`
Pretrained Models	`/opt/hallo3/pretrained_models`

Available Ports for Connection¶

External Access: 443 (HTTPS)
Internal Service: 7860 (Localhost only)

Starting and Stopping the Application¶

Nginx Proxy Service¶

To manage the proxy service:

cd /root/nginx
docker compose up -d # Start
docker compose down # Stop

Hallo3 Application¶

The application is managed as a background process. To stop it, identify the process using python hallo3/app.py and terminate it via kill. To start it, execute:

source /opt/miniconda3/etc/profile.d/conda.sh
conda activate hallo
python /opt/hallo3/hallo3/app.py &