Compare commits

..

No commits in common. "92ca7253c79dd4d24dfbc5cc54b7a2e18149aeb6" and "3a8765adceeb1be55f8b2794b0ff0d31a501e5c1" have entirely different histories.

6 changed files with 0 additions and 193 deletions

3
.gitmodules vendored
View File

@ -1,3 +0,0 @@
[submodule "InstantMesh"]
path = InstantMesh
url = https://github.com/TencentARC/InstantMesh.git

View File

@ -1 +0,0 @@
3.12

121
CLAUDE.md
View File

@ -1,121 +0,0 @@
# Claude notes — instamesh-docker
Agent context for this repo. Read before non-trivial changes.
## What this is
Docker wrapper around upstream [TencentARC/InstantMesh](https://github.com/TencentARC/InstantMesh)
for single-image → 3D mesh generation. **Not** a fork of InstantMesh
itself — this repo owns the docker build + compose plus a small set of
patches that fix known upstream build breakage.
## Repo shape
```
instamesh-docker/
InstantMesh/ # UNTRACKED — upstream clone. Operators run
# `git clone https://github.com/TencentARC/InstantMesh.git`
# once before `docker compose build`. Not a submodule.
docker/
Dockerfile # patched (see "Patches applied" below)
compose.yml # GPU compose, named volume for model cache, port 43839
requirements.txt # InstantMesh's pip deps, kept here so the Dockerfile
# can ADD them without changing the upstream tree
main.py, pyproject.toml, uv.lock, .python-version
# leftover uv scaffolding from initial repo init;
# NOT part of the build path. Don't extend these.
README.md
CLAUDE.md
```
`InstantMesh/` is intentionally untracked. Don't add it as a submodule
or vendor it into source control — keep the upstream boundary clean.
## Patches applied (vs. upstream)
The Dockerfile is forked from InstantMesh's docker config with three
deliberate changes — call out any churn around these:
1. **CUDA aligned to 12.1.** Base image is
`nvidia/cuda:12.1.0-runtime-ubuntu22.04`; conda installs `cuda` from
`nvidia/label/cuda-12.1.0`; pip installs `torch==2.1.0 + cu121` and
`xformers==0.0.22.post7`. All four must stay in sync. Don't bump CUDA
without re-pinning all of them.
2. **Duplicate `conda create` removed.** Upstream's Dockerfile created
the conda env twice; the second one nuked the first's pinned
packages. Don't reintroduce.
3. **`onnxruntime` added.** Missing from upstream's `requirements.txt`
(InstantMesh issue #175). Installed as a separate `pip install` step
after the bulk requirements install so it's not silently dropped by
the `|| true` below.
## Intentional `|| true` on the bulk pip install
```dockerfile
RUN pip install --no-cache-dir -r requirements.txt || true
```
This is **on purpose**. The requirements include `nvdiffrast` via a git
URL that needs `--no-build-isolation`, which pip's bulk install won't
do. We let that line fail, then install `nvdiffrast` correctly:
```dockerfile
RUN pip install git+https://github.com/NVlabs/nvdiffrast.git --no-build-isolation
```
Don't "fix" the bulk install by removing `|| true` — the build will
hard-fail on nvdiffrast.
## Hardware contract
- **NVIDIA GPU required**, exposed through Docker via the nvidia
runtime. InstantMesh wants **≥ 12 GB VRAM** comfortably; smaller cards
may OOM during inference.
- **CUDA 12.1** — see patch #1 above.
## Build is slow + brittle
Expect a 15+ minute first build. Conda + nvdiffrast compilation +
PyTorch wheels add up. Triggers that re-run the slow layers:
- Editing `docker/requirements.txt` invalidates the conda install layer.
- Editing the Dockerfile's `apt-get install` line redoes the whole
thing from a fresh base image.
Lean on Docker's layer cache; don't restructure for "cleanliness"
without measuring the rebuild cost.
## Compose
```yaml
ports:
- "43839:43839" # Gradio app, host-published
volumes:
- instantmesh-models:/workspace/models # weights cache (named volume)
```
No host-network mode, no bind mounts for code (the upstream tree is
COPYed at build time). If you need to iterate on InstantMesh source,
edit `InstantMesh/` locally and rebuild — there's no dev-mode wiring.
## Where outputs go
InstantMesh's Gradio app writes generated meshes inside the container
(under `/workspace/instantmesh/`). There's **no bind mount** for
outputs in `compose.yml` — operator downloads results from the Gradio
UI. If you find yourself wanting to bind-mount an outputs dir, mirror
`hunyuan3d-sunnie/docker/outputs/`.
## Don't-touch zones
- The CUDA 12.1 pins (base image / conda label / PyTorch wheel index /
xformers wheel) — load-bearing as a set.
- The `|| true` on bulk requirements install — required for nvdiffrast.
- The `onnxruntime` separate install line — load-bearing per upstream #175.
- The untracked `InstantMesh/` directory — let operators reclone.
## Bigger picture
Personal/one-off project, GPU-only. Runs on the dev tower; not part of
the homelab production stack. Sibling project `hunyuan3d-sunnie/` uses
a different model (Hunyuan3D-2) for the same general shape of problem
on a 10 GB card — pick that one if VRAM is tight.

@ -1 +0,0 @@
Subproject commit 08822c52fdc399b93ea00e4fa9e596344ed52ccc

View File

@ -1,59 +0,0 @@
# instamesh-docker
Docker wrapper around [TencentARC/InstantMesh](https://github.com/TencentARC/InstantMesh)
for single-image → 3D mesh generation. Patches upstream's docker setup to
fix a couple of known build issues (missing `onnxruntime`, duplicate
conda env create) and pins CUDA to 12.1 to match the InstantMesh
PyTorch / xformers wheels.
## Requirements
- NVIDIA GPU with CUDA 12.1 support and ≥ 12 GB VRAM (InstantMesh is
not VRAM-friendly).
- Docker + the NVIDIA Container Toolkit (`nvidia` runtime exposed to
compose).
- Disk: several GB for the conda env + model weights.
- Network egress on first build to pull miniconda, PyTorch wheels, and
the nvdiffrast / InstantMesh dependencies (long build — 15+ minutes
is normal).
## Quick start
```bash
# Clone the upstream model repo into this directory (the Dockerfile
# COPYs it via the build context; not a git submodule). Operator-managed;
# not committed.
git clone https://github.com/TencentARC/InstantMesh.git
# Build and run
cd docker
docker compose build
docker compose up
# Gradio UI at http://localhost:43839
```
## Project structure
```
instamesh-docker/
InstantMesh/ # cloned upstream — operator-managed, not committed
docker/
Dockerfile # patched build (CUDA 12.1, onnxruntime fix)
compose.yml # GPU compose, named volume for model cache
requirements.txt # Python deps installed inside the conda env
README.md
CLAUDE.md
```
## Notes
- First run downloads model weights into the `instantmesh-models`
named volume (mounted at `/workspace/models`). Several GB.
- The build uses miniconda inside the container with a `python=3.10`
env named `instantmesh` — not the host's Python. The repo-root
`pyproject.toml` / `uv.lock` / `.python-version` are leftover uv
scaffolding and are not part of the build path.
- See `CLAUDE.md` for the agent-facing gotchas: the patched bits, the
intentional `|| true` on the bulk requirements install, and the CUDA
pin reasoning.

8
uv.lock generated
View File

@ -1,8 +0,0 @@
version = 1
revision = 3
requires-python = ">=3.12"
[[package]]
name = "instamesh-docker"
version = "0.1.0"
source = { virtual = "." }