Deploy a Facility#

This page builds one facility deployment from an empty directory to running containers, using only osprey commands. Follow it in order and you end up with a git repository you can commit, review, and hand to a colleague.

The facility is called Demo Facility. It runs four services, serves two web terminals — one read-only, one write-capable — and ships one container the facility writes itself.

What You’ll Learn
  • Creating a deployment repository with osprey init

  • Editing the profile down to the services your facility actually runs

  • Adding a container the facility owns, with its own image-build job

  • Emitting the CI pipeline and the health check with osprey scaffold ci

  • Rendering the build and bringing the stack up

  • Making the deployment come back by itself after a reboot

Prerequisites: A working OSPREY installation, git, and Docker or Podman running locally.

Time: 30–45 minutes.

Tip

Read Build Profiles first if the words preset, profile and build are new. This page assumes you know that the profile is the source of truth and build/ is a rendered artifact.

What you are building#

One repository, holding the facility’s editable source and the deployment scaffolding that goes with it:

demo-facility/
├── profile.yml                       the manifest you own — edit this
├── data/                             channel databases, knowledge, lattice
├── tiers/                            one file per login, shared cards included
├── services/facility-mcp/            the facility's own container
├── scripts/verify.sh                 the post-deploy health check
├── .env                              the deployment's secrets
├── .env.agent-record.*               agent record credentials, one file per login
├── build/                            render target, kept out of git
├── var/                              agent memory and audit log, kept out of git
├── .gitlab-ci.yml                    emitted from the profile's deploy: block
├── ci-extra.yml                      your own CI jobs; never regenerated
└── .gitignore

Four services run:

Service

Comes from

What it does

agent-record

packaged

Keeps the agent record: what the agent was asked, what it answered and what it did (The Agent Record).

agent-record-clickhouse

packaged

The ClickHouse store the record is kept in, from the preset’s agent_record.backend: clickhouse.

virtual_accelerator

packaged

A containerized simulator with LUME-backed physics (Virtual Accelerator), serving EPICS Channel Access on port 5064 and standing in for the real machine.

facility-mcp

this profile

The facility’s own MCP server on port 10900, built from a Dockerfile that lives in the profile.

The first three are packaged with OSPREY. The last is the interesting one: it is the part no framework can ship for you, and everything about how a facility-owned container is declared, built, and reached is in Step 4 — Add the facility’s own container.

What the perimeter needs#

The web tier (nginx, the landing page and one terminal per user) makes four demands on the network in front of it: its own hostname or host:port, one origin, the host network, and at most 100 users. They hold for every deployment, and the refusals and warnings that enforce them link to this section.

Limit

What it means

If your site cannot meet it

Its own hostname or host:port

The deployment is served from / of the address a browser uses and cannot sit under a path such as https://www.example.org/osprey/. modules.web_terminals.external_origin is refused if it carries a path. Every terminal compares the browser’s Origin header against external_origin as a whole string, so it is written as a bare origin.

Give the deployment its own DNS name at the front proxy (https://osprey.example.org) or its own port on an existing name (https://www.example.org:8443).

One origin

Every terminal accepts a state-changing request only from the one origin the deployment was built for: external_origin, or the one derived from deploy.fqdn. nginx answers only on that origin’s host, and a request under any other name is redirected (301) to the same path there.

Publish one name and give every user that address. Serve it over HTTPS covers the setting and a TLS terminator in front.

The host network

nginx and every per-user terminal run with network_mode: host, so the container runtime must be able to put containers on the host’s own network.

A Linux host running Docker or Podman does this directly. Docker Desktop on macOS does it only with Enable host networking turned on (Settings → Resources → Network).

At most 100 users

Each per-user port family holds 100 ports, one for each user index 0 to 99 (The panel bands). A roster with an index past 99 is refused, and setting a family’s <family>_base_port does not raise the limit.

Run a second deployment for the next group of users, on its own deployment.port_base (Ports).

The write boundary today#

A process in a terminal or dispatch-worker container reaches the control system the way the host does. OSPREY’s block on raw puts is cooperative, not a sandbox (Safety Chain). The boundary that does not depend on OSPREY’s own code is the facility’s EPICS access security, at the CA gateway or the IOCs:

  • a host access group (HAG) holding only the OSPREY host, so writes from any other machine are refused;

  • a user access group (UAG) holding only the writer names OSPREY uses (the control identities in Safety Chain);

  • a gateway pvlist that denies by default and allows writes only to the channels this deployment is meant to move.

The client reports its own user name, so these rules narrow which writes are possible; they do not authenticate the process that makes one. Where the server supports it, match hosts by address rather than by the name the client reports. Code in a container that claims a writer name can still write to the allowed channels. The end state closes that gap: the connector runs as its own service, and the agent containers have no route to the control system.

Step 1 — Create the facility repository#

osprey init demo-facility --preset demo
cd demo-facility

The command writes the whole repository, runs git init at its root, and commits nothing. It prints the handful of entries you edit: the profile, the data directory, the six login files it wrote in tiers/, the two env files, and the README.

The folder name is read once, here. osprey init records it in profile.yml as the deployment’s name on a host:

name: Demo Facility          # display text
project_name: demo-facility  # names the compose project, volumes and images

From now on every container, volume and image this deployment creates is named from project_name:, and the folder a checkout sits in no longer matters. A clone under another folder name is the same deployment.

It says nothing about CI, which is expected: the profile ships with its deploy: block commented out, so there are no coordinates to render a pipeline from. Step 5 fills the block in and Step 7 renders the pipeline from it.

Step 2 — Trim the profile to this facility’s stack#

Open profile.yml. The demo preset ships a fuller stack than Demo Facility runs, so the first edit is subtraction. Delete:

  • the top-level bluesky:, bluesky_web: and dispatch: blocks. Each of these is a trigger: leaving one in place adds its service to the deployment, whatever else you write below.

  • from skills: — writing-bluesky-plans, operating-bluesky-plans and bluesky-plans.

  • from agents: — logbook-search and logbook-deep-research. Both query a logbook database at runtime, and this facility does not deploy one.

  • for the same reason, the logbook line under modules.web_terminals.shared in config:, plus tiers/logbook.yml. That card is the shared logbook login, and it needs the logbook database this facility does not run. The knowledge login stays: it reads the graph store this facility keeps.

  • from web_panels: — ariel, events and bluesky.

  • from config: — the claude_code.servers.bluesky.enabled line and every web.panels.events.* and web.panels.bluesky.* override. The panels they configure no longer exist.

Keep the virtual_accelerator: block. It is the trigger for the Virtual Accelerator this facility drives.

Step 3 — Name the facility and pin its services#

Still in profile.yml, under config:, set these four values. Some are already present with a different value; some ship commented out.

config:
  control_system.type: virtual_accelerator
  claude_code.servers.health.enabled: true
  system.timezone: America/Los_Angeles
  deployed_services: []

control_system.type: virtual_accelerator points the agent at the deployed simulator, so correctors move and BPMs read through exactly the approval and limit layers a live machine would use. The preset already ships this value; it is written out here because it is the line that changes when the deployment goes live (Changing something later).

The facility’s display name is not a config key. Open data/facility/identity.yaml (osprey init wrote it with the facility code) and add the name:

code: ca
name: Demo Facility

This name is what the agent prompts, the web landing page and the dispatcher dashboard show. A file without name shows the project name.

A deployment describes one real machine. control_system.type names it, or — on a simulated baseline like this one — the single non-simulated block under control_system.connector does, and the three control targets (live, va, standin) name that machine, the simulator and the stand-in soft IOC. A complex that operates two real machines, an injector and a storage ring say, runs one deployment per machine rather than one deployment naming both: the write posture, the limits, the approvals and the archive all belong to a machine, and a second non-simulated connector block here would be a block no target ever reaches. See Switch the Control Target at Run Time.

deployed_services looks too short, and is not. The virtual_accelerator: block and the services: entry you add in Step 4 each append their own service to this list at build time. Starting it empty is what keeps the preset’s postgresql, qmd and graphdb out — declared is not deployed, and this list is what osprey up reads. The agent record’s services come from the agent_record: block, never from this list.

The web tier is named from project_name like the rest of the deployment, so this one runs demo-facility-nginx and one demo-facility-web-<user> per operator (demo-facility-web-alice).

system.timezone is the zone operator times are read in and every timestamp is shown in. Spell it exactly as the IANA time zone database does, case included (America/Los_Angeles, not america/los_angeles), or osprey build refuses it. A build left on the preset’s UTC prints a one-line reminder, and osprey health reports UTC as information. A value that names an environment variable (${FACILITY_TZ}) is checked by osprey health, not by the build. It is the facility’s zone and the one place OSPREY takes it from: the agent quotes times in it, and each page that shows times is stamped with it.

While you are in the modules.web_terminals: block, note the auth: stanza the preset ships: the terminals ask for a login, with demo passwords that osprey init seeded into this repository’s .env (alice/alice, bob/bob, and carol/carol, the admin card) and allow_insecure_http: true keeping the login flow on plain HTTP. That is a demo posture: osprey up refuses to start once deploy.fqdn names a real host while any of these passwords is still set. For a facility host, set real passwords in .env (or rotate with osprey users passwd) and serve TLS — Require a Login walks through both, and through single sign-on if your site runs one.

Nothing else in the block needs editing. Each tier a user names and each name under shared: is a file in tiers/, and osprey build renders every one to build/<project_name>-<name> (here build/demo-facility-readonly). Renaming the deployment moves every render with it, and there is no second copy of the name to keep in step.

Step 4 — Add the facility’s own container#

Declare the service, and the MCP server it serves. Replace the services: {} line and the commented mcp_servers: example with:

services:
  facility-mcp:
    template: services/facility-mcp
    config:
      port: 10900
      http: true

mcp_servers:
  facility:
    port: 10900
    transport: http
    permissions:
      allow: [machine_status]

template: is profile-relative, so the next thing to do is write that directory. http: true says this service answers HTTP on the port it publishes, so the deploy summary prints its address as a link rather than as a bare host:port — the framework recognises its own services by name and has no way to know what protocol sits behind yours. Leave it out for a service that speaks anything else; a link that cannot open is worse than no link. Were facility-mcp moved to the host network, its template would render the bind address into a variable and name it with bind_env:.

The port appears twice because it is the same fact told to two parties: the container publishes it, and the agent dials it. 10900 is the first port of the facility band, the hundred ports the framework publishes nothing in so that a facility’s own services can claim them without ever colliding — see The facility band.

Now create services/facility-mcp/ with four files.

requirements.txt:

mcp==1.9.4

server.py — a read-only tool over streamable HTTP. Nothing here imports OSPREY: the agent reaches this container by URL, so the framework never has to be installed alongside it.

"""Demo Facility's own MCP server: read-only machine-status lookups."""

from __future__ import annotations

import json
import os
from pathlib import Path

from mcp.server.fastmcp import FastMCP

STATUS_FILE = Path(os.environ.get("FACILITY_STATUS_FILE", "/data/machine-status.json"))

mcp = FastMCP("demo-facility", host="0.0.0.0", port=int(os.environ.get("PORT", "10900")))


@mcp.tool()
def machine_status() -> str:
    """Report the control room's current machine state and operating mode."""
    if not STATUS_FILE.is_file():
        return f"No machine status available ({STATUS_FILE} is not present)."
    return json.dumps(json.loads(STATUS_FILE.read_text()), indent=2)


if __name__ == "__main__":
    mcp.run(transport="streamable-http")

Note

Keep a facility tool like this read-only. Anything that writes to the machine belongs behind the control-system connector, which is the single interface every write goes through.

Dockerfile — a service directory that carries one earns its own image-build job in the pipeline:

# Registry standing in for docker.io; images.base_registry points it at a site mirror of Docker Hub.
ARG OSPREY_BASE_REGISTRY="docker.io"
FROM ${OSPREY_BASE_REGISTRY}/library/python:3.11-slim

WORKDIR /app

COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

COPY server.py ./

# Unbuffered so container logs appear as the server writes them rather than
# when the process exits.
ENV PYTHONUNBUFFERED=1
EXPOSE 10900

CMD ["python", "server.py"]

docker-compose.yml.j2 — the same channel every packaged service uses: one compose template per service directory, rendered by the build.

{%- import "services/_site_image_args.j2" as site -%}
services:
  facility-mcp:
    image: ${OSPREY_FACILITY_MCP_IMAGE:-{{ (services['facility-mcp'] | default({})).image | default(osprey_labels.project_name ~ '-facility-mcp:local') }}}
    build:
      # With multiple `-f` compose files every relative path resolves against
      # the FIRST file's directory — the compose project dir, not this file's
      # own subdir — so the context is the service directory by name.
      context: ./facility-mcp
      dockerfile: Dockerfile
{%- if site_image_build_args %}
      args:{{ site.build_args(site_image_build_args) }}
{%- endif %}
    # container_name is a HOST-GLOBAL identifier: namespace it per-project so
    # two OSPREY projects can run this service on one host.
    container_name: {{ osprey_labels.project_name }}-facility-mcp
    labels:
      # Env-chain hash: a .env edit restarts this; the build adds project and config labels.
      osprey.env.digest: "${OSPREY_ENV_DIGEST:-}"
    restart: unless-stopped
    ports:
      - "{{ deployment.bind_address | default('127.0.0.1') }}:{{ (services['facility-mcp'] | default({})).port | default(10900) }}:10900/tcp"
    environment:
      PORT: "10900"
      FACILITY_STATUS_FILE: /data/machine-status.json
      TZ: {{ system.timezone }}
    volumes:
      - facility_mcp_data:/data
    networks:
      - osprey-network
    healthcheck:
      test: ["CMD-SHELL", "python -c \"import socket,sys; s=socket.socket(); s.settimeout(3); sys.exit(0 if s.connect_ex(('localhost', 10900)) == 0 else 1)\""]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s

volumes:
  facility_mcp_data:
    labels:
      com.osprey.repo-id: "{{ osprey_labels.repo_id }}"

networks:
  osprey-network:

The named volume carries the checkout label itself because the build’s labels override reaches services, not volumes, and osprey reset removes only the volumes that carry it.

The image reference follows the framework convention — environment variable, then config key, then a local tag. A laptop deploy builds the image from the sources beside the template; the deploy host selects the pipeline’s pushed image by setting OSPREY_FACILITY_MCP_IMAGE. The last layer is this template’s own literal, so the stack-wide registry and tag axes do not reach it: to have a facility-owned image follow them, write the default with the same shape they produce. Container Deployment covers the template variables, the image chain, and those axes in full.

Step 5 — Fill in the deployment coordinates#

Two edits, and they belong together.

First, env: and the deploy: block. Replace the preset’s env.required list, and uncomment and fill in the deploy: block near the bottom of the file:

env:
  required:
    - DEMO_REGISTRY_TOKEN

deploy:
  ci: gitlab
  registry:
    url: registry.example.org/accelerator/demo-facility
    token_env_var: DEMO_REGISTRY_TOKEN
  host:
    name: demo-deploy
    fqdn: demo-deploy.example.org
    user: osprey
    project_path: /opt/demo-facility
  image_source: local

Substitute your own registry and host. registry.url carries no scheme — it appears verbatim inside an image name. host.name must be ssh-resolvable for whoever presses the deploy button, and host.project_path is where this repository is checked out on that server. Credentials are named here, never written here.

image_source: local says the deploy host builds the web-terminal images itself from the rendered login projects, rather than pulling them from a registry.

With registry, the host pulls them under names derived from this block’s registry.url, which the build writes into the rendered config. A registry.url in config: overrides it. The scaffolded pipeline does not push those images. The names and what has to push them: Pull the terminal images from a registry.

Important

In the same edit, delete the image_source: local line from the modules.web_terminals: block under config:. The deploy: block is that fact’s only home, and the build writes the value into the rendered config for you. Saying it in both places is refused by name — the two are free to disagree, and the disagreement decides whether the host builds images or pulls them.

A runner or deploy host with no route to Docker Hub names a site mirror of it under config:; leave the key out where Docker Hub is reachable:

config:
  images.base_registry: mirror.example.org/dockerhub

The pipeline’s job images, the base image of every image this repository builds, and the Docker Hub images osprey up pulls then come from it.

Step 6 — Add the secrets#

The profile owns this deployment’s secrets, so that is where they go.

Step 1 may already have written .env for you, seeded from a matching key your shell exports — it says so in its output. If that file does not exist yet, start from the documented list:

cp .env.example .env

Either way, edit .env and set ANTHROPIC_API_KEY (or the key for whichever provider your profile names) and DEMO_REGISTRY_TOKEN. The repository’s .gitignore keeps .env out of git.

The agent record’s credentials do not go in .env. Each login is minted into a file of its own, .env.agent-record.* at the repo root, mode 0600 and outside the .env chain: osprey build writes them, and osprey up adds a key file per reader. A later rebuild keeps them, so the stack comes up on the same credentials its volumes were initialized with.

.env.example is written by osprey init. After you change env.required, update the example alongside it — it is the documented list that whoever sets this up next will read.

Step 7 — Validate, then emit the deployment files#

osprey validate

A valid profile reports its name and its deploy target — Deploy: gitlab CI → osprey@demo-deploy. If anything is wrong, every problem is reported at once rather than one per run.

Now render the deployment files from the deploy: block:

osprey scaffold ci

Two files appear:

.gitlab-ci.yml

The pipeline, at the repository root. Its header lists the CI/CD variables the pipeline reads, which you set in your GitLab project settings, masked and protected: DEMO_REGISTRY_TOKEN (the registry credential named by your deploy: block) and OSPREY_DEPLOY_SSH_KEY, a File-type variable holding the private key for the deploy-host account. The SSH key is CI-only — it authenticates the deploy job and is never part of the deployment’s own environment, which is why it is not in env.required.

scripts/verify.sh

The post-deploy health check, at the repository root: every container of the deployment, then the endpoints it can probe.

Re-run osprey scaffold ci whenever the deploy: block changes. It is safe to re-run: a file whose content already matches is left untouched, and a file the scaffolder did not write is reported and left alone unless you pass --force.

ci-extra.yml, which osprey init created in Step 1, is the facility’s own include point. A job you add there runs beside the scaffolded ones; reusing a scaffolded job’s name merges the two and the scaffolded pipeline’s own keys win, so give a job of your own its own name. Nothing ever regenerates that file.

Step 8 — Build the project#

osprey build

Note

On a restricted network, read this before you run it. osprey build and the first osprey up fetch from the public internet: base images and Debian packages, the agent CLI from npm, OSPREY and its dependencies from PyPI, the web UI’s assets from a CDN, the search sidecar’s models from Hugging Face, and — at the graph store’s first start — a Neo4j plugin from GitHub. Each has a knob or a workaround, on its own page:

osprey build walks up to the repository’s profile.yml and renders build/ from it, from whichever directory inside the repository you run it. Watch for these lines in the output:

  • Injected 1 profile service(s) for deploy — facility-mcp was picked up.

  • Injected Virtual Accelerator soft-IOC (CA port 5064).

  • Persisted 1 MCP server(s) to config.yml — the agent can reach facility-mcp.

Confirm the service list is exactly the two you expect:

osprey config --rendered | grep -A4 '^deployed_services:'

It should read facility-mcp and virtual_accelerator; the record’s two services are rendered beside them.

Step 9 — Deploy and check#

osprey up -d

Note

Running OSPREY from a source checkout rather than a released install? Add --dev — osprey up otherwise refuses, because a container built from PyPI would run different code than your checkout, and --dev builds the image from the checkout instead; see Container Deployment for that workflow.

The first run is slow: the virtual accelerator and the facility’s own image are both built locally. When the containers are up, osprey up prints a summary of the published endpoints and, on a deployment with the web tier, runs scripts/verify.sh itself; without the web tier, nothing runs it for you.

osprey status

Read the lines above the status table first. A drift report there means build/ was rendered from an older profile than the one on disk now, and the fix is osprey build, not a restart.

You can run the health check by hand at any time, and it is worth doing once before you trust it:

./scripts/verify.sh              # every group
./scripts/verify.sh containers   # one group
./scripts/verify.sh --strict     # exit 1 if anything is flagged

It checks the deployment osprey up recorded in var/deployment.json; before the first osprey up it says nothing has been deployed.

It exits 0 unless run with --strict. A container that is not running or not healthy, and a probe that gets no answer, is flagged and tells you where to look. osprey up never passes --strict, so a flag is never the reason a deploy is called a failure; --strict is for a job of your own that should fail on it.

What the pipeline does#

The walkthrough above is the local path. The pipeline in .gitlab-ci.yml takes the same profile through three stages:

validate runs on every commit and needs no credentials. It runs osprey validate, then osprey build with --skip-lifecycle --skip-deps — CI has no container runtime for post-build hooks, and nothing there runs the agent, so its virtual environment would be dead weight. The render is published as an artifact so a reviewer can see exactly what the commit produces.

images builds one image per facility-owned service that carries a Dockerfile — here, just facility-mcp. The build context is the service directory in the source zone, not the rendered copy. Every build pushes a commit-SHA tag; only the default branch moves :latest, so a feature branch can never reach the deploy host by accident.

deploy is manual and default-branch only, serialized by a resource group so two operators cannot interleave on the host. It re-renders on the host from the same commit rather than unpacking the artifact, which is what makes the running stack reproducible from git alone:

osprey build
osprey users env --output .env.users
osprey up -d

osprey users env writes the env file every per-user web-terminal container runs with, from the deploy host’s own env chain — .env.shared then .env, with .env winning on any key both set. Passing --output is not optional: without it the command writes the assembled secrets to stdout, which in a pipeline is the job log. --output also creates the file at mode 0600 from its first byte, which a shell redirect would not.

Changing something later#

The loop is always the same: edit the profile, rebuild, redeploy. Run it anywhere inside the repository:

osprey set connector=epics                      # your control system; or edit profile.yml by hand
osprey set config.archiver.type=epics_archiver  # the archiver that records it
osprey set va_archiver=null                     # that store records the simulator
osprey build
osprey up -d

The three osprey set lines are the go-live edit, with EPICS as the example: connector names your control system (epics, doocs or tango) and config.archiver.type the archiver that records it (epics_archiver, doocs_archiver, mongodb_archiver or mya_archiver). Use Connectors lists each one and the keys it needs.

Or in one step, osprey up --build -d. Every build re-renders everything the framework owns and preserves what you own: .env, var/, and the repository’s git history. The source zone itself is never touched by a build.

If you changed the deploy: block, run osprey scaffold ci again first so the pipeline and health check match the new coordinates.

Renaming the deployment#

The deployment’s name on the host is project_name: in profile.yml, not the folder the repository sits in. Moving or renaming the folder changes nothing. Changing project_name: renames the deployment, and everything named from it follows: the compose project, the volumes, the images, the web containers and the login renders. Stop the stack under its old name first, because osprey down addresses the name the current build/ was rendered with:

osprey down
osprey set project_name=demo-control-room
osprey build
osprey up -d

Data does not move with the name. The volumes are named <project_name>_<volume>, so the renamed deployment starts on new, empty volumes, and the old ones stay on the host under the old name until you copy what you need and remove them.

Operating it#

Everything past “the stack is up” runs from anywhere inside the repository:

osprey status                  # what is running, where it answers
osprey logs event_dispatcher   # one service's output; -f to follow
osprey health                  # config, environment, providers, agent record
osprey restart                 # stop and start again
osprey down                    # stop it, keeping the volumes

osprey status reads and reports — it starts nothing and renders nothing — so it is safe against a live stack and is the right first command when something looks wrong. It also says whether build/ still matches profile.yml, which is the same check osprey up refuses on.

When the answer is not obvious from those, run them inside an OSPREY agent session in the repository: the agent reads the same output you do, and it has the deployment’s configuration and rendered files at hand.

Starting it again after a reboot#

Nothing so far survives the host restarting: the containers come back only when somebody runs osprey up -d again. osprey scaffold systemd writes a systemd user unit that does it for you.

osprey scaffold systemd

It writes osprey.service at the repository root — and, beside it, scripts/osprey-boot-hook.sh, covered below — and prints the commands that install the unit on this machine:

cp /path/to/repo/osprey.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now osprey.service

Run the scaffold verb on the machine that will run the deployment. Both the repository directory and the osprey program are written into the unit as full paths, because systemd starts a unit with no working directory and a short PATH — a unit generated on your laptop would name paths the host does not have. Run it again after the repository moves or OSPREY is reinstalled somewhere else. Re-running is otherwise safe: a unit whose content already matches is left untouched, stamp included, so an OSPREY upgrade alone produces no diff, and a file the scaffolder did not write is reported and left alone unless you pass --force.

If no osprey program can be found to name, the command refuses rather than writing a unit that points at nothing. Check that command -v osprey answers in the same shell — if OSPREY lives in a virtual environment, activate it and re-run.

One more step, and it is the one people miss:

loginctl enable-linger $USER

A user unit runs inside that account’s own systemd --user instance, which logind starts at login and tears down when the account’s last session ends. Without linger there is no user instance at boot, so the unit never runs, and it stops again the moment you log out. osprey up already enables linger by itself for a rootless-podman deployment running web terminals — rootless podman puts the containers themselves under that same user instance, so they need it too — but every other deployment needs the command run once by hand. On Docker hosts the containers run under the Docker daemon and are unaffected by linger; the unit that starts them is still a user unit, so it still needs it.

Check it the way you would check any unit:

systemctl --user status osprey.service
journalctl --user -u osprey.service -b

When the home directory is on a network mount#

Linger is not enough when $HOME is on NFS or autofs, and the scaffold verb says so: it reads the home directory’s filesystem type with findmnt and prints a warning beside the install commands. The lingering user manager starts at boot before that mount is there. It resolves its unit search path once, finds nothing, and does not look again — so after every host reboot the unit reads as not-found, and podman.socket with it, until somebody runs systemctl --user daemon-reload by hand. It looks like a broken unit and it is a mount-ordering problem.

When systemd manages the mount itself — an fstab entry, or a .mount or .automount unit — ordering the user manager after it is a drop-in on user@<uid>.service, which OSPREY cannot install for you because it needs root:

# /etc/systemd/system/user@<uid>.service.d/network-home.conf
[Unit]
RequiresMountsFor=/home/<account>
After=remote-fs.target autofs.service

Followed by sudo systemctl daemon-reload. The command prints that file with your own uid and home directory already filled in, ready to hand to whoever administers the host. On a local home — or on a host with no findmnt, where there is no way to tell — it prints nothing extra.

That drop-in does nothing for a home served by the autofs daemon (automount(8)): there is no systemd mount unit for RequiresMountsFor to order against, so the manager starts exactly as before. findmnt reports autofs for a systemd automount as well, so the command cannot tell the two apart — check systemctl list-units -t mount,automount for your home to know which you have. For a daemon-managed home, and for any host where nobody with root is available, the same run has already written the other route: scripts/osprey-boot-hook.sh, beside the unit. It waits for the home, the deployment and the user manager to appear, then reloads the unit files and starts the unit — the script an affected site otherwise ends up writing by hand. Wire it into the account’s own crontab with the lines the command prints, all of them, pasted whole:

crontab -e
SHELL=/bin/sh
HOME=/
@reboot d=/tmp/osprey-boot-hook.$(id -u); mkdir -m 700 "$d" 2>/dev/null; if [ -d "$d" ] && [ ! -L "$d" ] && [ -O "$d" ]; then log=/tmp/osprey-boot-hook.$(id -u)/boot.log; else log=/dev/null; fi; echo "$(date) osprey-boot-hook: cron fired" >> "$log"; n=0; until [ -x /path/to/repo/scripts/osprey-boot-hook.sh ] || [ $n -ge 120 ]; do sleep 5; n=$((n+1)); done; if [ -x /path/to/repo/scripts/osprey-boot-hook.sh ]; then exec /path/to/repo/scripts/osprey-boot-hook.sh; fi; echo "$(date) osprey-boot-hook: gave up, /path/to/repo/scripts/osprey-boot-hook.sh never appeared" | tee -a "$log"

The job is deliberately not a bare @reboot with the script’s path, because two things happen before a cron job’s command runs and each one kills the job silently on this kind of host. cron changes into the crontab’s HOME first and dies, with no mail, when that directory is not there yet — HOME=/ gives it one that is, SHELL=/bin/sh names the shell the job is written for whatever an existing crontab set above, and the script restores the real home as its first act. Then sh has to read the script, which sits on the same late mount; so the job, which lives in the crontab on the local disk, notes that cron fired it in /tmp/osprey-boot-hook.<uid>/boot.log and waits for the script to become readable before running it. That log is the first place to look after a boot that did not come back: it splits “cron never fired” from “still waiting for the home” from “the hook ran and said why”. Put the lines last in the crontab: every job below them runs from / and sees HOME=/ in its environment, so a job body that expands $HOME breaks silently unless it starts with its own export HOME=<the real home>.

Where the drop-in applies, the hook repairs each boot after the fact rather than ordering the manager correctly in the first place, so there it is a fallback, not a replacement.

osprey health reports this condition too: the systemd_unit category is error when the unit is installed but the user manager reports it not-found, warning when it was scaffolded but never installed, and a skip on any host without a scaffolded unit or a user manager.

Why the unit runs osprey and not compose#

The unit’s ExecStart is osprey up -d and its ExecStop is osprey down — not a compose command against the rendered files in build/. That is deliberate. A compose invocation started by systemd would have to reproduce, by hand and correctly, everything osprey up assembles around compose:

  • COMPOSE_PROJECT_NAME, pinned to the project name in the configuration rather than left to compose’s own fallback of the current directory’s name. It decides which containers, networks and volumes the command addresses; get it wrong at boot and the host quietly grows a second copy of the stack beside the one your volumes belong to.

  • OSPREY_ENV_DIGEST, a hash of the .env chain that the rendered files carry as a container label. It is what makes an edit to .env reach a running container. A compose run that left it unset would look like a changed document on every boot and recreate the whole stack for no reason.

  • The .env chain itself — .env.shared then .env — collapsed in the right order, and the repository pinned as compose’s project directory so it resolves those files at all.

  • The container runtime, which osprey up detects (or reads from the configuration) and then probes for the compose provider behind it; the supported providers do not take the same command line.

  • Everything that is not compose: the ownership check that refuses to start over containers another checkout of the repository created under the same project_name, the host-port check that refuses before it touches a container, the drift check that refuses when build/ no longer matches profile.yml, minting any missing service credentials into .env, the second compose invocation a multi-user deployment needs for its web tier, and scripts/verify.sh afterwards.

Wrapping the verb keeps all of that in one place: the unit is two commands, and a boot does exactly what you do by hand.

See also

Build Profiles

What lives in a profile, the convention directories, and taking ownership of a framework artifact.

Container Deployment

The container-deployment reference: service configuration, compose template variables, image overrides, and the --dev workflow.

Multi-User Support

The web tier this facility deploys — the landing page and one containerized terminal per operator.

Use the Virtual Accelerator

Running the simulator, and driving it from the agent.

Use Connectors

Every control system and archiver OSPREY connects to, and the keys each one needs.

CLI Reference

Every osprey command and flag.