Deployment Packages
rescile-ce package builds locked, offline-reproducible deployment packages (deb, rpm, Nix, flake) that bundle:
- the
rescile-eecontroller binary for one or more Linux architectures, - optional served binaries (for example
rescile-runnerorrescile-vault-appbuilds) exposed through the controller’s/binaries/<prefix>/<file>routes, - one or more modules, and
- a ready-to-enable systemd service (
rescile-ee.service) with itsrescilesystem user, tmpfiles rules, and an examplemodule.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 starterpackage.tomlfrom the module’smodule.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 writespackage.locknext 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 fetchre-verifies the existingpackage.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.--archis 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.editionmust be"ee"or"ce".- Exactly one source (
github/url/path) per binary and per module. githubbinaries requiretagandasset;tag/assetare rejected on other sources. Modulegithubentries taketagorcommit(full 40-char SHA-1), never both.urlsources must be HTTPS without embedded credentials or fragments; module URLs must point at a.zip,.tar.gz, or.tgzarchive.- Served targets require
serve_pathof the form/binaries/<prefix>/<filename>with safe single-level names, unique across all served products. The controller target cannot haveserve_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-cewithedition = "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-dirmodule.tomlwhose[dependencies]point at/usr/share/rescile/modules/<name>./usr/lib/systemd/system/rescile-ee.service— runsrescile-ee --data-dir /var/lib/rescile/data serve --watch --auth-file /etc/rescile/rescile-auth.tomlas therescileuser, with--runner --runner-labels …whenservice.runneris on, the--serve-binariesmounts, andVAULT_JSON_PATHwhenservice.vaultis on. Requires/etc/rescile/rescile-auth.toml(checked non-empty byExecStartPre) and/etc/rescile/rescile.env(EnvironmentFile)./usr/lib/sysusers.d/rescile.confand/usr/lib/tmpfiles.d/rescile.conf— create therescilesystem user and/var/lib/rescile/data, and seeddata/module.tomlfrom 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
INTERPsegment and noNEEDEDdynamic entries (checked withfile/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.