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 initEditing 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 ciRendering 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 |
|---|---|---|
|
packaged |
Keeps the agent record: what the agent was asked, what it answered and what it did (The Agent Record). |
|
packaged |
The ClickHouse store the record is kept in, from the preset’s
|
|
packaged |
A containerized simulator with LUME-backed physics (Virtual Accelerator), serving EPICS Channel Access on port 5064 and standing in for the real machine. |
|
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 |
Give the deployment its own DNS name at the front proxy
( |
One origin |
Every terminal accepts a state-changing request only from the one
origin the deployment was built for: |
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 |
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 |
Run a second deployment for the next group of users, on its own
|
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:anddispatch: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-plansandbluesky-plans.from
agents:—logbook-searchandlogbook-deep-research. Both query a logbook database at runtime, and this facility does not deploy one.for the same reason, the
logbookline undermodules.web_terminals.sharedinconfig:, plustiers/logbook.yml. That card is the shared logbook login, and it needs the logbook database this facility does not run. Theknowledgelogin stays: it reads the graph store this facility keeps.from
web_panels:—ariel,eventsandbluesky.from
config:— theclaude_code.servers.bluesky.enabledline and everyweb.panels.events.*andweb.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.ymlThe 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 yourdeploy:block) andOSPREY_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 inenv.required.scripts/verify.shThe 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:
a proxy, an internal package index, and a CA for a proxy that re-signs TLS: The Project Image (the
images.*build argsosprey uppasses) and Environment Variables (the .env chain) (the proxy names the containers themselves are handed);web assets bundled into the image instead of served from a CDN: the top-level
offlinekey, also on The Project Image;images pulled from your own registry rather than built here: Deploying Prebuilt Images;
the search sidecar’s models, staged on the host: Prefetched Models for the Search Sidecar;
the graph store’s plugin, which has no knob — see Search the Facility Graph.
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-mcpwas picked up.Injected Virtual Accelerator soft-IOC (CA port 5064).Persisted 1 MCP server(s) to config.yml— the agent can reachfacility-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.envchain that the rendered files carry as a container label. It is what makes an edit to.envreach 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
.envchain itself —.env.sharedthen.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 updetects (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 whenbuild/no longer matchesprofile.yml, minting any missing service credentials into.env, the second compose invocation a multi-user deployment needs for its web tier, andscripts/verify.shafterwards.
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
--devworkflow.- 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
ospreycommand and flag.