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:
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 |
|---|---|
|
A build step rebuilds every service with |
|
The same build step, because the |
|
No build step. Compose builds a service’s image on |
A deployment with |
Starts detached whatever the flag, so only |
|
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 |
|
|
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 — |
The upstream pins |
|
The web tier’s images, auth sidecar included |
|
nginx |
|
# 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--devstart reportsskipped 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.