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.

When a command fails

Every command has exactly one failure disposition, decided by the slot it fills rather than its name — because one command can fill a slot in either mode. Source mode resolves prepare as install ?? build and run asdev ?? start, so build and start each show up in two modes.

"Fails the invocation" is what keeps this unambiguous. If you declare only start: — no dev, no image — it fills the run slot in source mode, and it's covered exactly once.

Commands run in a shell

A command string is handed to a POSIX shell, so &&, pipes, redirection and variable expansion all work the way you'd write them at a terminal:

commands:
  release: "rails db:migrate && rails db:seed"

A provider that can't offer a shell has to say the command went unhonored rather than guess at it — splitting on whitespace and running the first word would quietly execute half of what you wrote.

Timeouts and durations

Any command in the expanded form can declare a timeout:

commands:
  release:
    command: "npx prisma migrate deploy"
    timeout: "5m"

Every duration in a Launchfile uses one grammar: an integer immediately followed by exactly one unit — ms, s, m, or h. Valid: 500ms, 30s, 5m, 2h. Not valid: 5 m (no spaces), 1m30s (no compounds), 1.5h (no fractions). The same grammar covers the health check durations (interval, timeout, start_period).

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.

Where the source comes from

Locally, the source is the checkout your Launchfile sits in. A remote provider building from source has to acquire the tree first, and resolves it in order: a source the orchestrator hands it always wins (a fork, a mirror, a per-environment ref); otherwise the checkout the file was read from is shipped as the build context; otherwise — for a standalone file, like a catalog entry — it clones the repository field, the app's canonical origin.

On a git-hosted URL, a # fragment names the baseline ref the declaration describes — repository: https://github.com/hedgedoc/hedgedoc#develop is how an edge variant pins its baseline while the stable variant tracks a release. It's a default, never a lock: an orchestrator-supplied source always overrides it. A bare URL means the default branch.

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