start.sh fails on a fresh host: huggingface_cache bind volume's source dir is never created before 'docker compose up'

[latent-9]

Summary

Following the documented quickstart on a fresh host, ./start.sh fails at docker compose up -d because the huggingface_cache volume is a bind mount whose source directory is never created.

docker-compose.yml (lines 76-81):

huggingface_cache:
  driver: local
  driver_opts:
    type: none
    o: bind
    device: ${HOME}/.cache/huggingface

A local driver volume with o: bind is a mount --bind — Docker does not create the device source path if it's missing (unlike an inline -v src:dst bind, which auto-creates it). start.sh runs docker compose up -d with no mkdir.

Reproduce

On a machine that has never used Hugging Face tooling (so ~/.cache/huggingface doesn't exist yet):

cp .env.example .env   # fill HF_TOKEN
./start.sh

→ docker compose up -d aborts with failed to mount local volume ... /.cache/huggingface: no such file or directory; the engine never starts.

Why it's inconsistent (not just my setup)

The repo's other launch path, run_cluster.sh:141, uses an inline -v "$HOME/.cache/huggingface:/root/.cache/huggingface", which auto-creates the directory. So the cluster path works on a fresh host while the compose path fails.

Fix

Create the directory before compose mounts it — one line in start.sh:

mkdir -p "$HOME/.cache/huggingface"

(Alternatively, use a plain inline bind instead of the driver_opts volume.)

Found by reading the compose file against start.sh / run_cluster.sh; no GPU needed to confirm.