.env.example

# ============================================================================
# VocaGateway — Docker Compose settings
# ============================================================================
#
# Copy this file, then fill in a token:
#
#   umask 077
#   cp .env.example .env
#   printf 'VOCAGATEWAY_TOKEN=%s\n' "$(openssl rand -hex 32)" >> .env
#   docker compose up --detach --build
#
# WHO READS THIS FILE
#   Only `docker compose` (and `just up` / `just down`, which call it). The
#   justfile sets `dotenv-load := false`, so a natively started gateway
#   (`just run`, `uv run vocagateway`) never sees anything in here — it reads
#   its token from ~/.config/vocagateway/token instead.
#
# WHAT ACTUALLY REACHES THE CONTAINER
#   Only the keys compose.yaml names. It lists each one explicitly, so any
#   other VOCAGATEWAY_* variable put in .env is read by Compose, interpolated
#   into nothing, and silently dropped. Section 7 lists the ones people most
#   often expect to work here.
#
# Never commit the populated .env — .gitignore already excludes it.
#
# Sections:
#   1. Required: bearer token
#   2. Where Docker publishes the gateway
#   3. Address the pairing QR gives the phone
#   4. Which image to run, and how it is built
#   5. Gateway behaviour
#   6. Listener inside the container
#   7. Settings that do not belong here


# ============================================================================
# 1. Required: bearer token
# ============================================================================

# Bearer token the phone apps present on every request. At least 32
# characters. Generate one with: openssl rand -hex 32
#
# Compose passes it to the container as a secret mounted at
# /run/secrets/vocagateway_token, never as an environment variable.
#
# Fill this in, or append a second VOCAGATEWAY_TOKEN= line as shown at the top
# of this file — Compose uses the last assignment when a key repeats, so the
# appended value wins over this empty placeholder.
#
# An empty value is NOT caught by `docker compose config` — that check passes
# on the placeholder below. Nothing later tells you the token is missing
# either: the gateway falls back to a secret it generates and never prints, so
# /health/live looks fine while every authenticated request and every phone
# pairing returns 401. Set it before the first `up`.
VOCAGATEWAY_TOKEN=


# ============================================================================
# 2. Where Docker publishes the gateway
# ============================================================================

# Host interface and port Docker publishes the gateway on.
# 127.0.0.1 keeps it on loopback, which is what Tailscale Serve expects. Use
# 0.0.0.0 only for a trusted LAN, with the host firewall up. Never forward this
# port from the public internet.
#
# Ignored when VOCAGATEWAY_NETWORK_MODE=host (section 3) — Compose drops the
# whole port mapping in that mode.
VOCAGATEWAY_PUBLISH_HOST=127.0.0.1
VOCAGATEWAY_PUBLISH_PORT=8765


# ============================================================================
# 3. Address the pairing QR gives the phone
# ============================================================================

# On the default bridge network the container only sees its own private bridge
# IP (172.x), never the host's LAN NIC, so address auto-discovery cannot
# produce a phone-reachable address. One of the two settings in this section
# fixes that. Behind a reverse proxy, VOCAGATEWAY_PUBLIC_URL is mandatory:
# discovery cannot guess a public hostname.

# Names the address the phone should use and puts it ahead of discovery.
# Works everywhere, including Docker Desktop on macOS and Windows.
# Omit the port when TLS terminates on 443, e.g. https://gateway.example.com
#
# One caveat: this feeds the *discovered* candidate list. An address you
# previously picked and saved in the WebUI pairing card wins over it. If the
# card was ever opened before you set this, clear the old entry with **Remove**
# under "Saved addresses", or drop `pairing_url`/`pairing_urls` from
# config.json and restart.
#
# VOCAGATEWAY_PAIRING_URL is an accepted alias, checked second.
#VOCAGATEWAY_PUBLIC_URL=http://192.168.1.20:8765

# The alternative, on Linux Docker Engine only (Docker Desktop does not support
# it): share the host's network namespace so discovery finds the machine's real
# LAN address by itself. This discards the section 2 port mapping entirely and
# binds straight onto the host per VOCAGATEWAY_BIND_HOST/_PORT (section 6), so
# the host firewall becomes the only thing in front of the port — lock it down
# first.
#VOCAGATEWAY_NETWORK_MODE=host


# ============================================================================
# 4. Which image to run, and how it is built
# ============================================================================

# Tag for the `gateway` service. Setting it does not by itself switch Compose
# from building to pulling: `docker compose up --build` still builds locally
# and applies this tag to the result. To actually run a prebuilt
# multi-architecture image:
#
#   docker compose pull
#   docker compose up --detach --no-build
#
# The cuda/vulkan profile services carry fixed tags and ignore this.
#VOCAGATEWAY_IMAGE=ghcr.io/your-user/vocagateway:latest

# Extra cmake flags for the whisper.cpp build, appended after the Dockerfile's
# own, so a flag here overrides the default. Unlike the git-commit build args in
# section 7, this one belongs in .env: it is a property of the machine you build
# for, not of the moment you built.
#
# The two that come up:
#
#   -DCMAKE_CUDA_ARCHITECTURES=89-real
#       Build CUDA kernels for one known GPU (89 = Ada / RTX 40-series) instead
#       of the portable spread ggml picks. Much faster nvcc and a far smaller
#       binary; the image then runs only on that GPU generation.
#
#   -DGGML_BLAS=OFF
#       Drop OpenBLAS from the CPU image. Measured on arm64 this is a ~1.6x
#       slowdown (tiny.en on an 11 s clip: ~2.0 s with BLAS, ~3.2 s without), so
#       BLAS is on by default. If your host is x86 with AVX-512 the balance may
#       differ; there is a timing recipe under "Tuning the whisper.cpp build" in
#       docs/deployment.md.
#
# There is no CPU "native" profile to set here. The image builds every ggml CPU
# micro-architecture variant and loads the best one the host reports at startup.
#VOCAGATEWAY_WHISPER_CMAKE_EXTRA=-DCMAKE_CUDA_ARCHITECTURES=89-real

# How many compile jobs the whisper.cpp build runs at once. Blank is resolved to
# the builder's CPU count. The cuda image is the usual reason to set a lower
# value: nvcc instantiates a great many templates and each job can want most of a
# gigabyte, so a memory-constrained build can be OOM-killed partway through.
# Roughly one job per 2 GB of builder memory. An 8 GB machine normally wants 3.
#VOCAGATEWAY_BUILD_JOBS=3

# Supplementary groups the vulkan profile's container joins so uid 10001 can
# open /dev/dri/renderD128. Without the render group the open fails with EACCES,
# Vulkan finds no device, and whisper.cpp silently falls back to Mesa's software
# rasteriser — slower than the CPU image. The GID differs per distribution (993
# on Ubuntu, 104 on Debian); read your host's with:
#
#   stat -c '%g' /dev/dri/renderD128
#
# Ignored by the default and cuda services.
#VOCAGATEWAY_RENDER_GID=993
#VOCAGATEWAY_VIDEO_GID=44


# ============================================================================
# 5. Gateway behaviour
# ============================================================================

# Pin an engine instead of letting `auto` pick the first runnable one.
# Accepted values: auto, sherpa-onnx, faster-whisper, moonshine, whisper.cpp,
# mlx-audio, whisperkit, vocamac, handy.
#
# The container can only run the first five. The other four need macOS (and
# mlx-audio/vocamac need Apple silicon), and nothing rejects them at startup:
# the gateway comes up, the engine reports unavailable, and /health/ready stays
# 503 with no obvious cause. The `422 invalid_engine` rejection you may have
# read about applies to the WebUI picker and PUT /v1/admin/config, not to this
# variable.
#
# Setting anything other than `auto` also pins the engine process-wide and
# overrides whatever the WebUI engine picker has saved. Leave it at `auto` and
# choose in the WebUI unless you specifically want an environment-level lock.
#VOCAGATEWAY_ENGINE=auto

# How hard whisper.cpp searches while decoding. `quality` keeps the narrowed
# beam search (beam 2, best-of 2); `fast` decodes greedily, which cuts decoder
# work on a CPU-only host and can cost accuracy on accented or noisy audio.
# Temperature fallback stays on either way. Compare word error rate on your own
# recordings before keeping `fast`.
#VOCAGATEWAY_WHISPER_DECODER_PRESET=quality

# How long a failed session's audio is kept so the phone can retry, and whether
# audio is deleted immediately after a successful transcription.
#VOCAGATEWAY_RETENTION_HOURS=24
#VOCAGATEWAY_DELETE_SUCCESSFUL_AUDIO=true

# Serve the Swagger UI at /docs and the schema at /openapi.json, and report the
# image's build commit in /v1/admin/status and the WebUI **Build** row. Off by
# default: the schema and UI are extra surface area, so enable this only for
# local development.
#VOCAGATEWAY_DEBUG=true

# ----------------------------------------------------------------------------
# Transcript cleanup (optional, off by default)
# ----------------------------------------------------------------------------
# A small text model that fixes grammar, punctuation, and casing *after*
# recognition, on the recognised text only. Audio never reaches it. Whenever it
# cannot finish safely you get exactly the transcript you would have got with
# the feature off — it can improve a result, never lose one.
#
# In Compose it needs the opt-in `cleanup` sidecar, because the gateway image
# ships no text model and no llama.cpp runtime:
#
#   VOCAGATEWAY_CLEANUP_MODEL_DIR=$HOME/.local/share/vocagateway/models/cleanup \
#   VOCAGATEWAY_CLEANUP_MODEL_FILE=/models/llama.cpp/Qwen3-0.6B-Q8_0.gguf \
#   VOCAGATEWAY_CLEANUP_ENDPOINT=cleanup:8080 \
#   VOCAGATEWAY_CLEANUP_API_KEY=$(openssl rand -hex 24) \
#   docker compose --profile cleanup up -d
#
# Leaving these unset is not the same as setting them to off: unset means "the
# WebUI's saved choice decides", while a set value locks the toggle in the UI.
#VOCAGATEWAY_CLEANUP_ENABLED=true
#VOCAGATEWAY_CLEANUP_MODE=conservative
#VOCAGATEWAY_CLEANUP_MODEL=cleanup:qwen3-0.6b
#VOCAGATEWAY_CLEANUP_TIMEOUT_SECONDS=5

# Languages cleanup is allowed to run for. Defaults to the selected model's own
# list. These are languages the feature is *offered* for, not ones an
# evaluation has signed off — the WebUI reports the two separately.
#VOCAGATEWAY_CLEANUP_LANGUAGES=en,hi,hinglish_roman

# Address of the sidecar, and the credential the gateway presents to it. Only
# loopback, private ranges, and bare Compose service names are accepted; a
# routable address is refused at startup, because "runs on your gateway" has to
# stay true. A client's bearer token is never forwarded here.
#VOCAGATEWAY_CLEANUP_ENDPOINT=cleanup:8080
#VOCAGATEWAY_CLEANUP_API_KEY=

# Compose-only inputs for the sidecar itself.
#VOCAGATEWAY_CLEANUP_IMAGE=ghcr.io/ggml-org/llama.cpp:server
#VOCAGATEWAY_CLEANUP_MODEL_DIR=./models
#VOCAGATEWAY_CLEANUP_MODEL_FILE=/models/model.gguf


# ============================================================================
# 6. Listener inside the container
# ============================================================================

# VOCAGATEWAY_PORT is both the container's listener port and the container-side
# target of the section 2 mapping, so it is safe to change on the default
# bridge network: the host port stays VOCAGATEWAY_PUBLISH_PORT.
#
# VOCAGATEWAY_BIND_HOST is the one to leave alone on bridge — the gateway must
# keep listening on all container interfaces for the published port to reach
# it. Narrowing it is only meaningful under VOCAGATEWAY_NETWORK_MODE=host,
# where the container binds the host directly.
#VOCAGATEWAY_BIND_HOST=0.0.0.0
#VOCAGATEWAY_PORT=8765


# ============================================================================
# 7. Settings that do not belong here
# ============================================================================

# These are read from .env but never reach the container, because compose.yaml
# does not pass them. Setting them here looks like it worked and does nothing:
#
#   VOCAGATEWAY_DATA_DIR, VOCAGATEWAY_MODELS_DIR, VOCAGATEWAY_CONFIG_FILE,
#   VOCAGATEWAY_TOKEN_FILE
#       Fixed by the image at /data, /data/models, /data/config/config.json,
#       and /run/secrets/vocagateway_token. Move the data elsewhere by
#       remapping the `vocagateway-data` volume, not by setting these.
#
#   VOCAGATEWAY_WHISPER_BINARY, VOCAGATEWAY_WHISPER_MODEL,
#   VOCAGATEWAY_WHISPER_SERVER_BINARY,
#   VOCAGATEWAY_WHISPERKIT_BINARY, VOCAGATEWAY_VOCAMAC_APP,
#   VOCAGATEWAY_VOCAMAC_MODEL, VOCAGATEWAY_HANDY_BINARY,
#   VOCAGATEWAY_HANDY_MODEL, VOCAGATEWAY_HANDY_FALLBACK_MODEL
#       Native-only. The image pins its own whisper.cpp CLI and resident
#       worker, and the macOS engines do not exist in a Linux container.
#
# And one that must not go here even though Compose would use it:
#
#   VOCAGATEWAY_GIT_COMMIT, VOCAGATEWAY_GIT_COMMIT_SUBJECT,
#   VOCAGATEWAY_GIT_COMMIT_DATE
#       Build args, not settings. Written into .env they would pin every later
#       build to whatever commit was current when you wrote the file. `just up`
#       and `just image` export them from git for you; see "Stamping the build
#       commit" in the README for the direnv equivalent.