Docker Compose reference
Which compose file ships with Tale, what each is for, and how the layering works when you bring up dev, docs, or test combinations.
3 min read
Tale ships a handful of Docker Compose files. The base is compose.yml; the rest are overlays that add or replace services for specific scenarios — development, docs, test. This page names each file, says when to pick it, and gives the layering rule everything else follows.
The shape is conservative on purpose. The base file alone runs production; every overlay is opt-in via -f and adds only what it needs to. Memorise the base and a single overlay, not the whole grid.
A worked compose-up
A production single-host instance runs from the base alone:
docker compose up -dA developer hacking on platform and docs at the same time layers two overlays:
docker compose -f compose.yml -f compose.dev.yml -f compose.docs.yml up -dThe 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
| File | Use case | Notable overrides |
|---|---|---|
compose.yml | Production single-host | The base — every service, healthchecks, restart policy |
compose.dev.yml | Local development with hot-reload | Mounts source into containers, swaps to dev images, exposes dev ports |
compose.docs.yml | Adds the docs site service | Brings up tale-docs and routes /docs through the proxy |
compose.web.yml | Adds the marketing site service | Brings up tale-web and routes / (root) through the proxy |
compose.test.yml | Runs the platform test suite against the stack | Replaces the platform image with the test-shaped variant |
compose.web.test.yml | Runs web tests | Like web.yml but the test-shaped variant |
compose.docs.test.yml | Runs docs tests | Like docs.yml but the test-shaped variant |
compose.test.mock.yml | Mock-backed integration tests | Swaps providers for mock implementations |
Services and their roles
The base graph brings up eight containers:
tale-proxy— Caddy. TLS, reverse proxy, 301s.tale-platform— the TanStack Start app. The user-facing UI and API.tale-convex— the Convex backend. WebSocket, queries, mutations, actions — and the in-process RAG search, document ingestion, web crawling, and document generation that used to be separate services.tale-db— operational Postgres (ParadeDB). The Convex backend's persistent store.tale-knowledge-db— knowledge corpus Postgres (ParadeDB). Thetale_knowledgedatabase holding document chunks, embeddings, and crawled pages, on port 5433 so it never clashes withtale-dbon 5432.tale-sandbox-llm-gateway— the LLM gateway for in-sandbox coding agents (pinned external image).tale-sandbox-egressandtale-sandbox— the sandbox plane. Run-code containers behind an egress proxy (open by default; lock down withSANDBOX_EGRESS_ALLOWLIST), also the headless-browser runtime the convex backend calls for web rendering and document generation.
The stack is now entirely TypeScript — there is no Python service in the graph. 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=debugBring the stack up with the local overlay layered last:
docker compose -f compose.yml -f compose.local.yml up -dThis 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.
Profiles
One service in the base file uses a Docker Compose profile. Profiles let a service exist in the graph but not start unless its profile is activated. The profile in use is controller — the opt-in tale-controller sidecar that restarts the convex container on a signed request so a data-residency change applies without giving the platform Docker-socket access. Activate it with:
docker compose --profile controller up -dWhere 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.