Skip to content

The recipe: forkstage.yaml

The recipe is deliberately small. It is not a second compose file; it says what Forkstage needs to bake and fork: the services, the app’s port, how data gets in, when the stack counts as ready, and how to test it.

stack: orders-api
services:
app:
image: node:22 # run from an image…
source: . # …with the repository mounted at /app
setup: npm install # once, before the command
command: npm run dev
port: 3000
env:
DATABASE_URL: ${db.url}
depends_on:
- db
db:
image: postgres:16
port: 5432
data:
seed: npm run db:seed # a command in the app, or a .sql file
ready:
- http: app/health
migrate: npm run db:migrate
tests:
- name: unit
run: npm test

Built from a Dockerfile (build: .): Forkstage builds the image on the host during the bake, exactly as your Dockerfile says. Best when you already ship a Dockerfile. Tests then run inside the final image, so they can only use what that image contains.

Run from an image (image: plus source:): the repository is mounted at /app inside a stock image (node:22, python:3.12…), setup installs dependencies once during the bake, and command starts the app. Best for projects without a Dockerfile, and for fast iteration since nothing is rebuilt.

A service has one or the other, never both.

Forkstage fills these in from the services in the same recipe:

Placeholder Becomes
${db.url} postgres://forkstage:forkstage@db:5432/app (or MySQL / Redis equivalents by image)
${db.host}, ${db.port} the service’s name and port

Data stores get fixed credentials inside a fork: user forkstage, password forkstage, database app. They are only reachable from inside the fork.

data: empty means schema only: your migrations run, no rows. data: { seed: … } loads rows during the bake, from a .sql file (fed to psql in the database service) or a command run in the app. Migrations run before seeds. If your app migrates itself on start, leave migrate out.

A list of checks; the stack counts as up when all pass. http: service/path expects a 2xx or 3xx. tcp: service expects a connection on the service’s port. run: command expects exit 0, in the app unless in: says otherwise. The first http check is also what the bake waits for.

Each entry is a command run inside a service (the app by default, or in: db). forkstage test runs them all and records counts it can read from the output (Jest, Vitest, node:test, pytest, Go test, JUnit summaries). The GitHub App runs the same list on every pull request.

resources:
cpu: 4
memory: 4Gi

The microVM’s size. Defaults are 4 vCPUs and 3 GiB; a Maven build inside the bake is comfortable at that.

outside (how the stack reaches third-party hosts: record and replay, sandbox keys, block) and data: production-shaped are in the schema but not active in the hosted service yet. Leaving them out is correct today.

Every field, with types and defaults: Recipe fields.