Build and maintain Tale images

Build an image when a change affects container dependencies, startup behavior or packaged application code. Start from a source checkout with the prerequisites in Contributor setup, a running Docker daemon and access to the base-image and package registries used by the Dockerfile.

A successful build proves that an image can be assembled. Run it in a separate development stack and exercise the changed behavior before using it in a deployment.

What the images are

Dockerfiles use the repository root as their build context. Open the relevant Dockerfile for exact base-image versions and build arguments; the table describes each image’s purpose.

Object storage and the video-ingestion sidecar use upstream images directly. They are not built from a Tale Dockerfile. Sandbox runtime and BuildKit images are launched on demand; do not assume that building only the services in a Compose file also builds them.

Building locally

For an isolated proxy-image build, run this from the repository root:

docker build -f services/proxy/Dockerfile -t tale-proxy:docs-review .

The local docs-review tag makes the result distinguishable from a published release. The build must finish successfully before you test or tag it for distribution.

For services declared with build: in the repository Compose file, use:

docker compose build platform

docker compose build without a service selects all services that have a build definition. Build time depends on cached layers, network access, platform and the image; a browser or application image has different requirements from the proxy.

The repository Compose file defaults PULL_POLICY to build. Generated production Compose normally pulls release images. Use Compose files for the supported development launcher, which also prepares services and images that a bare build does not start.

The customisation seams

Choose the narrowest change that satisfies the requirement:

Entrypoints, health checks and internal paths are implementation contracts. A fork must maintain and test changes to them across upgrades. A configuration-only change may not need a new image; see Run Compose yourself.

Tagging and pushing your own registry

After testing the image, set your registry namespace and an immutable tag. This example publishes only the proxy image built above; it is not a complete deployment image set. Registry authentication and permission to push are prerequisites.

export REGISTRY=registry.internal.example.com/tale
export IMAGE_TAG=reviewed-build-1
docker tag tale-proxy:docs-review "$REGISTRY/tale-proxy:$IMAGE_TAG"
docker push "$REGISTRY/tale-proxy:$IMAGE_TAG"

Record the resulting digest, source commit and build platform. Distribute all images required by the destination, including sandbox images and upstream dependencies. An offline environment also needs a plan for packages, browser downloads and model access; moving a single image does not make the system self-contained.

The CLI reads GHCR_REGISTRY for the Tale image namespace. Its selected version still determines the image tag, so publish the names and version tags the deployment expects. For independently pinned images and source commits, follow the managed deployment reference.

Staying in sync with upstream

Keep the fork’s source changes under version control and review upstream changes before rebuilding. Record base-image versions or digests with the build. Review updates to those pins deliberately; rebuilding against an unchanged pin does not incorporate a newer upstream image automatically.

Before rollout, verify the startup role, health checks, public routes and the feature you changed. For sandbox changes, include a new session and its required network calls. Contribute generally useful fixes upstream when possible to reduce the code your fork must maintain.

Diagnose a failed build or startup

Use Container architecture to trace service dependencies and Upgrades for rollout and recovery.