Skip to content

DEPLOYMENT_CONTRACT.md

Latest commit

 

History

History
94 lines (68 loc) · 2.87 KB

DEPLOYMENT_CONTRACT.md

File metadata and controls

94 lines (68 loc) · 2.87 KB
Raw

Deployment Contract

Required repository files

flake.nix
flake.lock

Nix Ship refuses an unlocked production deployment. The lock file is the reproducibility boundary for external flake inputs.

GitHub sources are materialized from an exact Git commit. Harbur sources are materialized from an immutable ZIP whose revision and compressed content are the same SHA-256 digest. Both paths must produce this locked flake layout before evaluation.

The flake is the locked, standard Nix entry point rather than a development-only file. Nix Ship evaluates only the flake output; it never executes a loose Nix file or dashboard-provided command.

Required output

Preferred:

apps.${system}.default = {
  type = "app";
  program = "${package}/bin/application";
};

Named outputs are supported and selected as .#name in the dashboard.

Runtime rules

The executable must:

  • stay in the foreground;
  • exit non-zero on unrecoverable failure;
  • write logs to stdout/stderr;
  • use the injected HOST and PORT for web applications;
  • store mutable durable data under DATA_DIR;
  • avoid privileged ports, systemd, Docker, KVM, kernel modules and root-only paths.

Injected variables:

MANAGED_DEPLOYMENT=1
APP_ID
APP_NAME
DEPLOYMENT_ID
RELEASE_DIR
DATA_DIR
CACHE_DIR
LOG_DIR
HOST=127.0.0.1
PORT=<candidate port>   # web apps only

User-defined variables cannot replace reserved names.

Environment inheritance

Nix Ship does not copy the complete control-plane environment into an application. It retains only a reviewed compatibility set for locating Nix, basic user identity, temporary files, locales, TLS certificates, a configured Nix daemon and Nix-on-Droid runtime paths. Variables such as PLATFORM_*, provider credentials, agent sockets, NIX_CONFIG, NODE_OPTIONS, preload hooks and arbitrary host values are not inherited.

Environment precedence is compatible host values, then variables explicitly stored for the application, then the runtime variables listed above. Owners may deliberately configure HOME or PATH; runtime-owned names are rejected.

The compatibility set is operational support for the Nix launcher, not an additional application API. Applications should rely only on their configured variables and the documented runtime variables.

Invocation

nix flake metadata --json
nix flake show --json
nix run --no-write-lock-file .#<output>

Nix Ship passes arguments as an array and does not construct a user-controlled shell command.

Health

A web deployment activates when its configured path returns HTTP 200–399 before the startup timeout. Redirects are not followed. A worker activates after remaining alive through the configured stability window.

Trust

The flake can execute arbitrary build and runtime code as the Nix Ship OS account. Do not import untrusted repositories. Nix evaluation and the Nix store are not application isolation.