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.

Phase 2 split architecture (since v0.2.34): Convex runs as its own service (convex) instead of being embedded in the platform container. Platform becomes a thin Vite client that pushes schema + env to Convex over HTTP. See Upgrading from pre-split-convex (pre-v0.2.34) for the one-time migration step.

​

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.