Operators Guide

Deployment Packages

Build locked deb, rpm, Nix, and flake deployment packages of the controller, served binaries, and modules with rescile-ce package.

Deployment Packages

rescile-ce package builds locked, offline-reproducible deployment packages (deb, rpm, Nix, flake) that bundle:

  • the rescile-ee controller binary for one or more Linux architectures,
  • optional served binaries (for example rescile-runner or rescile-vault-app builds) exposed through the controller’s /binaries/<prefix>/<file> routes,
  • one or more modules, and
  • a ready-to-enable systemd service (rescile-ee.service) with its rescile system user, tmpfiles rules, and an example module.toml.

Everything is pinned in a package.lock file. package build then works fully offline from a content-addressed local cache, so the artifact you ship is byte-for-byte the artifact that was fetched and verified earlier.

Workflow

# 1. Create a starter package.toml from a local module directory
rescile-ce package init --module-dir ./my-module

# 2. Edit package.toml (binary tags, served targets, modules), then prefetch
#    and pin every source in package.lock (requires network)
rescile-ce package update

# 3. On the build machine: verify all pins against the cache without
#    changing package.lock (requires network only for cache misses)
rescile-ce package fetch

# 4. Build offline from verified, locked inputs
rescile-ce package build --format deb --arch x86_64
rescile-ce package build --format rpm --arch aarch64
rescile-ce package build --format nix        # includes all controller targets
rescile-ce package build --format flake
  • package init --module-dir <DIR> [--output package.toml] writes a starter package.toml from the module’s module.toml (name, version) with the controller pinned to a GitHub release tag and commented examples for served runner binaries. It refuses to overwrite an existing file.
  • package update [--config package.toml] [--git-client auto|gh|git|internal] downloads every binary and module source, verifies it, stores it in the local cache, and atomically writes package.lock next to the config. Re-running it with an existing lock re-verifies that nothing changed — a changed locked input is a hard error, not a silent bump.
  • package fetch re-verifies the existing package.lock (filling cache misses) without modifying the lockfile. Use it in CI to prove the lock is still satisfiable.
  • package build --format <deb|rpm|nix|flake> [--arch x86_64|aarch64] [--output DIR] [--config package.toml] builds strictly offline from cache blobs. --arch is required for deb/rpm and must be omitted for nix/flake (those include every enabled controller target). The output filename for deb/rpm is <name>_<version>_<arch>.<deb|rpm>; nix/flake write to <output>/nix/ or <output>/flake/. Builds refuse to overwrite existing artifacts.

--offline is a global flag: package update/fetch reject it (they need network on cache misses); package build is offline by design and never touches the network.

package.toml reference

[package]
name = "acme-site"          # package name (safe chars: A-Za-z0-9._-)
version = "1.2.0"
description = "Acme Rescile deployment"   # optional
output = "dist"             # optional, default "dist"
edition = "ee"              # optional, default "ee"; "ce" packages rescile-ce instead

[outputs]
formats = ["deb", "rpm", "nix", "flake"]      # subset of deb, rpm, nix, flake
controller_targets = ["linux-amd64", "linux-arm64"]

# The controller binary installed as /usr/bin/rescile-ee. Exactly one source per target.
[controller.targets.linux-amd64]
github = "rescile/rescile-controller"        # owner/repo; requires tag + asset
tag = "v0.1.229"
asset = "rescile-ee-linux-amd64"
# ...or: url = "https://example.com/rescile-ee"   (HTTPS, no credentials)
# ...or: path = "./binaries/rescile-ee-linux-amd64" (local file, relative to package.toml)

[controller.targets.linux-arm64]
github = "rescile/rescile-controller"
tag = "v0.1.229"
asset = "rescile-ee-linux-arm64"

# Optional served binaries, downloadable at /binaries/<prefix>/<file> from the
# running controller. Each product has its own target map; serve_path is required
# and must be unique across all served products: /binaries/<prefix>/<filename>.
[served.runner.targets.linux-amd64]
github = "rescile/rescile-controller"
tag = "runner/v1.0.5"
asset = "rescile-runner-linux-amd64"
serve_path = "/binaries/tools/rescile-runner-linux-amd64"

[served.vault.targets.linux-amd64]
url = "https://releases.example.com/rescile-vault-app-linux-amd64"
serve_path = "/binaries/tools/rescile-vault-app-linux-amd64"

# One or more modules, installed to /usr/share/rescile/modules/<name>.
# Exactly one source per module.
[[modules]]
name = "acme-site"
path = "./my-module"                          # local directory
# ...or: github = "acme/acme-site" with exactly one of:
#          tag = "v1.2.0"  OR  commit = "<40-char SHA-1>"
# ...or: url = "https://example.com/acme-site.zip"  (must end .zip, .tar.gz, or .tgz)

[service]                    # all optional; defaults shown
runner = true                # start the built-in runner in the systemd unit
runner_labels = ["runner:builtin"]
vault = true                 # set VAULT_JSON_PATH=/var/lib/rescile/vault.json in the unit

Choosing the controller edition

edition = "ce" packages rescile-ce instead of rescile-ee: the binary installs as /usr/bin/rescile-ce, the systemd unit becomes rescile-ce.service running rescile-ce --data-dir /var/lib/rescile/data serve --watch (no --auth-file, no auth-file pre-check — CE has no server authentication), and the NixOS module exposes services.rescile-ce. Use edition = "ee" (the default) for authenticated deployments with rescile-ee.

Validation rules enforced at load time:

  • package.edition must be "ee" or "ce".
  • Exactly one source (github / url / path) per binary and per module.
  • github binaries require tag and asset; tag/asset are rejected on other sources. Module github entries take tag or commit (full 40-char SHA-1), never both.
  • url sources must be HTTPS without embedded credentials or fragments; module URLs must point at a .zip, .tar.gz, or .tgz archive.
  • Served targets require serve_path of the form /binaries/<prefix>/<filename> with safe single-level names, unique across all served products. The controller target cannot have serve_path.
  • Names, versions, labels, refs, and route components are restricted to safe character sets.

package.lock and the local cache

package update writes package.lock next to package.toml:

version = 1
config_sha256 = "…"           # hash of package.toml; build fails if config changed

[binaries."controller/linux-amd64"]   # also "served.<product>/<target>"
sha256 = "…"

[modules.acme-site]
sha256 = "…"                  # tree digest of the module files
commit = "…"                  # git sources only
archive_sha256 = "…"          # archive sources only

Fetched bytes are stored content-addressed under the package cache ($RESCILE_PACKAGE_CACHE, else $XDG_CACHE_HOME/rescile/package or ~/.cache/rescile/package) as blobs/<sha256> with 0700 directories and 0600 files; symlinks in the cache path are rejected. package build re-hashes every blob it reads and verifies the module tree digest against the lock, so a corrupted or swapped cache file fails the build instead of shipping.

What a deb/rpm package contains

Built with nfpm (required on PATH, together with nix for nix/flake outputs and the gh CLI for GitHub sources):

  • /usr/bin/rescile-ee (or /usr/bin/rescile-ce with edition = "ce") — the locked controller binary, installed executable.
  • /usr/share/rescile/binaries/<prefix>/<file> — each served binary, and the systemd unit passes --serve-binaries <prefix>=/usr/share/rescile/binaries/<prefix> so the controller serves them under /binaries/<prefix>/….
  • /usr/share/rescile/modules/<name>/… — each module’s files, and /usr/share/rescile/module.toml.example, a ready-made data-dir module.toml whose [dependencies] point at /usr/share/rescile/modules/<name>.
  • /usr/lib/systemd/system/rescile-ee.service — runs rescile-ee --data-dir /var/lib/rescile/data serve --watch --auth-file /etc/rescile/rescile-auth.toml as the rescile user, with --runner --runner-labels … when service.runner is on, the --serve-binaries mounts, and VAULT_JSON_PATH when service.vault is on. Requires /etc/rescile/rescile-auth.toml (checked non-empty by ExecStartPre) and /etc/rescile/rescile.env (EnvironmentFile).
  • /usr/lib/sysusers.d/rescile.conf and /usr/lib/tmpfiles.d/rescile.conf — create the rescile system user and /var/lib/rescile/data, and seed data/module.toml from the example.
  • postinstall/postremove scripts register the user, create tmpfiles, and reload systemd.

After install, configure /etc/rescile/rescile.env (and /etc/rescile/rescile-auth.toml for the EE edition), then systemctl enable --now rescile-ee (or rescile-ce).

Nix and flake outputs

package build --format nix writes dist/nix/ containing one payload per enabled controller target (payload/x86_64-linux/…, payload/aarch64-linux/…), a package.nix (a stdenvNoCC.mkDerivation installing bin/rescile-ee — or bin/rescile-ce with edition = "ce" — and share/rescile/…), and a module.nix — a NixOS module (services.rescile-ee, or services.rescile-ce for the CE edition) that wires the package, user, tmpfiles, and the same systemd unit with configurable dataDir, authFile, and environmentFile.

--format flake writes dist/flake/ with package.nix, a flake.nix exposing packages.<system>.default for all systems derived from controller_targets, and a pinned flake.lock. Build with nix build ./dist/flake (or nix build ./dist/nix#… after importing package.nix); enable the service with services.rescile-ee.enable = true; (or services.rescile-ce.enable = true; for the CE edition).

Binary and module verification

Every locked binary is verified before it enters the lock and again at build time:

  • Linux targets must be static, stripped ELF of the right machine type (amd64 = EM_X86_64, arm64 = EM_AARCH64), with no INTERP segment and no NEEDED dynamic entries (checked with file/readelf).
  • Windows targets must be PE executables of the right architecture; macOS targets 64-bit Mach-O of the right CPU type.

Modules are hashed as a tree digest over all files (relative path + contents). The digest excludes runtime/state directories and files (.git, node_modules, tests, __pycache__, .rescile, data, .ready, vault.json, secrets.json, .env*), and any symlink inside a module fails the hash. This keeps customer secrets and local state out of packages while still pinning every authoring file.

CI pattern

# In CI, on the machine that prepares releases:
rescile-ce package update                       # once, when inputs change; commit package.lock
rescile-ce package fetch                        # gate: lock still verifiable
rescile-ce package build --format deb --arch x86_64 --no-progress
rescile-ce package build --format flake --no-progress
# Upload artifacts from ./dist (or --output) — builds never touch the network

See CLI reference for the flag list and Binary file serving for the /binaries/… URL scheme that served package binaries are exposed under.