From 5d34fa1ca61db4cbf2d07b64686018fc08257c33 Mon Sep 17 00:00:00 2001
From: Travis Herbranson <tjherbranson@gmail.com>
Date: Thu, 30 Apr 2026 18:54:47 -0400
Subject: [PATCH] =?UTF-8?q?Hunyuan3D-2=20Docker=20deployment=20=E2=80=94?=
 =?UTF-8?q?=20mini-turbo=20variant,=20low=20VRAM=20mode,=20PBR=20textures?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md          | 36 ++++++++++++++++++++++++++++++++
 docker/Dockerfile  | 52 ++++++++++++++++++++++++++++++++++++++++++++++
 docker/compose.yml | 32 ++++++++++++++++++++++++++++
 3 files changed, 120 insertions(+)
 create mode 100644 README.md
 create mode 100644 docker/Dockerfile
 create mode 100644 docker/compose.yml

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dd280c5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,36 @@
+# Hunyuan3D-2 + Sunnie Animation Pipeline
+
+Self-hosted Hunyuan3D-2 (mini-turbo variant) for generating a 3D Sunnie
+mesh from a reference image, then rigging and animating in Blender via
+Mixamo.
+
+## Quick Start
+
+```bash
+# Clone the model repo
+git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.git
+
+# Build and run
+cd docker
+docker compose build
+docker compose up
+
+# Gradio UI at http://localhost:8080
+```
+
+## Project Structure
+
+```
+hunyuan3d-sunnie/
+  Hunyuan3D-2/          # cloned repo (git submodule or manual clone)
+  docker/
+    Dockerfile           # custom build with CUDA 12.4
+    compose.yml          # GPU-enabled compose with model volume
+    outputs/             # generated meshes land here
+```
+
+## Notes
+
+- First run downloads model weights (~several GB) to the named volume
+- Uses mini-turbo variant with --low_vram_mode for RTX 3080 (10GB VRAM)
+- Outputs .glb with PBR textures for Blender import
diff --git a/docker/Dockerfile b/docker/Dockerfile
new file mode 100644
index 0000000..99d6a35
--- /dev/null
+++ b/docker/Dockerfile
@@ -0,0 +1,52 @@
+# Hunyuan3D-2 — image to 3D mesh with PBR textures
+# Community Dockerfile based on repo issues #125, #122
+# Target: RTX 3080 (10GB VRAM) with mini-turbo variant
+FROM nvidia/cuda:12.4.0-devel-ubuntu22.04
+
+LABEL name="hunyuan3d-2" maintainer="herby"
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# System dependencies
+RUN apt-get update && apt-get install -y \
+    git wget curl vim \
+    build-essential cmake \
+    python3 python3-pip python3-dev \
+    libgl1-mesa-glx libglib2.0-0 libsm6 libxrender1 libxext6 \
+    libegl1-mesa-dev libgles2-mesa-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set python3 as default
+RUN ln -sf /usr/bin/python3 /usr/bin/python
+
+WORKDIR /workspace
+
+# Copy repo contents
+COPY . /workspace/Hunyuan3D-2
+WORKDIR /workspace/Hunyuan3D-2
+
+# Install PyTorch with CUDA 12.4 support
+RUN pip install --no-cache-dir \
+    torch torchvision torchaudio \
+    --index-url https://download.pytorch.org/whl/cu124
+
+# Install project requirements
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Install additional deps that may be missing from upstream requirements
+RUN pip install --no-cache-dir \
+    gradio \
+    onnxruntime \
+    flash-attn --no-build-isolation || true
+
+# Install custom ops if available
+RUN cd /workspace/Hunyuan3D-2 && \
+    pip install -e . || true
+
+# Model cache directory
+VOLUME /root/.cache/hy3dgen
+
+EXPOSE 8080
+
+# Default command — overridden by compose.yml command
+CMD ["python3", "gradio_app.py", "--host", "0.0.0.0", "--port", "8080"]
diff --git a/docker/compose.yml b/docker/compose.yml
new file mode 100644
index 0000000..87c9fbd
--- /dev/null
+++ b/docker/compose.yml
@@ -0,0 +1,32 @@
+services:
+  hunyuan3d:
+    build:
+      context: ../Hunyuan3D-2
+      dockerfile: ../docker/Dockerfile
+    image: hunyuan3d-2:local
+    container_name: hunyuan3d
+    ports:
+      - "8080:8080"
+    volumes:
+      - hunyuan3d-models:/root/.cache/hy3dgen
+      - ./outputs:/workspace/outputs
+    command: >
+      python3 gradio_app.py
+      --model_path tencent/Hunyuan3D-2mini
+      --subfolder hunyuan3d-dit-v2-mini-turbo
+      --texgen_model_path tencent/Hunyuan3D-2
+      --low_vram_mode
+      --enable_flashvdm
+      --host 0.0.0.0
+      --port 8080
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: all
+              capabilities: [gpu]
+    restart: unless-stopped
+
+volumes:
+  hunyuan3d-models: