Skip to content

Preflight

The check that runs before compose up. One command, no flag to skip a check. The plan for the rules is cited in deployment/preflight/index.ts. This page lists what the code on this tree checks.

Owns

deployment/preflight/. The CLI is index.ts. The stack wrapper is stack.ts. The parser is compose-parse.ts (yaml 2.9.1, parseAllDocuments). Env values are held in secret-map.ts. printable.ts is what a line may contain.

index.ts exit codes: 0 when every check passes, 1 when one fails, 2 when the inputs cannot be read. A throw is a failure. C3, C4, C5 and C24 are network: true and fail after 30 s (NETWORK_TIMEOUT_MS). C18 is network: true too, with its own deadline of ten minutes (timeoutMs on the check, ADAPT_TIMEOUT_MS), since it pulls or builds the edge image. Each check is handed the outcomes of the checks before it. A reason that contains a configured value is replaced with a fixed withheld line. Output is one PASS, FAIL or UNSIGNED line per check. UNSIGNED is only a pass (verdict in index.ts). Under --env local the run appends LOCAL_LAST_LINE: LOCAL unsigned, local-only stack: never deploy it. Under --source the run appends SOURCE_LAST_LINE: SOURCE built from the checkout, unsigned: staging only. --source is refused unless --env is dev (inputs.ts), so a run appends at most one of those lines. C3, C4 and C5 still verify the lock under --source. They return UNSIGNED only under local.

ENVS in inputs.ts is dev, prod and local. There is no prod compose file and no deployment/networks.prod.json.

Checks, in CHECKS order (deployment/preflight/checks/index.ts). LOCAL_CHECKS (L1, L2) run only under --env local, after the others.

IdFileWhat the check requires
C1checks/stack.tsname is unset- plus --env.
C2checks/images.tsDev and prod without --source: no build, and every image is ghcr.io/undefined6799/… by digest and in deployment/images.lock.json. Under --env dev --source: a service may build, with no image beside it, when C26 passes; a service that names an image keeps the lock rule. Local: a build C26 accepts, a run-only vendor image by tag and digest, or the token reader on the node base with network_mode: none and profile tools.
C3checks/images.tsFirst-party lock entries verify. Local returns UNSIGNED.
C4checks/images.tsUpstream lock entries verify. Local returns UNSIGNED.
C5checks/images.tsEvery lock digest is an OCI index or a Docker manifest list. Local returns UNSIGNED.
C6checks/pds.tsPDS_RECOVERY_DID_KEY is set and isAtprotoDidKey accepts it (secp256k1 or P-256 did:key).
C7checks/pds.tsPDS_INVITE_REQUIRED is true. Outside prod, PDS_CRAWLERS is empty. PDS_ADMIN_PASSWORD length is at least 32. PDS_RATE_LIMITS_ENABLED is false.
C8checks/pds.tsNo name starting PDS_RATE_LIMIT_BYPASS_ in any service environment.
C9checks/secrets.tsEach secret file the stack reads exists and is non-empty. Compose-read files are mode 0600 and owned by the deploy user. Mounted file secrets are mode 0400 and owned by the service uid, inside a 0700 directory. None of them resolve inside the project directory.
C10checks/stack.tsUnder dev, no service publishes a port. Otherwise only edge publishes 80 and 443, and every other published port binds 127.0.0.1.
C11checks/pds.tsPDS_EMAIL_SMTP_URL is smtps: or smtp: with a single requireTLS=true, and is not Mailpit. PDS_EMAIL_FROM_ADDRESS passes fromAddressProblem. Local: both names absent.
C12checks/pds.tsIf LOG_ENABLED is set, it is false. If LOG_LEVEL is set, it is info, warn, error, fatal or silent.
C13checks/settings.tsPDS_LEXICON_AUTHORITY_DID is unset.
C14checks/settings.tsNo name containing DEV_MODE, and no PDS_ name containing DISABLE, except PDS_EMAIL_DISABLE_CONFIRMATION_LINK when the value is true.
C15checks/settings.tsPDS_SERVICE_HANDLE_DOMAINS is set, is not .0x40.me, is exactly .staging.unset.name under dev, and under local is under the PDS .localhost host.
C16checks/settings.tsPDS_EMAIL_DISABLE_CONFIRMATION_LINK is true.
C17checks/networks.tsNo network_mode except none on pds-token-reader in profile tools. Membership matches deployment/networks.dev.json or, under prod, deployment/networks.prod.json, with the local-only and dev-only rows in local-only.ts.
C18checks/edge.tsLocal: the built edge’s mounts and secrets are the local set, each site file mounted once from its own file (siteMountsProblem). Dev and prod: the edge serves the PDS host. Without a build it runs the lock’s edge image. Under --env dev --source, an edge that builds must be deployment/edge/Dockerfile, a build C26 passes, and no image beside it (runsBuilt in checks/build.ts); the lock ref is not what that service runs. Dev also requires PDS_HOST staging.unset.ac and web’s PUBLIC_ORIGIN host to be the dev app host. Under dev the two sites are dev/app.caddy and dev/pds.caddy; under prod the sites folder is sites/ or inside it. C18 reads the Caddyfile format nowhere itself (P1.39e). The edge service’s environment may hold only the five placeholder names (ENV_NAMES), from environment or an env file, since caddy adapt is handed those names only. checks/edge-adapt.ts first judges the edge’s values (envProblems), then runs caddy adapt in the edge image (the lock’s reference by digest after docker pull, only when C2 to C5 passed; or the edge’s own build by docker build -q, only when C26 passed in this run, so C18 runs and prints after C26), with --pull never --network none --read-only --cap-drop ALL --cap-add NET_BIND_SERVICE --security-opt no-new-privileges --user 65532:65532 (ADAPT_RUN_FLAGS in deployment/edge/adapted.ts, which adapted.image.test.ts also runs), the edge’s read-only /etc/caddy binds and its values by name (-e NAME). The output must be JSON, equal deployment/edge/adapted/<env>.generated.json (reviewedDifference) and pass adaptedProblems. Failures are fixed words.
C19checks/settings.tsModeration mail under the C11 TLS rule, and PDS_MODERATION_EMAIL_ADDRESS passes fromAddressProblem. Local: both names absent.
C20checks/settings.tsNo name starting PDS_MOD_SERVICE_.
C21checks/host.tsUnder dev, one fixed skip line (C21_DEV_WAIVER). Otherwise, if PDS_HOSTNAME is 0x40.space, docs/human/retirement/retirement-check.json has retirement_part_a_complete: true. Any other host skips.
C22checks/settings.tsLocal and dev: PDS_BLOB_UPLOAD_LIMIT is 5242880, PDS_BLOBSTORE_DISK_TMP_LOCATION is unset, and the PDS tmpfs is /tmp with size=20m. When VIDEO_MASTER_MAX_BYTES is set, the upload limit is an integer at least that large.
C23checks/settings.tsProd: some service sets FINGERPRINT_CHECK to arachnid, and no service sets FAKE_FINGERPRINT_LIST. Other envs skip.
C24checks/host.tstimedatectl reports NTPSynchronized=yes. When chronyc tracking runs, the offset is at most 1 second. A PDS_HOSTNAME ending in .localhost skips.
C25checks/capabilities.tsA service with cap_add runs the edge. Under local, and under --env dev --source when that service builds, runsBuilt (checks/build.ts) requires deployment/edge/Dockerfile, a build C26 passes, and no image beside it. Otherwise it runs the lock’s edge ref. Under dev, lockOrNone still reads deployment/images.lock.json.
C26checks/build.tsEach build’s Dockerfile is one scripts/ci/list-dockerfiles.ts discovers, the context is the one that workflow uses, and the context does not reach the secrets folder, the dev CA folder, or an env file.
C27checks/build.tsA tmpfs on /var/run/postgresql is only on the service that runs the postgres image.
C28checks/pds.tsPDS_DID_PLC_URL is set and is https://plc.directory.
C29checks/local-only-keys.tsDev and prod: no LOCAL_ONLY_KEY_NAMES key, and each origin key is https:. Local skips.
C30checks/pds.tsThe pds service has one env file. Its names are the four PDS_ENV_SECRETS, plus the two mail URLs under dev and prod, plus the store’s key pair PDS_STORE_KEYS under local and dev. Those names are not also set in the compose environment.
C31checks/newt.tsDev requires a newt service. Its one env file holds PANGOLIN_ENDPOINT, NEWT_ID and NEWT_SECRET. Compose environment is the six NEWT_SETTINGS literals. No mount and no secret. Outside local it runs the lock’s newt ref. Local may omit it.
C32checks/placeholders.tsDev and prod: no environment value starts with [to fill:. Local skips.
C33checks/settings.tsLocal and dev: the PDS keeps blobs in the object store’s unset-pds bucket at http://objects:8333, path style, region us-east-1, with its key pair set, no disk blobstore key and no AWS_ variable. Prod skips until P5.01.
C34checks/placeholders.tsEvery name the Compose files interpolate has a non-empty value in the interpolation env file, so a setting a new step adds stops the deploy here, not the service at boot.
C35checks/review.tsEvery stack: the review service, and any service built from review.Dockerfile, joins only review_web, which is internal and holds web and review alone; it reads no secret, env file or mount, sets only the settings it reads as literals, and runs read-only with every capability dropped and no new privileges. A stack with no review passes (ADR 0070 point 2.2).
L1checks/local.tsEvery published port binds 127.0.0.1.
L2checks/local.tsPDS_HOSTNAME matches a .localhost name.

C3 and C4 call inputs.verify, which runs node scripts/ci/verify-images.ts <lock> --trusted-root deployment/sigstore/trusted_root.json (inputs.ts). The cosign binary is deployment/preflight/cosign.ts: /usr/local/bin/cosign, v3.1.3. The preflight does not import scripts/.

scripts/dev-precheck.ts is the child stack.ts runs before Compose. Its header says it refuses a production PDS host (PRODUCTION_HOST is unset.ac) and a foreign describeServer DID, then runs this preflight, and creates no account. preflightFlags adds --source only when the wrapper passed it.

May import

The deployment-preflight row. dependency-cruiser 18.7.0 is pinned in package.json. An edge no row lists fails as not-in-allowed.

FromMay reach
deployment/preflight/deployment/preflight/, deployment/edge/adapted.ts, deployment/edge/adapted-rules.ts, shared/host-pin/index.ts, npm package yaml (2.9.1), Node built-ins.

stack.ts imports hostWalk, localDockerHost and UsageError from @unset/shared-host-pin. checks/build.ts and checks/secrets.ts import resolveChecked and the walk reasons from the same package index.

edge-not-preflight: nothing under deployment/edge/ imports this folder. Tests are the tooling row and are not this row. The rest of the boundary is on deployment.

Entry points

node deployment/preflight/index.ts -- --env dev|prod|local --compose <absolute file> [--compose <absolute file>...] [--interpolation-env <absolute file>] [--source]
node deployment/preflight/stack.ts -- up|down --env dev|local --compose <file> [--compose <file>...] --interpolation-env <file> [--source]

CLI_OPTIONS in deployment/preflight/inputs.ts and WRAPPER_OPTIONS in deployment/preflight/stack.ts are env, compose, interpolation-env and source. scripts/dev-precheck.ts CLI_OPTIONS is the same four. No name starts with env-file, require or import. The commands put -- before those flags. index.ts and stack.ts cite Node v26.10.0 for why. .nvmrc is 26.12.0. --source is a boolean, at most once, and only with --env dev, in all three parsers.

stack.ts CHILD_ENV_NAMES is PATH, HOME, DOCKER_CONFIG and DOCKER_CERT_PATH. childEnv also sets NODE_OPTIONS to empty and DOCKER_HOST from localDockerHost. A COMPOSE_* variable in the caller’s environment is refused. up passes --build when --env is local or --source was given, and --no-build when --env is dev without --source. up under local then runs served-leaf.ts. down does not pass -v. --source on down is accepted under dev and is not passed to Compose (plan).

The npm run scripts are on compose.

Data

Reads, and does not own:

PathUsed by
deployment/images.lock.jsonC2, C3, C4, C5, C18, C25, C27, C31
deployment/images/bases.lock.jsonC2 under local
deployment/sigstore/trusted_root.jsonC3, C4
deployment/networks.dev.json or deployment/networks.prod.jsonC17. Local reads the dev file.
RETIREMENT_REPORT in deployment/preflight/inputs.tsC21, when the host is 0x40.space. The constant is docs/human/retirement/retirement-check.json.
compose file, interpolation env, secret filesthe inputs

No schema, role or table. Configured values stay in SecretMap and are not printed.