Deployment Overview of Hallo3 on Server¶

Prerequisites and Basic Requirements¶

Operating System: Ubuntu 22.04 (LTS).
Privileges: Root access or a user with sudo privileges.
Domain: The application is deployed under the hostkey.in domain.
Hardware: NVIDIA GPU with drivers and CUDA support.
Ports:
- Internal: 7860 (Application).
- External: 443 (HTTPS).

Final Access URL¶

The application is accessible via the following Fully Qualified Domain Name (FQDN): hallo<Server ID>.hostkey.in:443 (Replace <Server ID> with the actual server identifier).

File and Directory Structure¶

The deployment utilizes the following directory paths for configurations, data, and certificates:

/root/nginx: Directory for the Nginx Docker Compose configuration.
/root/nginx/compose.yml: Docker Compose file for the Nginx reverse proxy and Certbot.
/data/nginx/user_conf.d/: Directory containing custom Nginx configuration files.
/data/nginx/nginx-certbot.env: Environment file for the Nginx container.
/data/nginx/user_conf.d/hallo<Server ID>.hostkey.in.conf: Specific proxy configuration for Hallo3.
/opt/miniconda3: Installation path for Miniconda.
/opt/miniconda3/envs/hallo: Conda environment for the Hallo3 application.
/opt/hallo3: Source code directory for the Hallo3 application.
/opt/hallo3/pretrained_models: Directory storing downloaded Hugging Face models.

Application Installation Process¶

The Hallo3 application is installed using the following sequence:

System Preparation: The system updates are applied, and the Linux Hardware Enablement (HWE) kernel for Ubuntu 22.04 is installed.
CUDA and NVIDIA Drivers:
- The CUDA repository keyring (cuda-keyring_1.1-1_all.deb) is downloaded and installed.
- The cuda-toolkit and nvidia-cuda-toolkit packages are installed via apt.
- Environment variables PATH and LD_LIBRARY_PATH are configured to include CUDA binaries and libraries.
- The nouveau driver is removed, and NVIDIA kernel modules are loaded.
Miniconda Installation:
- The Miniconda installer is downloaded and installed to /opt/miniconda3.
- The system PATH is updated to include the Miniconda binaries.
Application Setup:
- The Hallo3 repository is cloned from GitHub (https://github.com/fudan-generative-vision/hallo3) into /opt/hallo3.
- A new Conda environment named hallo with Python 3.10 is created.
- Dependencies listed in requirements.txt, along with gradio, ffmpeg, and huggingface-hub, are installed within the environment.
Model Download: Pretrained models are downloaded from Hugging Face to the /opt/hallo3/pretrained_models directory using the huggingface-cli.

Docker Containers and Their Deployment¶

The reverse proxy and SSL certificate management are handled by Docker containers defined in a Compose file.

Compose File Location: /root/nginx/compose.yml
Image: jonasal/nginx-certbot:latest
Service Configuration:
- The Nginx service runs with network_mode: host.
- It restarts automatically unless stopped manually (restart: unless-stopped).
- SSL certificates are stored in an external named volume nginx_secrets mapped to /etc/letsencrypt.
- Custom user configurations are mounted from /data/nginx/user_conf.d to /etc/nginx/user_conf.d inside the container.

The container is started using the command:

docker compose up -d

executed from the /root/nginx directory.

Proxy Servers¶

Nginx acts as the reverse proxy to terminate SSL connections and forward traffic to the Hallo3 application.

SSL/TLS: Managed automatically by the nginx-certbot container.
Proxy Configuration:
- Source File: /data/nginx/user_conf.d/hallo<Server ID>.hostkey.in.conf
- Target Address: http://127.0.0.1:7860
- The configuration redirects traffic from the external domain to the internal application port.

Access Rights and Security¶

Directory Permissions:
- /root/nginx: Owned by root with mode 0755.
- /root/nginx/compose.yml: Owned by root with mode 0644.
Firewall: The application is accessed securely via port 443 (HTTPS). Direct access to the internal port 7860 is not exposed to the external network.
User Configuration: The application runs under the context of the user executing the deployment scripts, utilizing the root directory for Docker management.

Available Ports for Connection¶

Port	Protocol	Usage	Status
443	HTTPS	Public access via domain	Open
7860	TCP	Internal application service	Localhost only

Starting, Stopping, and Updating¶

The Hallo3 application is executed as a background process using Python.

Starting the Application: The application is launched by activating the Conda environment and running the entry script:
```
source /opt/miniconda3/etc/profile.d/conda.sh
conda activate hallo
cd /opt/hallo3
python hallo3/app.py
```
Managing Docker Services: To start, stop, or update the Nginx proxy container:
```
cd /root/nginx
docker compose up -d
```