Contributor compose files

This page is for people hacking on the source tree. The base is compose.yml; the rest are overlays that add or replace services for development, docs, and tests. Operators running Tale do not start here — the CLI path is Quickstart, and a stack you write yourself is Run Compose yourself.

The base file is a build-from-source stack for local smoke-testing. Every overlay is opt-in via -f. A production instance is generated by tale deploy and never uses these files.

A worked compose-up

The base file builds every image from source and runs that frozen build. It exposes ports that must never be public (5432, 8003) and boots with insecure dev secret defaults, so it is for local smoke-testing, not a public instance:

docker compose up -d

A developer hacking on platform and docs at the same time layers two overlays for live source and hot-reload:

docker compose -f compose.yml -f compose.dev.yml -f compose.docs.yml up -d

The leftmost file is the base; each subsequent file merges its keys on top. Conflicts (same service, same key) resolve last-file-wins. The merged graph is what Docker brings up.

The compose files

Services and their roles

The base graph brings up eleven containers:

• tale-proxy — Caddy. TLS, reverse proxy, 301s.
• tale-platform — the web tier: a Vite + TanStack Router SPA plus the Bun server that serves it, branding, and the config SSE watch.
• tale-backend-api — the application backend in the api role (TALE_ROLE=api). Every application door: the app API, auth, the SSE hint stream, and the machine doors.
• tale-backend-worker — the same image in the worker role. The job runner behind schedules and agent turns, and the in-process document ingestion, web crawling, RAG indexing, and document generation that used to be separate services.
• tale-db — operational Postgres (ParadeDB). The tale_app application store, on port 5432.
• tale-knowledge-db — knowledge corpus Postgres (ParadeDB). The tale_knowledge database holding document chunks, embeddings, and crawled pages, on port 5433 so it never clashes with tale-db on 5432. (A tale deploy production stack folds this into tale-db instead — see Architecture overview.)
• tale-object-store — MinIO, the S3-compatible blob backend for uploads, attachments, and generated media (internal-only).
• tale-sandbox-llm-gateway — the LLM gateway for harness turns.
• tale-sandbox-egress and tale-sandbox — the sandbox plane. Run-code containers behind an egress proxy (open by default; lock down with SANDBOX_EGRESS_ALLOWLIST), also the headless-browser runtime the backend calls for web rendering and document generation.
• tale-bgutil-provider — a third-party sidecar supplying YouTube PO-tokens for video-link ingestion.

There is no separate Python service in the graph — the knowledge work (RAG, crawling, document generation) runs inside the backend worker now. Container architecture goes deeper on what owns what.

Overriding

Operator customisations belong in an extra overlay, not in edits to the shipped files. Create compose.local.yml with the overrides you need:

services:
  platform:
    environment:
      - LOG_LEVEL=debug

Bring the stack up with the local overlay layered last:

docker compose -f compose.yml -f compose.local.yml up -d

This pattern keeps git pull clean — no merge conflicts on the shipped files. The same pattern works for any custom volume mount, custom port, or environment override.

Where this fits

The compose reference is the operator's grid for the source tree. For the inside of each container, the container architecture page covers responsibilities; for the variables the containers read at boot, the environment reference is the source of truth.