Recipes

A recipe is one complete way to run an application in an Orbit slot. It implements the hook contract for a specific runtime: a container engine, a service manager, or another process model that the project already uses.

Hooks define when Orbit calls the project. A recipe defines what those calls do. The Hooks page is the contract. This page is the catalog of implementations.

Read the Guide and add ops/deploy.sh before you follow a recipe. The recipe does not replace host setup, slots, or orbit env.

What a recipe owns

Every recipe implements the same three hooks, or explains why a hook is absent:

• ops/deploy.sh builds or installs the new version, starts it, checks it, and publishes it.

• ops/status.sh reports whether that published version is healthy.

• ops/down.sh stops the application and removes runtime files.

A recipe also decides how the application reads $SLOT_ENV, where it writes durable data under $SLOT_DATA, and how it publishes a socket or unit under $SLOT_RUN.

Orbit does not contain runtime-specific logic. Two projects can share the same slot layout and use different recipes.

Current recipes

• Podman builds an image on the host, starts a new container, checks it through a Unix socket, then switches Caddy to that socket.

Add another recipe when a second runtime needs its own hook files. Keep each recipe on its own page. This page stays the index.

Other runtimes

Docker and systemd are the usual next recipes. They are not written as step-by-step pages yet. The shape below is the work those pages would own. Until they exist, implement the same hook contract and follow the Podman sequence as a model.

Docker

A Docker recipe looks like the Podman recipe: build an image, start a container on a release-specific socket, check that socket, then point a stable socket at the healthy release.

The commands change (docker build, docker run, docker stop). The hook boundary does not. Use $SLOT_DEPLOY_ID to name the image and container, and keep $SLOT_DATA and $SLOT_ENV outside the image.

systemd

A systemd recipe starts a process or a user service instead of a container. A typical deploy hook would:

1. Install or compile the new version into $SLOT_SRC or a release directory under $SLOT_RUN.

2. Write or update a unit that sets EnvironmentFile= to $SLOT_ENV.

3. Start or restart the unit.

4. Check the application through its socket or HTTP port.

5. Reload Caddy when the application is an HTTP service behind the prepared proxy.

ops/down.sh stops the unit. ops/status.sh asks systemd whether the unit is active, or checks the same socket the unit publishes.

Do not put secrets in the unit file. orbit env already stores them at $SLOT_ENV.

Writing a new recipe

Start from the hook lifecycle, not from the runtime's happy path:

1. Name the release with $SLOT_DEPLOY_ID so a failed deploy can leave the previous release in place.

2. Keep durable data in $SLOT_DATA and application settings in $SLOT_ENV.

3. Publish one stable entry point under $SLOT_RUN for status, Caddy, or both.

4. Make ops/deploy.sh idempotent. A second deploy of the same source must be safe.

5. Make ops/down.sh find the application from slot labels or stable paths, not from a remembered deploy ID.

When the recipe is complete, add it to the list on this page.