fix(fish): runtime deps, missing bind-mounts, longer warmup window

[mabry1985]

Summary

Three Fish-sidecar issues that each crashed a cold rebuild, bundled because the fix is a single compose + Dockerfile pass.

Root causes

Issue	File	Fix
Failed to find C compiler / CalledProcessError ... cuda_utils.c on first synth	Dockerfile.fish	Add build-essential + python3-dev. torch.compile's Inductor backend shells out to gcc at synth time to build CUDA kernels as Python extension modules — needs both a C toolchain and Python.h.
/app/.venv/bin/python: No such file or directory at container start	docker-compose.yml	Bind-mount ../fish-speech/.venv → /app/.venv read-only. fish-speech/.dockerignore excludes .venv/ (despite Dockerfile comments claiming COPY . includes it). Same story for checkpoints/ — too large to bake into the image.
Healthcheck restart loop while torch.compile was still running	docker-compose.yml	start_period: 180s → 600s, retries: 3 → 5. Cold compile on Blackwell is 3-5 min; the old threshold made Docker mark unhealthy and bounce the container.

Docs

• docs/tutorials/docker-compose.md — documents all three gotchas so the next operator doesn't have to rediscover them.
• docs/reference/tts-backends.md — separately notes that Fish's native POST /v1/tts isn't OpenAI-compat; an external shim in protoLabsAI/lab wraps /v1/audio/speech → Fish for LiteLLM / OpenAI SDK clients.

Test plan

• Cold rebuild: docker compose build --no-cache fish-speech && docker compose up -d fish-speech — container stays up through the compile, serves /v1/health once warm.
• Verify /v1/references/list returns populated after startup (regression check — the references dir is unaffected by this PR, but worth spot-checking after any compose change).
• docker compose logs -f fish-speech during first boot — no gcc / python.h / cuda_utils.c errors, no .venv/checkpoints ENOENT, healthcheck crosses over before the start_period expires.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Added guide for exposing Fish TTS sidecar via OpenAI-compatible API endpoint.
  • Enhanced Docker Compose tutorial with volume mount requirements and first-boot troubleshooting guidance.

• Chores

  • Optimized Docker configuration for improved container health checks and startup behavior.

[coderabbitai]

Walkthrough

Updates Docker infrastructure and documentation for Fish TTS to support runtime CUDA kernel compilation. Adds Python development headers and C/C++ toolchain to the Dockerfile, configures volume mounts for the virtual environment and checkpoints in docker-compose, and documents deployment requirements and OpenAI-compatible interface.

Changes

Cohort / File(s)	Summary
Docker Infrastructure Dockerfile.fish, docker-compose.yml	Added python3-dev and build-essential packages to enable torch.compile CUDA kernel compilation. Configured read-only volume mounts for .venv and checkpoints directories. Extended healthcheck startup grace period to 600 seconds and retry count to 5 for cold-start/compilation tolerance.
Documentation docs/reference/tts-backends.md, docs/tutorials/docker-compose.md	Documented OpenAI-compatible /v1/audio/speech endpoint via external shim with wav and pcm/mp3 support. Added Docker Compose deployment guidance covering volume mount requirements, healthcheck timing configuration, and explanation of why build dependencies are necessary for Inductor CUDA extensions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the three main fixes: runtime dependencies (build-essential, python3-dev), missing bind-mounts for .venv and checkpoints, and extended healthcheck warmup window. It directly corresponds to the core changes across Dockerfile, docker-compose.yml, and supporting docs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/fish-sidecar-runtime

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docker-compose.yml`:
- Around line 24-27: The docker-compose binds are hardcoded to /home/ava/...
which breaks on other machines; update the two bind-mount entries that match
"/home/ava/dev/fish-speech/.venv:/app/.venv:ro" and
"/home/ava/dev/fish-speech/checkpoints:/app/checkpoints:ro" to use a
parameterized variable (e.g., ${PROJECT_ROOT} or ${PWD}) sourced from an .env or
environment so the host checkout root is configurable; ensure the .env key is
documented or defaulted and that docker-compose references that variable for
both the .venv and checkpoints mounts.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 42fd7d25-4de0-400c-999b-1992482a48a4

📥 Commits

Reviewing files that changed from the base of the PR and between 09fc076 and 04747fe.

📒 Files selected for processing (4)

• Dockerfile.fish
• docker-compose.yml
• docs/reference/tts-backends.md
• docs/tutorials/docker-compose.md

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

Hardcoded host bind-mount paths will break startup outside one developer machine.

Line 26 and Line 27 hardcode /home/ava/.... On other hosts this typically mounts the wrong/nonexistent source and the container fails again with missing /app/.venv/bin/python or checkpoints. Please parameterize the checkout root.

🔧 Suggested fix

     volumes:
       - ${FISH_REFERENCES_DIR:-/mnt/data/fish-references}:/app/references
-      - /home/ava/dev/fish-speech/.venv:/app/.venv:ro
-      - /home/ava/dev/fish-speech/checkpoints:/app/checkpoints:ro
+      - ${FISH_SPEECH_DIR:-../fish-speech}/.venv:/app/.venv:ro
+      - ${FISH_SPEECH_DIR:-../fish-speech}/checkpoints:/app/checkpoints:ro

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	# .dockerignore excludes .venv/, so bind-mount from the host checkout.
	# Dockerfile comment claims COPY . includes them, but it doesn't.
	- /home/ava/dev/fish-speech/.venv:/app/.venv:ro
	- /home/ava/dev/fish-speech/checkpoints:/app/checkpoints:ro
	# .dockerignore excludes .venv/, so bind-mount from the host checkout.
	# Dockerfile comment claims COPY . includes them, but it doesn't.
	- ${FISH_SPEECH_DIR:-../fish-speech}/.venv:/app/.venv:ro
	- ${FISH_SPEECH_DIR:-../fish-speech}/checkpoints:/app/checkpoints:ro

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docker-compose.yml` around lines 24 - 27, The docker-compose binds are
hardcoded to /home/ava/... which breaks on other machines; update the two
bind-mount entries that match "/home/ava/dev/fish-speech/.venv:/app/.venv:ro"
and "/home/ava/dev/fish-speech/checkpoints:/app/checkpoints:ro" to use a
parameterized variable (e.g., ${PROJECT_ROOT} or ${PWD}) sourced from an .env or
environment so the host checkout root is configurable; ensure the .env key is
documented or defaulted and that docker-compose references that variable for
both the .venv and checkpoints mounts.