Container architecture

Tale runs as six Docker containers managed by Docker Compose. Each container has a single responsibility and communicates over an internal bridge network. Convex runs as its own service (convex) and serves WebSocket clients independently of the platform container; platform is a thin Vite client that pushes schema and env to Convex over HTTP.

Service overview

Image details

Splitting Convex out of platform reduced the platform image from ~2.58 GB to ~320 MB compressed; the convex service is a new ~485 MB image. Net image disk is similar but the platform layer rebuilds much faster for app-only changes.

Port mapping

Development ports (compose.yml)

Test ports (compose.test.yml)

Volume mapping

Important: Never run docker compose down -v. The -v flag deletes all Docker volumes, permanently erasing your database and all platform data.

Build arguments

Multi-stage build strategy

All services use a FROM scratch squash as their final stage. This flattens Docker layers so that file deletions in cleanup stages actually reclaim disk space, rather than just adding masking layers.

Platform (5 stages, post-split)

1. bun-bin — Extracts Bun binary
2. workspace-deps — Installs all npm dependencies (including devDependencies)
3. builder — Runs vite build to produce the SPA
4. pruner — Reinstalls production-only deps, removes dev packages (@vitest, @storybook, typescript, etc.)
5. runner — Final runtime on the convex-backend base image (kept for the generate_key glibc binary used to sign Convex admin tokens). Vite SPA + Bun server only — no Convex backend process.
6. squash — FROM scratch + COPY --from=runner. Runs as root, drops to app user via gosu in entrypoint.

Convex (2 stages, new in Phase 2)

1. convex-dashboard — FROM ghcr.io/get-convex/convex-dashboard to COPY the Next.js standalone build.
2. runner — FROM ghcr.io/get-convex/convex-backend. Contains convex-local-backend daemon, Dashboard, builtin seed assets (agents/workflows/integrations/providers/branding), entrypoint. Strips LLVM/Clang (~155 MB).

Crawler (3 stages)

1. builder — Installs Python deps via uv, downloads Chromium headless_shell, runs deep cleanup (removes full Chrome, FFmpeg, pip, __pycache__, .so debug symbols, test dirs)
2. runtime — Clean python:3.11-slim with only runtime system libs (Chromium deps, tini, curl). Strips LLVM/Adwaita icons
3. squash — FROM scratch + COPY --from=runtime. Pre-creates volume mountpoints for /app/data and /app/platform-config

RAG (3 stages)

1. builder — Installs Python deps with build-essential + libpq-dev for compiling native packages, then strips pip/setuptools
2. runtime — Clean python:3.11-slim with only libpq5 + curl. Pre-creates volume mountpoints
3. squash — FROM scratch + COPY --from=runtime

DB (3 stages)

1. cleanup — Strips debug symbols (~888 MB), LLVM shared libraries (~127 MB), PostGIS extension files, locales, and docs from the ParadeDB base image
2. runtime — FROM scratch + COPY --from=cleanup. Fresh layer with only cleaned files
3. squash — Re-declares PGDATA, PATH, and other ENV vars lost during FROM scratch

Health checks

The /tmp/<service>-ready markers are touched by each service's entrypoint after its one-shot initialization work completes (Convex: backend up + builtin seed; Platform: env sync + convex deploy). This prevents traffic from being routed before the service is truly ready to serve requests.

Container testing

Tale includes three container test scripts:

See Contributing Docker guide for details on modifying Dockerfiles and running tests.