2776f1df7a
These were the remaining `uv init` residue alongside the already-removed main.py stub — not part of the build/deploy path. Also drops the now-stale 'leftover uv-init artifacts' note from CLAUDE.md since the files are gone.
119 lines
4.5 KiB
Markdown
119 lines
4.5 KiB
Markdown
# 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
|
|
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.
|