Package reference
Mirrors the package README (single source). Install @basaltkit/deploy v0.10.1 — npm · source.
@basaltkit/deploy
One deploy pipeline for a Basalt app on a single Linux server: the .env, dedicated Docker infra (Postgres, Redis, SeaweedFS for S3), PM2, Apache, a database dump before migrating, a health check, and a rollback when the new release does not answer. Design and decisions: RFC 0006RFC 0007 and RFC 0010 (object storage).
pnpm add -D @basaltkit/deployIllustrated guide: Deploying to a server walks through a first server, everyday deploys from the terminal and the local UI, with screenshots and a troubleshooting table (Português).
The config
deploy.config.ts at the app root, committed. It holds no secrets. basalt-deploy init --domain=<host> writes it from the project:
| Read from | Fills |
|---|---|
src/env.ts (as text — the app is not loaded) | the typed defineDeploy<typeof env>; generate for each secret() the app mints, ask for each required key and each provider-issued secret (S3, API, SMTP…) |
package.json, prisma.config.ts, prisma/tenants/ | app, build.prisma, migrate (central/tenants, or command: ['pnpm', 'db:deploy'] when that script is the app's own) |
web/package.json | build.web |
a production compose file whose images are variables (image: ${APP_IMAGE}) | runtime: compose(…): one image per variable (Dockerfile from build:, else docker/<name>/Dockerfile), the service on 127.0.0.1 as upstream |
| otherwise | runtime: pm2(), infra: dockerInfra(app) for the DATABASE_URL, REDIS_URL, S3_* keys the schema has |
--server, on the server | the Apache vhosts that already serve the domain (managed: false), the ports taken (avoid) |
It asks the domain, the tenancy and the branch (or takes --domain, --tenants, --branch, --proxy), never overwrites a config (--force), and runs check on what it wrote.
Every option, its default and an example: the deploy.config.ts reference (Português).
import { apache, ask, defineDeploy, dockerInfra, pm2, secret } from '@basaltkit/deploy'
export default defineDeploy({
app: 'acme', // names everything it owns: acme-api, acme-pg, …
domain: 'acme.example.com',
tenants: 'subdomain', // also checks the *.domain certificate and DNS
branch: 'master',
env: {
schema: 'src/env.ts', // your defineEnv(): the .env is validated against it
fixed: { NODE_ENV: 'production', HOST: '127.0.0.1' },
generate: { APP_SECRET: secret(32) },
ask: {
MAILER_URL: ask.secret('SMTP URL', { optional: true }),
PAYCO_SECRET_TOKEN: ask.secret('PayCo token'),
},
derive: ({ domain }) => ({ PAYCO_CALLBACK_URL: `https://${domain}/api/webhooks/payco` }),
forbid: ['PAYCO_FAKE'],
},
infra: dockerInfra('acme', {
postgres: { urlParams: { schema: 'public' } },
seaweedfs: { buckets: ['acme-documents', 'acme-backups'] }, // S3_ENDPOINT, S3_ACCESS_KEY, S3_SECRET_KEY
}),
build: { prisma: ['prisma.config.ts', 'prisma/tenants/prisma.config.ts'], web: 'web' },
migrate: { central: true, tenants: true },
runtime: pm2({ avoid: [3000, 3001] }), // runs the package.json "start" script, with the .env loaded
proxy: apache(), // web/dist at /, /api/ → the app
})pm2() gives the app its env.file without handing the values to pm2: the process gets the file's path and a preload that loads it inside the app's own processes only, so neither the pm2 daemon nor pm2 save's dump ever holds a secret. An exported NODE_ENV/PORT/HOST still wins over the file. pm2({ loadEnv: false }) turns it off for an app that loads its environment itself.
What is true of one server only (a port taken there, another branch) goes in /etc/basalt/<app>.json: { "port": 3002, "infra": { "postgres": { "port": 5434 } } }.
Typed by your env
Give defineDeploy the type of your defineEnv(...) and every .env key the config names is completed and checked — env.fixed, generate, ask, derive, backup.urlKey, the infra urlKeys, migrate.env. Values follow the schema: a z.enum completes its members, a number takes digits, a boolean 'true' | 'false'.
import type { env } from './src/env.js' // type only: the app is never loaded
import { defineDeploy } from '@basaltkit/deploy'
export default defineDeploy<typeof env>({
env: { fixed: { NODE_ENV: 'prod' } }, // ✗ '"prod"' is not assignable to '"development" | "production" | "test"'
backup: { urlKey: 'DATABSE_URL' }, // ✗ … Did you mean '"DATABASE_URL"'?
// …
})Without the type argument every key is a plain string, as before. basalt-deploy check runs the same checks without a server — the config's own validation, then your tsc on deploy.config.ts with your tsconfig — so CI catches them too.
On a new server
A fresh Ubuntu or Debian with Node, three commands. Root runs its own copy of the tool, pinned to the exact version your lockfile records (here 0.5.0), from outside the checkout — never the checkout's node_modules, which the app user can change (who runs what):
sudo adduser --disabled-password myapp && sudo git clone <repo> /srv/myapp
cd / && sudo -H npx --yes --package=@basaltkit/deploy@0.5.0 -- basalt-deploy bootstrap --dir=/srv/myapp --user=myapp # --dry-run first
sudo -u myapp -H sh -c 'cd /srv/myapp && node node_modules/@basaltkit/deploy/dist/bin.js run' # as myapp, from then onbootstrap installs only what is missing — base packages, Docker with compose, Node at engines.node (NodeSource), the pnpm the lockfile records — gives the checkout and the docker group to the user (said plainly: that group is root on the machine; rootless Docker is a later step), then, as the user, in the checkout: pnpm install, env (it asks what it cannot generate) and install-plan. From that plan (data, validated) it installs the app's system packages, adds swap when RAM is under 6 GB (bootstrap.swapGb), ufw with SSH and 80/443 (turned on only when nothing else listens; --no-firewall), Caddy when the proxy is caddy(), and runs install. It never loads deploy.config.ts itself. A step that fails stops it; running it again redoes nothing done. It warns when the lockfile records another @basaltkit/deploy version than the one running.
--dir is required and is never taken from the working directory (root runs from cd /): it must be an absolute path with no link in it, holding package.json and .git, and not a system directory (/, /etc, /home, /srv, /usr/…, /var/lib/…). Giving the checkout to the user (chown -R) asks first. The user's steps never run on root's terminal: pnpm install and install-plan in a new session (setsid -w, no controlling terminal), env in a terminal of its own (script, which root runs). Without that, on sudo < 1.9.14 with a kernel < 6.2 (Debian 12, Ubuntu 22.04) a postinstall script could type into root's shell (TIOCSTI). A Ctrl-C stops bootstrap, not a step already running in its own session.
By hand, the same thing:
# as the app user (never root), in the checkout:
pnpm install
node node_modules/@basaltkit/deploy/dist/bin.js env # writes the .env (asks once), starts the containers, validates
node node_modules/@basaltkit/deploy/dist/bin.js install-plan # writes the install plan (data) and prints the root command
# once, as an administrator — the command install-plan printed, e.g.:
cd / && sudo -H npx --yes --package=@basaltkit/deploy@0.5.0 -- basalt-deploy install --plan=/srv/myapp/.basalt/install-plan.json --user=myapp
# then, every deploy, as the app user:
node node_modules/@basaltkit/deploy/dist/bin.js runWrap it in a two-line deploy.sh if you like. Run it with node, not pnpm exec basalt-deploy: pnpm ≥ 12 rewrites pnpm-lock.yaml on any command in the checkout when the lockfile came from another pnpm, and the deploy refuses a modified tree.
run pulls the code itself. Store the git credentials once (git config credential.helper store && git fetch, or a read-only deploy key): preflight probes the remote with prompts disabled, warns at a terminal and stops before anything changes when nobody can type them (cron, CI).
With Apache the TLS certificate is yours to issue (certbot --dns-cloudflare -d <domain> -d '*.<domain>'); every deploy checks it. With Caddy it is Caddy's:
proxy: caddy({ onDemandTls: { ask: '/tls/allowed' } }), // tenants: a certificate per host, for hosts the app vouches forinstall writes /etc/caddy/sites/<app>.caddy — the apex (and *.<domain> with tenants), /api/ stripped to the app, web/dist with the SPA fallback — and, on a server still on the package's Caddyfile, a main file that imports it and asks the app before each certificate. Someone's own Caddyfile only gets the import line. caddy validate runs before the reload; a failure puts every file back. Deploys diff the site and never rewrite it; C1, C2 (not imported) and C8 (no ask) are checked as for Apache.
System packages
What the app runs from the operating system — binaries it spawns, libraries it loads — is declared with the app, as Debian/Ubuntu apt package names:
system: { packages: ['tesseract-ocr', 'poppler-utils', 'unzip'] },Each name matches [a-z0-9][a-z0-9.+-]{1,62} (no option, no version, no shell syntax) and appears once. Every deploy checks them as the app user (dpkg-query -W -f='${Status}' <pkg>, no shell): a missing one is a C12 error that stops the run before anything is built and prints the fix, sudo apt-get install -y <missing> — not the first user who reaches the feature. Without dpkg-query (not Debian/Ubuntu) it is a warning: nothing could be checked. plan prints system: tesseract-ocr, poppler-utils, unzip (installed) or (missing: …).
A deploy never installs them (it is not root). Root does, from the install plan, which carries the names as data: bootstrap (after the user's install-plan) and install run apt-get update and apt-get install -y --no-install-recommends for the missing ones, non-interactively, from the server's own apt sources. The app user chose the names and a package's install scripts run as root, so the list is shown and needs a "yes" at the terminal; when nothing is missing nothing is asked. Adding a package later: commit it, then install-plan and install once (or the apt-get line the deploy printed).
Commands
As the app user, in the checkout (node node_modules/@basaltkit/deploy/dist/bin.js <command>):
init --domain=<host> | writes deploy.config.ts from the project (--server: also from this server), then check |
check | the config is valid and types check (your tsc). No server needed — for CI. |
plan | every check, then what run would do, and the commits it would deploy. Asks nothing, and changes nothing run uses: the commits are fetched into a private ref it deletes again. |
run | preflight → fetch → env → infra → build → validate → backup → migrate → release → health → record |
env | the .env and the containers only |
rollback [--to=<sha>] | the last healthy release. Code only — the database keeps its migrations. Holds the commit it left. |
status | where the code comes from (remote, branch, address without credentials), the last releases (who, from where), the process, the deploy lock, a hold |
commits --from=<sha> --to=<sha> | the commits between two releases. Read-only: no lock, no fetch. |
commits --rollback [--to=<sha>] | what rollback would take out of production, to the commit it would choose |
install-plan [--out=<file>|-] | what install needs, as JSON (default <state dir>/install-plan.json, 0600), and the root command to run |
attach <runId> --json [--from-seq=<n>] [--follow] | the events of a run, from any point (machine mode, below) |
cancel <runId> [--first-only] | SIGTERM to a detached run; a second cancel stops it at once (--first-only refuses instead) |
ui | prints how to start the local UI (@basaltkit/deploy-ui) — on your machine, never on the server |
As root, with a copy of the tool root owns (cd / && sudo -H npx --yes --package=@basaltkit/deploy@<version> -- basalt-deploy <command>):
bootstrap --user=<name> --dir=<checkout> [--dry-run] | a fresh server, once (above); --dir is required |
install --plan=<file> --user=<name> | once per server: the state directory, the proxy site, the env files' owner |
Options: --skip=fetch,backup,tls, --config=<file>, --overrides=<file>, --actor=<name> (recorded with the release; default $BASALT_DEPLOY_ACTOR, else $USER), run --unhold, --allow-root, --unsafe-tool, and the machine-mode flags below (--json, --answers=stdin, --answer-timeout, --detach, --via=ui).
Exit codes: 0 done · 1 failed or refused · 3 another deploy holds the lock · 130 stopped by a signal (a second signal ends the process at once: 130/129/143).
One deploy at a time
run, env, rollback and install take <state dir>/deploy.lock (created exclusively, 0600) with the pid, host, start time, actor and command. A second deploy is refused with exit code 3 and says who holds it; a lock whose process is gone (same host) is taken over — for a detached run, once no process it started is left. status shows it.
The first Ctrl-C (or SIGTERM/SIGHUP) stops run/env at the end of the current step: run puts the code back and records the release as aborted. From the release on — and during rollback and install — the command finishes first; a second signal stops it at once, and with it the step's processes when the deploy leads its process group (started from a shell, or detached).
Releases, rollbacks and holds
Every release in releases.json records the sha, the status, the migrations it applied, the dump taken before them, the OS user and the actor, the SSH client address ($SSH_CONNECTION) and how it ran (ssh, ci, terminal, batch). audit: { syslog: true } also sends one line per release to logger -t basalt-deploy.
A rollback onto a commit that does not answer either exits 1 and records it as rollback-unhealthy; the next rollback never picks it. A manual rollback refuses a checkout with local edits and holds the commit it left: a scheduled run will not deploy that commit again until the branch moves on, or run --unhold.
Machine mode (--json)
For a program that drives the deploy — the local UI (@basaltkit/deploy-ui, RFC 0009), a script — over the system ssh, as the app user, exactly as a person would type it. There is no daemon, no listener and no new credential: the program can do what the SSH account can, nothing more. Design and threat model: RFC 0008 (it builds on RFC 0006).
--json (or --json=1; any other version is refused) works on status, check, plan, run, env, rollback, install-plan, attach and cancel. init, install and bootstrap refuse it. stdout then carries only NDJSON events, one per line:
{"v":1,"ts":"2026-10-13T10:00:00.000Z","seq":0,"runId":"20261013T100000Z-5f2c9a1b3d4e","type":"hello","tool":"@basaltkit/deploy","version":"0.5.0","protocol":1,"command":"run","pid":4100,"host":"server-1"}
{"v":1,"ts":"…","seq":1,"runId":"…","type":"step-start","id":"lock","title":"lock"}
{"v":1,"ts":"…","seq":2,"runId":"…","type":"step-end","id":"lock","status":"ok","durationMs":3}
{"v":1,"ts":"…","seq":9,"runId":"…","type":"log","stream":"child","level":"info","text":"Done in 4.1s","redacted":false,"step":"build","source":"pnpm"}
{"v":1,"ts":"…","seq":40,"runId":"…","type":"result","command":"run","data":{"sha":"…","previous":"…","status":"ok","migrations":[],"url":"https://myapp.example.com"}}
{"v":1,"ts":"…","seq":41,"runId":"…","type":"done","exitCode":0}Every stream starts with
helloand ends withdone;seqcounts up by one. A stream that ends withoutdoneended abnormally (a second signal, a kill) — never treat it as success.typeis one ofhello,step-start,step-end,log,finding,prompt,result,error,done(andevent, fromattach).errorcarries acode(locked,aborted,preflight,held,release-failed,answer-missing, …); the exit codes are the ones above.What a build, a hook, a migration or
deploy.config.tsprints (on stdout or stderr) is always thetextof alogevent (stream: "child"or"foreign"), stripped of terminal escapes, redacted, then cut at 8 KiB — data, never interpreted. Every other string of every event is stripped of escapes too.No event carries a secret. Every string is redacted before it is written: the values of generated, asked-secret and secret-named
.envkeys, passwords inside URLs, the infra passwords, secret-named variables of the deploy's own environment, every secret answer — raw and URL-encoded, and a multi-line value (a PEM key) also with its newlines escaped and line by line — become[redacted:KEY]. A name is secret when it holdsSECRET,TOKEN,PASSW,PRIVATE,APIKEY,CREDENTIAL, aKEY,SALTorPWDword, or ends in_URL/_DSN; declare any other withgenerateorask.secret. What the config prints while it loads waits until its.envhas been read. A bare origin in a*_URLkey (APP_URL=https://app.example.com) is the app's address and is not redacted. A value shorter than 6 characters cannot be matched; asecret-shortwarning names its key.Types and a validating parser for a program written in TypeScript:
tsimport { parseEvent, type DeployEvent } from '@basaltkit/deploy/protocol' for (const line of output.split('\n').filter(Boolean)) { const parsed = parseEvent(line) if (!parsed.ok) throw new Error(`corrupt stream: ${parsed.error}`) // stop: never guess if (parsed.known) handle(parsed.value) // a type this version does not know is skipped }The subpath is pure (no CLI, no Node API at load).
Answers. run and env ask the env.ask questions. plan --json lists them in its result (questions, never with a value; a secret never with a default). Send the answers on stdin with --answers=stdin, one line each:
printf '%s\n' '{"v":1,"type":"answer","id":"env.SMTP_URL","value":"smtps://user:pass@smtp.example.com:465"}' |
ssh -T deploy@192.0.2.10 -- 'cd /srv/myapp && node node_modules/@basaltkit/deploy/dist/bin.js run --json=1 --answers=stdin'An unknown id, a duplicate, a malformed or oversized line fails the command before the lock is taken. A required question nobody answers fails (answer-missing); an unanswered optional secret is left out of the .env. With stdin kept open, a refused answer is asked again (prompt with attempt: 2); a prompt waits --answer-timeout seconds (default 600). The deploy's own environment still answers first. No child process ever reads stdin.
Detached runs. run --detach --json (and rollback --detach --json) checks every answer first, starts the deploy in its own session — it survives the SSH connection — and returns {runId, pid, log} once that run holds the deploy lock:
node node_modules/@basaltkit/deploy/dist/bin.js run --json=1 --detach --answers=stdin --via=ui --actor=alice < answers.ndjson
node node_modules/@basaltkit/deploy/dist/bin.js attach 20261013T100000Z-5f2c9a1b3d4e --json --follow --from-seq=0
node node_modules/@basaltkit/deploy/dist/bin.js cancel 20261013T100000Z-5f2c9a1b3d4e --json- Every JSON-mode
run,envandrollbackwrites its events to<state dir>/runs/<runId>.ndjson(0600, in a 0700 directory, created exclusively, never through a link).attachreplays one, wrapped as{"type":"event","event":{…}}, from--from-seq(the innerseq), and with--followwaits for itsdone; a run gone without one isrun-vanished. The newest 50 logs are kept, none older than 30 days; a log stops taking output lines at 64 MiB. cancelsends SIGTERM only to the process holding the lock for that run, checked by its own command line (Linux). It stops at the next safe point, as Ctrl-C does; a secondcancelstops it at once, with the step it was running (its process group). The lock is taken over by the next deploy once no process of that run is left.cancel --first-onlysends only a first signal: when the run was already cancelled once, from any client, it is refused (already-cancelled) and nothing is signalled. A client that asked for the mild cancel never sends the immediate one by surprise.status --jsonreports the lock, the active run and the last run, and (0.9.0)source: the config's remote and branch, and the remote's address ashost/path, never with credentials, a query or a local path.--via=uirecordsvia: "ui"with the release; like--actor, it attributes, it does not authenticate.
The local UI
@basaltkit/deploy-ui is a browser UI for all of the above that runs on your machine (npx @basaltkit/deploy-ui@<exact version>), listens on 127.0.0.1 only and drives each server over your own ssh with the machine mode — status, plan, the .env questions, a detached run with its live log, cancel, rollback, history. Never add it to the app's package.json: this package installs the app's devDependencies on the server. Design and security model: RFC 0009.
Docker Compose apps
runtime: compose({
file: 'docker/compose.prod.yml',
images: [
{ tag: 'myapp', dockerfile: 'docker/app/Dockerfile', env: 'MYAPP_IMAGE' },
{ tag: 'myapp-worker', dockerfile: 'docker/worker/Dockerfile', env: 'MYAPP_WORKER_IMAGE' },
],
upstream: { service: 'api', port: 3001 }, // published on 127.0.0.1 by the compose file
env: { MYAPP_API_HOST_PORT: '3001' }, // compose interpolation — never secrets
keepImages: 3,
}),- Each image is built once per commit as
<tag>:<7-char sha>and skipped when it exists;compose up -dgets the tags through theenvvariable of each image. - Health: the upstream service healthy by its own healthcheck, no service of the project restarting, then the loopback and public URLs.
- Rollback starts the previous commit's images again — no rebuild. After a healthy release,
<sha>tags of these images outside the lastkeepImagesreleases are removed; nothing else is ever pruned. - Image tags must be
<app>or<app>-…(C4).
The env file outside the checkout: env: { file: '/etc/myapp/api.env', mirror: ['/etc/myapp/worker.env'] }. Mirrors are rewritten as exact copies; one that differs is a C10 error. Outside the checkout an env file lives directly in /etc/<app>/ — nowhere else (never /etc/environment). install gives /etc/<app> (0700) and the files (0600) to the deploy user, through descriptors opened without following links: a symlink or a hard link planted there is refused. The app name picks that directory, so install never takes one that is not the app's: names such as systemd, ssh, apt, docker or basalt cannot keep env files in /etc (keep the env in the checkout, or rename the app); a directory a Debian package ships, one with subdirectories, or one another account owns is refused; one root created by hand is shown and given only after a "yes". The state directory /var/lib/basalt/<app> is refused too when another account owns it.
Migrations by command, with values that override the .env for them and for the pre-migration dump (a container name the host cannot resolve):
migrate: {
command: ['./node_modules/.bin/tsx', 'scripts/db.ts', 'deploy'],
env: (v) => ({ DATABASE_URL: v.get('DATABASE_URL')!.replace('@myapp-postgres:', '@127.0.0.1:') }),
},Dedicated infra for a compose app — the containers created by the deploy too, in their own compose project, reached by name from the app's containers:
infra: dockerInfra('myapp', {
project: 'myapp-infra', // never the runtime's project: each would remove the other's containers
access: 'containers', // URLs name the containers (myapp-pg:5432); migrations get 127.0.0.1:<port>
postgres: { user: 'myapp_owner', urlKey: 'OWNER_DATABASE_URL', appRole: { name: 'myapp_app', urlKey: 'DATABASE_URL' } },
redis: { urlKey: 'REDIS_URL' },
seaweedfs: { buckets: [{ name: 'myapp-documents', versioned: true }] },
}),
runtime: compose({
// …
attach: { 'myapp-pg': ['data'], 'myapp-redis': ['data'], 'myapp-seaweedfs': ['data'] },
passEnv: ['REDIS_URL'], // a service without env_file gets it through ${REDIS_URL}: from memory only
}),Ports are still published on 127.0.0.1 for the host; the app role's URL follows the database when it moves (a recreated container) and keeps its password.
Services you keep but do not create (RFC 0007 §4) — containers that outlive any release, adopted by name:
infra: external({
postgres: {
container: 'myapp-postgres',
urlKey: 'OWNER_DATABASE_URL', // the owner: role, grants and the dump run as it
appRole: { name: 'myapp_app', urlKey: 'DATABASE_URL' }, // what the app connects as: no DDL
},
redis: { container: 'myapp-redis' },
s3: { // any S3-compatible store; credentials from the .env
hostEndpoint: 'http://127.0.0.1:8333', // where the deploy reaches it, if the .env names a container
buckets: [{ name: 'myapp-documents', versioned: true }, { name: 'myapp-quarantine', expireDays: 1 }],
},
}),
runtime: compose({
// …
attach: { 'myapp-postgres': ['data'], 'myapp-redis': ['data', 'sandbox'] }, // onto <app>_<network> before up
jobs: [{ service: 'freshclam', command: ['freshclam', '--stdout'], once: { exists: '/var/lib/clamav/main.c?d' } }],
}),
verify: {
logs: { 'ingest-worker': ['EAI_AGAIN', 'ECONNREFUSED'] }, // since the release started; found → rolled back
http: [{ path: '/readyz' }],
},- Preflight: each container running; every service and container name the config uses exists (
did you mean "ingest-worker"?). - The role: created when missing, its password the
.env's (generated from the owner's URL when the key is absent), proven over TCP before anything is changed, granted DML through the owner's default privileges — never on existing tables, which an app may keep append-only. Withmigrate.tenants, everytenant_*schema too, after the migration. - Buckets: over the S3 API itself (signed in the deploy, no vendor CLI): created; versioning on; the expiry rule added once, next to any rule already there. The store and its credentials are checked before the build.
- Attach: on a fresh server the project is created first (
up --no-start) so its networks exist and the first release is healthy, not the second. - Jobs:
docker compose run --rm --no-depswith this commit's images, beforeup;onceskips them when the path exists. - The dump runs inside
infra.postgres.containeras the owner. dockerInfraservices takecontainer(adopt another name) andappRoletoo.
Object storage: SeaweedFS (RFC 0010) — dockerInfra(app, { seaweedfs }) runs one chrislusf/seaweedfs container (master, volume, filer and S3 in one process) and writes S3_ENDPOINT, S3_ACCESS_KEY and S3_SECRET_KEY (rename them with keys):
- Only the S3 API is published, on 127.0.0.1. The master, the volume server and the filer listen on the container's loopback only — they have no authentication, and
runtime.attachputs the container on the app's networks. The Iceberg and Lance listeners are off. - The admin gRPC (identities, policies) requires a signed token: the deploy generates the signing key and keeps it. SeaweedFS 4.48 otherwise accepts an identity from any neighbour on the network — verified, RFC 0010 §3.
- Healthy means a volume server has joined, not only that
/healthzanswers: reads fail for a few seconds after/healthzturns green. - The credentials are not stored in the data: a new pair on an old volume is a rotation (the objects stay readable), not the lock-out it is for Postgres.
Moving off MinIO. MinIO's community edition is archived (no images, no fixes), and minio is gone from this package: a config that still names it is refused with this pointer. Per app:
- Replace
minio: { … }withseaweedfs: { … }(samebucketsandkeys), orexternal({ s3: { … } })for a store you run yourself. basalt-deploy plan, thenrun: the new store is created next to the old one, on its own port, with the buckets.- Copy the objects, old store to new, with any S3 tool — e.g.
rclone syncfrom a container on the host network, both remotes set by environment variables, so no key lands in a file or a command line. Versioned buckets: only the current versions come across. - Check the app, then remove the old container and, once you are sure, its volume.
Hooks — what only your app does, as commands that also run by hand:
hooks: {
infra: [['bash', 'scripts/deploy/infra.sh']], // after the .env and infra, before the build
verify: [['bash', 'scripts/deploy/verify.sh']], // after the health check; failing rolls back
},They run in the checkout as the deploy user with the .env values, the image variables, DEPLOY_SHA and DEPLOY_APP. They run on every deploy: idempotent.
Apache you write yourself: apache({ managed: false, vhosts: ['myapp.conf'] }) checks C2 and C1 on each vhost on every deploy and never writes them.
What runs by default
prisma migrate deploy— whenbuild.prismalists a config, ormigrate.central: true; not with amigrate.commandunlesscentral: true.tenant:migrate— only withmigrate.tenants.- The dump before migrating — when something is migrated and there is a Postgres to dump (dedicated, or a
postgres://URL in the.env);backup.beforeMigrateforces it either way.plansays why when it is skipped. Dumps go to<state dir>/backups(0700). Onceinstallran that is/var/lib/basalt/<app>/backups, outside the checkout — never in an image, a commit or a served directory. Before, it is<checkout>/.basalt/backups: a new app's.gitignore/.dockerignoreexclude/.basaltand/backups, and the preflight warns (dumps) when git does not ignore the directory or a Docker build would copy it.backup.dir(relative to the checkout) keeps the old place; dumps left inbackups/predeploy, the old default, are pointed out until they are moved or deleted. When/var/lib/basaltexists but/var/lib/basalt/<app>is missing or not reachable by the app user (a parent only root can enter), the preflight says so (state-dir) instead of falling back to the checkout in silence;installmakes/var/lib/basalt0755 (each app's own directory below stays 0700). - The node it runs on, first on
PATHfor everything it starts (pnpm,node, the app's scripts). With nvm, fnm or volta, a non-interactive shell (ssh host cmd, cron, the local UI) does not have them onPATH; starting the deploy with that node's absolute path is enough. With external infra in a container,backup: { container: 'myapp-postgres' }runspg_dumpinside it (docker exec), as the user and database of the URL atbackup.urlKey— the server's own pg_dump, none needed on the host. The preflight checks the container is running.
What it refuses to do
Each of these is a check that runs on every deploy, written after a production incident (RFC 0006 §5):
- C1 proxy or bind to a port another process owns — including Apache's own;
- C2 trust a vhost copied into
sites-enabled/instead of linked; - C3 restart a PM2 process that runs from another directory (it re-creates it);
- C4 name any process, container or volume that does not start with
<app>-; - C5 write or read a
.envline that is notKEY=value(reported by line, never by value); - C6 accept a value meant as off that your schema reads as on (
z.coerce.boolean()turns"0"intotrue); - C7 give an existing database volume a new password;
- C8 stay silent about a certificate that does not cover the apex or a tenant host;
- C9 run with a package manager major other than the one
packageManagerdeclares; - C10 keep a forbidden key, or a fixed key with another value.
- C11 build a commit whose
packageManager(pnpm ≥ 12) the lockfile does not record — checked in preflight and again on the commit the fetch brings, before any install. A lockfile the package manager rewrites during the deploy is put back to the committed version (with a warning), so the next deploy is not blocked; and no check runs the package manager inside the checkout. - C12 build when a
system.packagesentry is not installed (the fix is printed; a deploy never runs apt).
Secrets never reach a command line, the compose file, or the terminal: the summary names keys, passwords travel in child-process environments only.
Your app loads its own .env (import 'dotenv/config' first in src/server.ts, or node --env-file=.env). PM2 starts it with NODE_ENV, PORT and HOST only: not the operator's shell (a stray variable would override the file), and not the secrets (pm2 save writes the process environment to ~/.pm2/dump.pm2).
When a release fails
- Before
release(build, validation, backup, migration): the code on disk is put back to the previous commit and rebuilt; nothing running was touched. - A failed migration is recorded as
failed-migration: the database may be part-way, so thepg_restorecommand for the dump taken before it is printed. - At
release/health: the previous commit is rebuilt, restarted and checked. - A release that applied a migration listed in
destructiveis never rolled back automatically — its code would run on a schema it does not know. Thepg_restorecommand for the dump taken before it is printed instead. - Healthy on
127.0.0.1but not athttps://<domain>: exit 1, no rollback — the problem is the proxy, DNS or TLS, not the code.
Who runs what: the trust boundary
| Who | Runs | Can change |
|---|---|---|
| the app user | env, run, rollback, plan, status, install-plan; the app itself | the checkout: deploy.config.ts, node_modules, every file in the tree; its .env; <state dir> |
| root | bootstrap, install — from a copy of the tool root owns | everything |
- Root never runs the app user's code.
installreads a data-only plan (install-plan), without following a link, and validates every field again: the web root (inside the checkout, no dot directories, not the checkout itself), the API prefix, the certificate name, the env files (only/etc/<app>/), the checkout (must be the user's own directory). It never loadsdeploy.config.ts, the checkout'stsxornode_modules, nor reads the.env. Before writing it prints what it will do. Raw Caddyextraand a non-default proxy root are shown and need a "yes" at the terminal;extramay hold no control, direction or zero-width character (what is shown is what is written) and noimport. - A plan cannot take another site. The managed vhost is
<app>.conf(or<app>-….conf), andinstallrefuses a domain — or a name under its wildcard, or a wildcard over it — that another Apache vhost or Caddy site already serves (Caddyextrasite blocks included). The file it replaces must be the app's own: written byinstallfor it, or serving only its names. - The served directory follows no planted link out of the user's files. The vhost sets
Options -FollowSymLinks +SymLinksIfOwnerMatchandAllowOverride Noneon the checkout and the web root, and the link rule on every directory above the checkout too — a parent the user can write (/home/<user>) could otherwise hold a link swapped in for the checkout itself.installrefuses a checkout reached through a link, and the plan'sdiris letters, digits and. _ @ + -only. Caddy'sfile_serverhas no such option: withcaddy(), a link in the web root is followed to anything thecaddyuser can read — keep secrets of other sites out of its reach, and the checkout under a root-owned directory (/srv/<app>;installwarns otherwise). - A user step never gets root's terminal. In
bootstrap, the app user'spnpm install(andenvwithout a terminal) writes to a pipe, not to root's terminal: a process a postinstall leaves behind cannot read root's keystrokes. Its output is shown line by line, without escape sequences. - Root writes only where no other user can plant a link: directories only root can write (
/var/lib/basalt,/etc/basalt, the Apache/Caddy roots), or files changed through anO_NOFOLLOWdescriptor. - The tool root runs is checked. As root,
installandbootstraprefuse to run from files another user can change —sudo node node_modules/@basaltkit/deploy/dist/bin.jsfrom the checkout, a user's npm cache, a per-user Node (nvm) — unless--unsafe-tool. The check catches that mistake; it cannot stop a copy someone already tampered with (its code has run by then), so the defence is the copy itself. Run the pinned copy:cd / && sudo -H npx --yes --package=@basaltkit/deploy@<version> -- basalt-deploy …(cd /: inside the checkout npx would pick its own copy;-H: root's npm cache, not the user's), or a root-owned global install (sudo npm install -g @basaltkit/deploy@<version>) with a root-owned Node (NodeSource's/usr/bin/node). The check is a guardrail against a mistake, not a boundary: it runs inside the copy being checked, so a copy the app user changed can drop it. Running the pinned, root-owned copy is the control. - The app user's commands refuse root (
--allow-rootto insist): as root they would build and run the app's code, anddeploy.config.ts, as root. - The
dockergroup is root on the machine (a container can mount/).bootstrapadds the user to it sodockerInfraandcomposework, and says so; with it, the boundary above protects against mistakes and a compromised checkout less than against the app user itself. Rootless Docker for the app user is the real fix (dockerd-rootless-setuptool.sh install), and moves every volume — a later step, not done for you.