Skip to content

    Development documentation — this describes the current development branch. Documented behavior may not exist in the latest release.

    Docker Compose

    Docker Compose

    Section titled “Docker Compose”

    The repository ships three Compose files under docker/gpu/, each for a different use case. All map container port 8880.

    Prerequisites

    Section titled “Prerequisites”
    • Docker with the Compose plugin.
    • An NVIDIA GPU with the Container Toolkit for the GPU stacks.

    Production: pull and run

    Section titled “Production: pull and run”

    docker-compose.prod.yml pulls the published image with weights baked in — no source mounts, no downloads at start, GPU reserved:

    Terminal window
    docker compose -f docker/gpu/docker-compose.prod.yml up -d

    This is the offline-capable path suitable for a persistent single host. Uncomment API_KEY in the file (or supply it via your own env) to require authentication.

    Local single-GPU with HTTPS

    Section titled “Local single-GPU with HTTPS”

    docker-compose.local.yml builds the image and runs it with built-in HTTPS (self-signed on first run), a persistent named volume, and the container’s HTTPS exposed on host port 8443 (override with KOKORO_HTTPS_PORT):

    8443/web/
    docker compose -f docker/gpu/docker-compose.local.yml up -d --build

    The named volume kokoro-data is mounted at /data (OUTPUT_DIR=/data), so generated audio and the self-signed certificate under /data/tls survive restarts. Browsers warn on self-signed certificates — expected for local use. See Security hardening.

    Development: build from source

    Section titled “Development: build from source”

    docker-compose.yml builds from the local checkout and bind-mounts api/, so it sets DOWNLOAD_MODEL=true to fetch weights (the mount would otherwise shadow the baked-in ones). Use it when iterating on the server code:

    Terminal window
    docker compose -f docker/gpu/docker-compose.yml up --build

    The DOWNLOAD_MODEL=true path fetches weights at start and needs network access. The production and local files use baked-in weights and run offline.

    Common overrides

    Section titled “Common overrides”
    • Authentication — add API_KEY=... to the service environment.
    • CPU only — set USE_GPU=false and remove the deploy.resources.reservations GPU block.
    • Persistence — the local file already mounts a volume; for prod, add a volume and OUTPUT_DIR=/data.

    Next steps

    Section titled “Next steps”