Compose Templates and Images#

How each service container is defined and where its image comes from — authoring docker-compose.yml.j2 templates, taking ownership of a framework-managed template, and pointing services at mirrored or pinned images. Declaring a service in the first place is covered on the parent page: Container Deployment.

Docker Compose Templates#

Each service needs a docker-compose.yml.j2 template in its service directory. In addition, a root-level services/docker-compose.yml.j2 is required to define the shared network (osprey-network). Without it, osprey build and osprey up will fail.

services/
├── docker-compose.yml.j2          # Required: shared network definition
└── postgresql/
    └── docker-compose.yml.j2      # Per-service template

Per-service templates have access to the full configuration plus a few engine-injected values:

services/postgresql/docker-compose.yml.j2 (excerpt)#
services:
  postgresql:
    container_name: {{ osprey_labels.project_name }}-ariel-postgres
    ports:
      - "{{ deployment.bind_address | default('127.0.0.1') }}:{{ services.postgresql.port_host | default(osprey_ports.postgres, true) }}:5432"
    environment:
      TZ: {{ system.timezone }}
    networks:
      osprey-network:
        aliases:
          - ariel-postgres

The container name starts with the project name because a container name is global on the host: a fixed name collides when two projects run on one host. Other containers reach the database through the stable network alias ariel-postgres.

Common access patterns: {{services.<name>.<key>}}, {{file_paths.<key>}}, {{system.<key>}}, {{project_root}}, {{deployment.bind_address}}, {{osprey_ports.<slot>}} (the port layout for the deployment’s port_base), and {{osprey_labels.project_name}} / project_root (injected by the deploy engine).

The build writes build/osprey-labels.override.yml and passes it to every compose invocation. It gives every service osprey.project.name, com.osprey.repo-id, osprey.project.root and osprey.config.digest, so a template never writes them, and one that does is harmless. A template still writes two labels itself: com.osprey.repo-id: "{{ osprey_labels.repo_id }}" on each named volume it declares, because the override labels services, not volumes, and osprey reset only removes volumes that carry it; and osprey.env.digest on a service that reads the env chain.

The engine deliberately injects no deploy timestamp. Everything a template renders comes from the project’s configuration, so building the same project twice produces the same files — which is what lets you diff a rebuilt build/ directory and see only your own changes. A timestamp would also make every container look changed to the container runtime on each osprey up, restarting the whole stack for nothing. If you need to know when a container was started, ask the runtime: docker inspect reports it as .Created. Earlier versions of these templates carried an osprey.deployed.at label; a template you have customized that still sets it keeps building, and the label just renders empty, but you should drop the line.

What that timestamp was doing by accident, two content-hash labels now do on purpose. Your service reads its settings from files — the env chain, and the config.yml mounted into the container — and the container runtime decides whether to restart a container by comparing the compose document, which names neither file’s contents. So editing .env or running osprey set would leave the running container on the values it started with. Each label carries a hash of one of those files, which turns such an edit into a document change and restarts exactly the containers that read it. osprey up sets both variables for you; they interpolate to empty if you run docker compose by hand.

The build adds the config digest, osprey.config.digest, to every service through the labels override. The env digest is the template’s own:

osprey.env.digest: "${OSPREY_ENV_DIGEST:-}"

A service template you wrote yourself should carry the env digest line if the service reads the env chain — without it your service keeps serving its old env values after a change, with nothing to say so.

Service Template Ownership#

The service templates under <project>/services/ are framework-managed, so an edit made to one in place is overwritten on the next build; to keep an edit, claim the template into the build profile with osprey scaffold claim services/<name> (Taking ownership of a framework artifact).

Overriding Service Images#

Every service image resolves through the same three-layer chain — an environment variable wins, then a config.yml key, then the packaged default — and the two stack-wide axes assemble the default name of an OSPREY-built image. Every image, the two axes and their precedence are catalogued in Deployment — service images and ${VAR} interpolation.

When a deploy builds an image#

A service is built on the deploy host only when its rendered compose document carries a build: block. Upstream pins never do. The OSPREY-built services (the event dispatcher, the Bluesky bridge, the Bluesky web panel, the Google Chat, Nextcloud, Teams and Slack bridges, the qmd sidecar and the virtual accelerator) each do while they run the image OSPREY builds. A service whose services.<name>.image names any other image renders without build:, and that image is pulled and run as named. Where one template renders several containers off one image (the virtual accelerator and its live stand-in, the Bluesky lanes), the first of them that runs OSPREY’s image carries the build, and none does when every one names another image.

Which start builds what:

Start

What is built

osprey up --dev, with or without -d

A build step rebuilds every service with build:, then up --no-build.

osprey up or osprey restart without -d

The same build step, because the up replaces the osprey process.

osprey up -d without --dev

No build step. Compose builds a service’s image on up only when that image is not on the host.

A deployment with modules.web_terminals.enabled

Starts detached whatever the flag, so only --dev gives it a build step.

prebuilt_images: true or OSPREY_PREBUILT_IMAGES=1

Nothing, on any start (Deploying Prebuilt Images).

An OSPREY_<SERVICE>_IMAGE naming an image other than the one the build: block produces keeps that service out of every build. The start reports <service> runs <image> (<variable>); not built, builds the others in a step of its own even under -d, and starts everything with up --no-build, so an image that is neither on the host nor pullable fails with compose’s own error naming it.

The project image (dispatch worker, ARIEL sync, record archive, history page) has no build: block. The deploy builds it itself on every start unless the host is prebuilt or every one of those services it deploys names another image (OSPREY_WORKER_IMAGE or services.<name>.image).

The web tier names its registry separately#

The web tier — the landing page and the one containerized terminal per operator, described in Multi-User Support — carries its own, older spelling of the registry and tag axes, and the two vocabularies coexist rather than merging:

Service images

Web tier

Registry

images.registry / OSPREY_IMAGE_REGISTRY

registry.url

Tag

images.tag / OSPREY_IMAGE_TAG

modules.web_terminals.image_tag

Neither pair reaches the other’s images. images.registry does not move the web images, and registry.url does not move the service images. A deployment that mirrors everything sets both pairs, and sets them to the same place — that is the one case where the divergence costs you a line of config rather than nothing. A profile with a deploy: block in registry mode does not write registry.url itself, because the build fills it from deploy.registry.url (see Pull the terminal images from a registry).

Whether the web tier pulls those images or builds them on the deploy host is a third, separate setting: modules.web_terminals.image_source (registry, the default, or local). It is unrelated to the axes, and it is also the setting that governs the web-terminal and auth-sidecar builds — see below.

Mirroring every image into one registry#

A host behind a strict firewall, or with no route to the public internet at all, needs every image it starts to come from a registry it can reach. There are four channels to point at that mirror, and a deployment that misses one fails at up on the image it forgot:

Images

How to point them at your mirror

The OSPREY-built images

Set the registry axis once — images.registry, or OSPREY_IMAGE_REGISTRY for a single build.

The upstream pins

images.base_registry (or OSPREY_BASE_REGISTRY) moves every Docker Hub pin onto your mirror at once; a services.<name>.image row (or its OSPREY_..._IMAGE) still names one outright. tiled is on ghcr.io and needs its row. The agent record’s ClickHouse store has no variable: the profile’s agent_record.clickhouse.image names it.

The web tier’s images, auth sidecar included

registry.url plus modules.web_terminals.image_tag.

nginx

images.base_registry reaches it too. modules.web_terminals.nginx_image names it outright; that key carries no environment variable.

# config.yml — all four channels, one mirror
images:
  registry: registry.example.org/accelerator
  tag: "2026.08.1"
  base_registry: registry.example.org/dockerhub

registry:
  url: registry.example.org/accelerator

services:
  bluesky:
    tiled_image: registry.example.org/mirror/tiled:0.2.18

modules:
  web_terminals:
    image_tag: "2026.08.1"

Copy only the rows for services you actually deploy — the upstream pins for a service that is not in deployed_services are never rendered.

Naming the mirror is half the job: the host also has to stop building. That is the switch in Deploying Prebuilt Images. If your route is a self-built image rather than a mirror, The Project Image covers the air-gapped build trio — OSPREY_PIP_SPEC for an internal package mirror, PIP_NO_PROXY to exempt it from the proxy, and OSPREY_OFFLINE=1 to vendor the web assets into the image.

Deploying Prebuilt Images#

Some hosts cannot build images at all — no build tooling, no registry in reach — and run instead on images pulled from a mirror or loaded from a tarball. There, an image build is not merely slow but impossible. The top-level prebuilt_images key turns building off, so the deploy starts the containers from the tags already on the host:

# config.yml
prebuilt_images: true
# or, for one shell
OSPREY_PREBUILT_IMAGES=1 osprey up

1, true, yes and on turn the switch on; 0, false, no and off turn it off — case does not matter. The variable wins over the config key in both directions, so OSPREY_PREBUILT_IMAGES=0 forces a build for one shell even on a host whose config.yml pins the key. With neither set, deploys build as they always have.

The switch covers both ways a build can start (When a deploy builds an image):

  • A start with a build step of its own (any dev mode start, any start without -d) skips it, and a --dev start reports skipped image build (prebuilt images) where it would otherwise have built.

  • A detached non-dev start has no build step, but compose would still build a service whose compose document carries a build: block when its image is not on the host. The switch passes --no-build, so compose starts what is there instead.

What the switch does not reach. It governs compose’s implicit builds only. The web-terminal images and the auth sidecar are built explicitly, by a different mechanism, and stay governed by modules.web_terminals.image_source: a host that cannot build at all needs image_source: registry as well as prebuilt_images. Setting only one of the two is the usual way a genuinely build-less host still ends up trying to build something.

Nothing checks up front that the tags are really present. A missing one surfaces as compose’s own No such image error, which names the image to load or pull.

Together with the mirror settings above, the pull-only shape of a restricted deployment is: point all four image channels at the mirror, set prebuilt_images: true, and set modules.web_terminals.image_source: registry.

Sharing a Build Cache#

A host that builds the same images on a fresh builder every time, such as a CI runner, spends most of each build reinstalling the same Python dependencies. Two variables give every image build the deploy runs a BuildKit layer cache to read from and write to:

# read the layers another host wrote
export OSPREY_BUILD_CACHE_FROM='type=registry,ref=registry.example.org/osprey-cache:{key}'
# and, on the host that keeps the cache current, write them too
export OSPREY_BUILD_CACHE_TO='type=registry,ref=registry.example.org/osprey-cache:{key},mode=max'

Each value is a --cache-from / --cache-to spec as docker build takes it, with {key} standing for the image’s recipe rather than its deployment, so two deployments share one cache. The key is project for the project image and every web-terminal image (they share the project Dockerfile), auth-sidecar for the login sidecar, and a service’s build directory name, such as bluesky or event_dispatcher, for the rest.

A cache that has never been written is a BuildKit warning, not an error. A cache whose registry fails to serve one of its layers fails BuildKit’s build, so osprey up builds that image again once without OSPREY_BUILD_CACHE_FROM and logs a warning; the rebuild is slower, never wrong. Writing one needs Docker’s containerd image store or a docker-container builder; the classic overlay2 store refuses OSPREY_BUILD_CACHE_TO. Under Podman neither variable has any effect. With neither set, deploys build as they always have.