docker compose up gives you a development server that behaves like Izwi running natively on your machine. Production adds a second Compose file, which you switch on with two lines in .env.
Requirements
- Docker Engine 28.3.3 or newer on Linux, or Docker Desktop on macOS and Windows. Older Linux engines could let other machines on the same network reach ports published on
127.0.0.1, which the development setup relies on to stay private. See Keep the host patched. - Docker Compose v2 with support for the
!overridemerge tag (used by the production overlay). - For CUDA: NVIDIA driver 580 or newer and the NVIDIA Container Toolkit. The CUDA image targets Ampere (compute capability 8.0) or newer GPUs.
Development (the default)
docker compose up -d --build, or leave docker compose watch running to do that whenever a file under crates/ or ui/ changes. The build caches compiled dependencies, so a rebuild recompiles only what changed.
Using a published image
Releases after 0.1.0 also ship signed images on the GitHub Container Registry, so you can skip the build. Verify the signature with cosign 3 or newer, then tag the image as the one Compose uses:${VERSION}-cuda tag and tag it izwi:cuda. The release notes list every image and the matching gh attestation verify command.
What the development setup allows
- The port is published on the host’s
127.0.0.1only, so other machines cannot reach it. - Inside the container the server runs in loopback-only mode (
IZWI_LOOPBACK_PUBLISHED=1). It needs no API key and answers onlylocalhost-styleHostnames, so a web page cannot reach it through DNS rebinding. - Any program on this machine can use the API, just as with a native install.
- Other containers on the Compose network that call the server by service name need that name allowed: set
IZWI_ALLOWED_HOSTS=izwiin.env. - Setting
IZWI_API_KEYin development is optional; when it is set, it is enforced.
Production
Write a.env file next to docker-compose.yml that adds the production overlay and holds a new API key, then start the server as before:
Authorization: Bearer <key>, and the web UI asks for it once. To read it back, run grep IZWI_API_KEY .env.
docker-compose.prod.yml) changes these settings and nothing else:
Both modes run as the unprivileged
izwi user (uid 1000) with every Linux capability dropped and privilege escalation disabled, and on a server with a key the public /livez and /readyz answer with only the status and version. Capacity, queues and startup warnings are on /v1/health, which needs the key.
Fish Audio Drama 3 and third parties. A server or Docker deployment that lets third parties generate speech with FishAudio-Drama-3 from text or voice samples they supply is a “Hosted Service” under the model’s Fish Audio Community License v1.0, which grants no license for one: such a deployment needs a license from Fish Audio. Personal, research and non-commercial use, and speech for your own product, are fine within the license’s terms, including its USD 500,000 annual revenue cap on commercial use. See Models.
Reaching the server from other machines
The server speaks plain HTTP, so anything that crosses a network should go through a TLS-terminating reverse proxy. The production overlay includes one: Caddy, which gets and renews a certificate automatically. Point a DNS name at the host, open ports 80 and 443, and add to.env:
tls profile:
IZWI_TLS_UPSTREAM=izwi-cuda:8080. To use your own proxy instead, run it on the same host, keep the default IZWI_PUBLISH_ADDR=127.0.0.1, and set IZWI_ALLOWED_HOSTS to the public host name, so the server answers only that name and localhost. Per-client rate limits belong in the proxy.
Setting IZWI_PUBLISH_ADDR=0.0.0.0 publishes the port on every interface, and the API key then travels unencrypted. Docker’s port rules bypass host firewalls such as UFW, so do this only on a network you trust.
Never set IZWI_ALLOW_UNAUTHENTICATED_NETWORK in a container. It removes the API key requirement for every client that can reach the port.
Keeping the key out of the environment
A key in.env reaches the container as an environment variable, which docker inspect shows to anyone who can use Docker on the host. The server can read the key from a file instead: set IZWI_API_KEY_FILE to its absolute path inside the container and leave IZWI_API_KEY unset. Orchestrators that mount secrets (Docker Swarm, Kubernetes, systemd) do this directly. With Compose, add a file of your own, for example docker-compose.secret.yml:
./secrets/izwi_api_key and, in .env, replace the IZWI_API_KEY line with IZWI_API_KEY_FILE=/run/secrets/izwi_api_key and append :docker-compose.secret.yml to COMPOSE_FILE. The file must be readable by uid 1000.
Offline and proxied networks
IZWI_OFFLINE=1stops the server from contacting Hugging Face at all: model downloads are refused and sizes come from built-in estimates. Copy model files into theizwi-modelsvolume yourself. Fish Audio Drama 3 also needs theizwi-artifact.jsonIzwi writes when it checks a download, so copy its whole directory from a machine where Izwi downloaded it (see Manual Downloads).- Downloads use
HTTPS_PROXY(withNO_PROXYexceptions) when it is set.
environment: in a compose file of your own, listed after the others in COMPOSE_FILE.
Data
- Models live in the
izwi-modelsvolume. - History (the database) and media live in
izwi-data.
docker compose down and docker compose up --force-recreate. docker compose down -v deletes them.
Upgrading
izwi-data first.
The server runs as uid 1000 with no capabilities, so it cannot write files that another user owns. If models were downloaded by the development container from Izwi 0.1.0 or earlier, which ran as root, hand the volume to uid 1000 once:
Backup and restore
Stop the server so the database is consistent, archive the volume, then start it again:Keep the host patched
Container isolation is only as strong as the host’s container runtime. Keep Docker Engine (or Docker Desktop), runc, containerd and, for CUDA, the NVIDIA Container Toolkit up to date. In particular:- Docker Engine 28.3.3 or newer on Linux. Older engines could expose ports published on
127.0.0.1to the local network. - runc 1.2.8, 1.3.3 or newer, which fix the November 2025 container-escape vulnerabilities (CVE-2025-31133, CVE-2025-52565, CVE-2025-52881).
- NVIDIA Container Toolkit 1.17.8 or newer (CVE-2025-23266).
- NVIDIA driver 580 or newer for the CUDA image, which is built with CUDA 13.0.
Without Compose
The image refuses to start on0.0.0.0 without a key, because it cannot tell how its port is published. For development, publish on loopback and say so:
-v, every docker run creates fresh anonymous volumes, and earlier history looks lost.