Skip to main content
Bring up the whole stack — serve, the backend worker, metrics, Postgres, and Redis 8 — with the Compose bundle from tai-distribution, running the official image. The bundle needs Docker Compose 2.20 or newer.

Boot the bundle

1

Get the bundle

2

Pin the image and set the secrets

Set POSTGRES_PASSWORD (it has no default — Compose refuses to start until it is set), and pin the image to a release rather than running latest:
TAI_VERSION in .env
3

Create the config directory

config/ bind-mounts at /app, so config/manifest.yml is the manifest the runtime loads and config/.env is the app-side environment. Create config/.env even when it is empty — the config-reload path treats a missing file as an error.The runtime writes the settings you save from Studio or the API back into these files, so at every start the stack hands config/ to the image’s user (uid 1000). After the first start, reading or editing these files by hand on the host takes that uid (sudo).
4

Start it

Two one-shots run first: config-init hands config/ to the image’s user, and db-migrate runs tai db migrate; serve and backend wait for both before they start. Only serve publishes a port (${TAI_SERVE_PORT:-8000}) — Postgres and Redis stay on the Compose network.
.env.example ships ACCESS_CONTROL_ENABLE=false — the auth-free quickstart shape, every route open. Turn it on before anything but a laptop, and register an identity provider in the same change: with access control on and no provider, the runtime refuses to boot. See Turn on access control.

The persistent mounts

Three paths a real deployment must keep across a container recreation, each located by an env var the server reads: The bundle bind-mounts config/ for the first, mounts the tai-plugins-data named volume at /app/plugins for the second on every app service and the db-migrate one-shot, and backs /app/templates with the tai-storage-local-data named volume for the third. A packaged marketplace install refuses while TAI_PLUGINS_DIR is unset, and every serve and backend process mounts the same directory. Persist all three, or a recreated container loses stored files or boots with the code and its registration out of sync. The bundled Postgres and Redis keep their own named data volumes. See Add plugins for the two ways a deployment installs plugins onto these mounts.

Profiles

The core stack is arq-on-Redis, and the example manifest selects local storage (storage_module: tai42_storage_local). Four opt-in profiles add infrastructure. celery, minio, and monitoring serve plugins that are not in the minimal image — add the plugin (a derived image or a marketplace install) before enabling its profile. sandbox serves the Docker sandbox provider, which the image already ships. The core Redis is Redis 8, so the default checkpoint store and LLM store run on it with no profile:
Langfuse itself runs as its own stack from compose/langfuse/: Langfuse 4.x with ClickHouse 26.4. A deployment that runs the 3.x stack moves with Move the Langfuse stack to 4.x. Its langfuse-web joins the core stack’s <project>_monitoring network (tai_monitoring under the default project name; TAI_CORE_PROJECT in compose/langfuse/.env names the core project), so bring the core stack up first. The containers then reach it at http://langfuse-web:3000 (inside a container, localhost is that container). Set that address as LANGFUSE_HOST in two places:
  • config/.env, with LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY: the plugin’s reads.
  • .env, with OTEL_COLLECTOR_LANGFUSE_AUTH (base64 of <public key>:<secret key>): the collector’s sends.
The network belongs to one core stack, so each core stack on a host sends to its own collector and its own Langfuse only. For several core stacks on one host, run one Langfuse stack per core stack, each with its own project name (-p), its own LANGFUSE_WEB_PORT and its TAI_CORE_PROJECT. The core stack owns the network. If the core stack is taken down and up again while langfuse-web is stopped, the network it pointed at is gone and it refuses to start (network … not found). Recreate it:
See Monitoring with Langfuse.

Build the image from source (dev only)

For running the stack against uncommitted local changes, compose/docker-compose.local.yml layers a SOURCE=local build onto every app service, building from sibling checkouts instead of pulling the release:
The source build’s siblings context is the parent of the checkouts, which can hold untracked secrets. Run it on a local builder only — never CI, never a shared registry. Production runs the official image.

See also

  • Deploy — transports, workers, and the serving modes.
  • Operate — access control, plugin setup, and the fleet view.
  • Upgrades — moving to a new image tag.