Skip to content
OpenASR

Docker

Each OpenASR core release publishes runtime images to Docker Hub. The images ship the CLI binary plus the signed model-registry metadata only — model weights are not baked in. Install packs at runtime into a volume mounted at /data (OPENASR_HOME).

Images are assembled from the same GitHub Release archives as the prebuilt CLI (no second cargo build inside Docker), so the container binary matches the release tag bit-for-bit.

Images and tags

Section titled “Images and tags”
Tag patternContentsPlatforms
latest, <version>, sha-<short>CPU binary (linux-x86_64 / linux-arm64)linux/amd64, linux/arm64
cuda-latest, cuda-<version>, cuda-sha-<short>CUDA binary (linux-x86_64-cuda)linux/amd64 only

Replace <version> with a published core release (see GitHub Releases). Prefer a pinned version tag in production; move latest / cuda-latest only when you intend to track the newest core release.

Not published as images (use the GitHub Release tarball on the host instead): Vulkan, ROCm, and musl builds. Those variants need host drivers or a different libc story than the slim Debian/CUDA runtime bases used here.

Quick start (CPU)

Section titled “Quick start (CPU)”
bash
docker pull quintinshaw/openasr:latest


docker run --rm -d --name openasr \
  -p 8080:8080 \
  -v openasr-data:/data \
  quintinshaw/openasr:latest

The default command is serve --addr 0.0.0.0:8080. Health check:

bash
curl -s http://127.0.0.1:8080/health

NVIDIA GPU (CUDA)

Section titled “NVIDIA GPU (CUDA)”

Requires the NVIDIA Container Toolkit on the host, a driver compatible with CUDA 13.2, and a GPU with compute capability sm_75 (Turing) or newer.

bash
docker pull quintinshaw/openasr:cuda-latest


docker run --rm -d --name openasr-cuda \
  --gpus all \
  -p 8080:8080 \
  -v openasr-data:/data \
  quintinshaw/openasr:cuda-latest

The CUDA image is fail-closed on GPU visibility: if no GPU device shows up inside the container (openasr doctor reports no (gpu, …) device), the entrypoint exits instead of silently serving on CPU. That usually means missing --gpus, a missing toolkit install, or an incompatible host driver.

Install a model (required before transcription)

Section titled “Install a model (required before transcription)”

The HTTP server never downloads a model to satisfy a request — same contract as a bare-metal openasr serve. Pull packs explicitly into the data volume:

bash
# interactive container already running as "openasr"
docker exec -it openasr openasr pull whisper-small --yes


# or one-shot against the same named volume
docker run --rm -v openasr-data:/data quintinshaw/openasr:latest \
  pull whisper-small --yes

--yes is required in non-interactive environments (no TTY). List what landed:

bash
docker exec openasr openasr list

Then call the OpenAI-compatible endpoint:

bash
curl -s http://127.0.0.1:8080/v1/audio/transcriptions \
  -F [email protected] \
  -F model=whisper-small \
  -F response_format=json

Full route table, auth modes, and TLS notes: Server API.

Persist data

Section titled “Persist data”
Path inside containerRole
/data (OPENASR_HOME)Installed .oasr packs, config, history, speaker enrollments

Always mount a volume (or bind mount) on /data. Without it, every new container starts empty and you re-download models.

One-shot CLI inside the image

Section titled “One-shot CLI inside the image”

The entrypoint is the openasr binary, so any CLI subcommand works:

bash
docker run --rm -v openasr-data:/data -v "$PWD:/work" -w /work \
  quintinshaw/openasr:latest \
  transcribe audio.wav --model whisper-small --offline

--offline fails closed if the pack is missing — pull it first as above. Live microphone / system-audio capture is a host concern; containers are aimed at file transcription and the local HTTP API.

Environment and networking

Section titled “Environment and networking”
Variable / settingDefault in imageNotes
OPENASR_HOME/dataKeep the volume here
OPENASR_ALLOW_INSECURE_NON_LOOPBACK1Lets serve bind 0.0.0.0 inside the container. Exposure is still controlled by your -p / mesh / firewall. Put TLS (or a TLS-terminating proxy) in front on untrusted networks.
Published port8080Map with -p 8080:8080

For remote access patterns (pairing auth, self-signed TLS), prefer configuring openasr serve flags via docker run … <flags> or see the Server API guide — the image does not weaken those fail-closed defaults beyond the loopback bind opt-in above.

Compose (local source build)

Section titled “Compose (local source build)”

The repository compose.yaml builds from source for development (Dockerfile / Dockerfile.cuda). Published Hub images are the release path; compose remains the smoke / hack-on-main path:

bash
git clone --recurse-submodules https://github.com/QuintinShaw/openasr.git
cd openasr
docker compose up openasr                 # CPU, source build
docker compose --profile gpu up openasr-cuda

What ships automatically

Section titled “What ships automatically”

On every core GitHub Release, CI assembles and pushes the CPU multi-arch and CUDA tags above to quintinshaw/openasr when the DOCKER_PAT secret is configured. A failed Docker job does not roll back the GitHub Release assets. Manual rebuild:

bash
gh workflow run docker-release.yml \
  -R QuintinShaw/openasr \
  -f version=<version> -f push=true -f mark_latest=true -f variants=all
Section titled “Related”