Lifecycle Commands

The deployment lifecycle

Every deployment follows the same arc: compile the code, prepare the environment, then run the app. Launchfile gives you a hook for each stage via the commands block.

Here's the order, and when each command fires:

1. build — Compile source, install dependencies, generate assets. Runs at build time.
2. release — Runs once per deployment, before start. Migrations, asset uploads, cache warming. If it fails, the deploy stops.
3. start — The long-running process. This is your app.
4. seed — Populate the database with sample or default data. Typically run on demand, not on every deploy.
5. test — Run the test suite. Used by CI and during deploys that validate before promoting.
6. bootstrap — First-time setup. Create the admin user, generate invite links, initialize config. Runs on user request, not automatically.

Build it up

commands:
  start: "node server.js"

commands:
  build: "npm install && npm run build"
  release: "npx prisma migrate deploy"
  start: "node dist/server.js"

commands:
  build: "npm install && npm run build"
  release: "npx prisma migrate deploy"
  start: "node dist/server.js"
  seed: "node scripts/seed.js"
  test: "npm test"

commands:
  start:
    run: "my-app serve"
    capture:
      ADMIN_TOKEN: "Admin token: (.+)"

The build block

There's a subtle but important distinction: commands.build runs shell commands (like npm run build), while a top-level build: block configures a Dockerfile-based container build. They serve different purposes.

commands:
  build: "npm install && npm run build"
  start: "node dist/server.js"

build:
  dockerfile: ./Dockerfile

commands:
  start: "node server.js"

Running from source: install and dev

The commands above run the app as a built artifact — build compiles it, start runs it. But on a dev machine you often want to run the app from source instead: hot reload, the repo's own dev server, no container. That's a different execution mode, and it varies exactly one thing — the command lines.

Two source-mode keys pair with the artifact ones:

• install — source-mode prepare (the counterpart of build). Runs on demand: first launch, or when dependencies change.
• dev — source-mode run (the counterpart of start). Your dev server.

commands:
  build: "bun install && bun run build"
  start: "node dist/server.js"

source: ./apps/api        # working dir for install/dev
commands:
  install: "bun install"
  dev: "bun run dev"

launchfile up runs the artifact (build → start); launchfile dev runs from source (install → dev), in the optional source directory. Run precedence is dev > image > start: a prebuilt image stays an artifact unless dev overrides it. Only prepare and run are mode-aware — release, bootstrap, seed, and test are the same command in either mode.

In the wild

This spec example shows a real-world pattern: a post-start bootstrap command that creates an admin user and captures the one-time invite link from stdout.

version: launch/v1
name: my-app

build:
  dockerfile: ./Dockerfile

provides:
  - protocol: http
    port: 9999
    exposed: true

env:
  APP_SECRET:
    generator: secret
    sensitive: true
  PUBLIC_URL:
    default: $app.url
    description: "Public URL the app is reachable on (auth callbacks, email links)"

health: /health
restart: always

commands:
  start: "node server.js"

  # Post-start setup: create the first admin and capture the one-time invite link.
  # Run by the user via `launchfile bootstrap my-app` (or the provider's equivalent)
  # after the app is up. Re-runnable; failures are reported, not deploy-failing.
  bootstrap:
    command: "my-app-cli create-invite --name admin --url $app.url"
    capture:
      invite_link:
        pattern: "https?://\\S+"
        description: "One-time invite link — open in a browser to register your account"
        sensitive: true

Check your understanding