Dockerfile with healthcheck, Coolify-ready docker-compose, and a published image on GHCR

[luisalrp]

Motivation

The README pitches this as self-hosted meeting notes, and the privacy table is exactly what makes self-hosters want to run it on their own box (a home server, a NAS, a Coolify instance). Today the only install path is uv tool install on the machine you sit at. A container image would let people run the heavy half of the pipeline — process, search, the pyannote diarization stack — on a server, while recording stays on the laptop where the microphone lives.

What I'm asking for

1. A Dockerfile

• Multi-stage: build with uv, run on python:3.11-slim with ffmpeg installed.
• Two flavors (build arg or two targets): base, and diarize with the [diarize] extra (torch is heavy; keep it opt-in like pyproject.toml already does).
• Non-root user, HCW_HOME=/data as the single volume.
• HEALTHCHECK that actually means something for a CLI image: a lightweight check that config loads and the Helmcode API is reachable — essentially a quiet, non-interactive subset of hcw doctor (exit 0/1, no device checks, since there's no audio hardware in the container). If that needs a hcw doctor --quiet --no-audio flag, that flag is part of this issue.

2. A docker-compose.yml with the Coolify magic

Coolify deploys a compose file one-click and auto-generates its magic variables, so:

services:
  hcw:
    image: ghcr.io/helmcode/helmcode-whisper:latest
    volumes:
      - hcw-data:/data
    environment:
      - HELMCODE_API_KEY=${HELMCODE_API_KEY}
      - HELMCODE_BASE_URL=${HELMCODE_BASE_URL:-https://api.helmcode.com/v1}
      - HF_TOKEN=${HF_TOKEN}
      - HCW_HOME=/data
    healthcheck:
      test: ["CMD", "hcw", "doctor", "--quiet", "--no-audio"]
      interval: 60s
      timeout: 10s
      retries: 3
volumes:
  hcw-data:

With the volume named and HCW_HOME fixed, the workflow for a self-hoster becomes: rsync a recorded meeting folder into the volume (or mount a synced folder), then docker compose exec hcw hcw process / hcw search "...". Documented in the README under a short "Docker / Coolify" section.

3. Published image on GHCR + GitHub Releases

A compose file pointing at build: . still makes the self-hoster clone the repo. The one-click story needs a published image:

• A GitHub Actions workflow (there's already .github/workflows/) that builds and pushes to ghcr.io/helmcode/helmcode-whisper on every tag:
  • Tags: latest, X.Y.Z, and X.Y.Z-diarize for the heavy flavor.
  • Multi-arch (linux/amd64 + linux/arm64 — half the self-hoster fleet is a Raspberry Pi or an ARM VPS).
• Cut a GitHub Release per tag (auto-generated notes are fine) so v0.1.0 exists as a citable artifact and the image tags have something to point back to.
• The compose file above references the GHCR image, not build: ..

4. The open question this surfaces

For Coolify to keep the container green, something must stay running. Options, cheapest first:

1. A no-op keepalive (sleep infinity) + exec for commands — works today, zero new code.
2. A hcw watch mode that polls HCW_HOME for new meeting folders and runs process on them — this is what actually makes the container useful unattended, and --progress-json (examples/02) shows the pipeline was already designed to be driven programmatically.

I'd scope this issue to (1) plus the Dockerfile/compose/healthcheck/publishing, and file hcw watch separately if there's interest.

Out of scope

• hcw record in a container. Mic + system-audio capture belongs on the host by design; the README's privacy table stays true.
• hcw watch daemon mode (separate issue if there's interest).