Run Compose yourself

This page is what a stack must reproduce when you write Compose or Kubernetes yourself instead of running tale deploy: which services hold state, the DNS names, the probes, the volumes. The CLI path stays in Quickstart and Upgrades.

When this path is the right one

Use the CLI when you can run it. Use this page when you write Compose, or when you map the same contract onto Kubernetes.

There is no official Helm chart.

Stateful and stateless

Ten services, two kinds. Stateful services hold disks and fixed identity — recreate them and you lose data or break DNS. Stateless services are interchangeable replicas of one image; recreate them in place on upgrade. One compose file is the default. Split files or Kubernetes is yours, as long as the DNS names, the isolated sandbox network, and the boot order stay.

sandbox-llm-gateway is the harness path: the api provisions it, and a session container reaches it as llm-gateway. bgutil-provider is the worker's YouTube PO-token sidecar and is best-effort — video-link ingest degrades without it.

The three stateless services share one image (ghcr.io/tale-project/tale/tale-platform:<version>). TALE_ROLE picks api or worker at boot; the web tier is the same image without that role. Pin every tale-* image to the same release tag so the wire contracts cannot skew.

The images

Every tale-* image is published on the GitHub Container Registry under the same release tag, so one version number pins the whole stack. Two services run upstream images with versions of their own.

One image is not a compose service. The spawner creates every session container from ghcr.io/tale-project/tale/tale-sandbox-runtime:<version>, and its built-in default is the local tag the development stack builds — a host that never built it must name the registry image in SANDBOX_RUNTIME_IMAGE, or Run code, web render, and document generation all fail with an image-not-found. The examples below pin the release this page documents; replace the tag with the release you are installing.

The stateless services

Below are the three stateless roles — aliases, /ping as liveness, TALE_ROLE, NET_ADMIN. Put the stateful services in the same file or elsewhere; the tables on this page are what they must still do. Pin the image tag and fill .env from the Environment reference.

# Stateless app tier. No container_name: --scale needs free names.
# Add db, proxy, sandbox, … in this file or another — your call. In one file,
# add depends_on: { db: { condition: service_healthy }, … } as well.
services:
  platform:
    image: ghcr.io/tale-project/tale/tale-platform:0.5.11
    env_file: [.env]
    volumes: ['config-data:/app/data:ro']
    restart: unless-stopped
    stop_grace_period: 45s
    healthcheck:
      test:
        [
          'CMD-SHELL',
          'curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]',
        ]
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 180s
    networks:
      internal:
        aliases: [platform]
  backend-api:
    image: ghcr.io/tale-project/tale/tale-platform:0.5.11
    environment:
      TALE_ROLE: api
      PORT: '3005'
      TALE_CONFIG_DIR: /app/data
      DATABASE_URL: postgresql://tale:${DB_PASSWORD}@db:5432/tale_app
      SANDBOX_URL: http://sandbox:8003
      SANDBOX_HTTP_API_BASE_URL: http://backend-api:3005
      OBJECT_STORE_ENDPOINT: http://object-store:9000
    env_file: [.env]
    volumes: ['config-data:/app/data']
    cap_add: [NET_ADMIN]
    restart: unless-stopped
    healthcheck:
      test: ['CMD-SHELL', 'curl -sf http://localhost:3005/ping']
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 30s
    networks:
      internal:
        aliases: [backend-api]
      sandbox:
        aliases: [backend-api]
  backend-worker:
    image: ghcr.io/tale-project/tale/tale-platform:0.5.11
    environment:
      TALE_ROLE: worker
      TALE_CONFIG_DIR: /app/data
      DATABASE_URL: postgresql://tale:${DB_PASSWORD}@db:5432/tale_app
      SANDBOX_URL: http://sandbox:8003
      SANDBOX_HTTP_API_BASE_URL: http://backend-api:3005
      OBJECT_STORE_ENDPOINT: http://object-store:9000
    env_file: [.env]
    volumes: ['config-data:/app/data']
    cap_add: [NET_ADMIN]
    restart: unless-stopped
    healthcheck: { disable: true }
    networks: [internal]
volumes:
  config-data:
networks:
  internal:
  sandbox:
    name: tale-sandbox-net
    internal: true
    enable_ipv6: false

There is no checked-in production compose to copy. The CLI generates a split file pair and deletes it after up. Your file does not have to look like that.

Secrets you generate before the first boot

tale init mints every secret and writes the .env; without the CLI that job is yours. The Environment reference marks what each variable does — the four below are the ones a hand-rolled stack most often ships without, because the example file leaves them commented for the CLI to fill.

The public endpoint is the one to get right before you start, not after. The backend seeds the deployment-default blob connection into the config volume on its first boot (default/object-storage/connection.json) and never rewrites a default that already exists, so setting the variable on an instance that has already booted changes nothing. To repair such an instance, add "publicEndpoint": "<your SITE_URL>" to that file and restart the backend.

Networks and DNS names

Two Docker networks carry every hop. An ordinary compose network is enough for the internal plane. The sandbox bridge must be named tale-sandbox-net and marked internal so the spawner can docker run --network tale-sandbox-net and a session container cannot reach the internet without going through sandbox-egress. A bridge without internal is an open path out.

Workers have no shared alias. Nothing addresses a worker by name; they only claim jobs from the queue. Colour-suffixed aliases (backend-api-blue, platform-green) are only for a blue-green while two versions are up at once.

The proxy sends app API lanes to backend-api:3005 (BACKEND_UPSTREAM). It sends /api/health and the SPA to platform:3000, and it health-checks platform on /api/health. Fail that probe on a draining web replica and Caddy marks the whole site down.

Volumes

Name these logical volumes in your compose. One file can let compose create them. Mark them external only if something outside this file must mount the same disks.

Instances upgraded from before 0.5.11 may still have a convex-data volume beside config-data. The CLI copies the store across once and never deletes the old volume. A hand-rolled first boot on a fresh host does not need convex-data.

Health probes

Liveness and readiness are different questions. Mixing them cuts a draining replica out of DNS before in-flight work finishes, or keeps an unready replica in the pool.

Environment the compose must inject

The Environment reference is every variable the process reads from .env. The rows below are what the compose file itself must set — image defaults point the process at the wrong host.

Capabilities and mounts that break if omitted

These look optional and fail closed when they are missing.

Publish only 80 and 443 on proxy. Everything else stays on the internal network.

Boot order

Bring the stores up first, then the sandbox plane, then the app tier. An api that starts before db and object-store are healthy crash-loops on ENOTFOUND and on a missing database. In one file, depends_on with service_healthy is enough.

docker compose up -d
# Wait until db, object-store, proxy, sandbox, sandbox-egress, sandbox-llm-gateway
# report healthy. bgutil-provider is best-effort — YouTube ingest degrades without it.

Give every service a restart policy (restart: unless-stopped). Nothing else brings a container back after a host reboot or an OOM kill, and a stack that boots once but never again is the failure operators find weeks later.

Schema migrations run inside the backend at boot, under an advisory lock. There is no separate migrate step. A replica that cannot apply a migration fails to start; leave the previous api running until the new one is healthy.

Kubernetes

There is no Helm chart and no official manifest. Map the Docker contract; do not invent a second architecture.

Publish only 80 and 443. Leave Postgres, MinIO, and the sandbox port off the public Service list.

In-place recreate of the stateless Deployments is the default. Zero-downtime is a rolling update you own.

What you give up without the CLI

tale deploy is not a compose up. The commands below have no equivalent in a file you maintain.

An in-place recreate of the stateless services is the default. Zero-downtime is the part you reimplement.

What production must not do

These look local and break a public instance.

Where this fits

You now have the contract: which services hold state, two networks, the DNS names the proxy and the sandbox resolve, the probes that must not be swapped, and what Kubernetes must still do. Environment reference is every variable the containers read. Container architecture is what each container owns when one of them dies. Most teams still want the quickstart and tale deploy — this page is the path when that wrapper is the thing you cannot run.