Stack file

briq.yaml sits at the root of a repo and declares its stack. A service is a recipe and the fields it changes, or an image with its settings, as in GitHub Actions services:.

stack: shop
services:
  db:
    recipe: postgres
    image: pgvector/pgvector:pg16
    volume: { gb: 10 }
  cache: { recipe: redis }
  mail: { recipe: mailpit, expose: private }
  web:
    image: ghcr.io/acme/shop:latest
    ports: [3000]
    env:
      DATABASE_URL: postgres://postgres:{{secret:POSTGRES_PASSWORD}}@{{briq:db}}:5432/app
      REDIS_URL: redis://default:{{secret:REDIS_PASSWORD}}@{{briq:cache}}:6379
      SMTP_HOST: "{{briq:mail}}"
      SMTP_PORT: 1025
      STRIPE_KEY: { secret: STRIPE_KEY }
    expose: private
    sleep: 3h

Bring it up:

What up does

1. Makes each service the stack does not have yet, as briq_run makes it and under the same checks (key policy, quotas, plan, credits). Every new service is made, or none.
2. Leaves each service the stack has as it is. It never changes or deletes one.
3. Answers with every briq, the services created and existing, and the outputs: each recipe's connection strings, the secrets briq generated, and <briq>:URL for each published service.

Calling it again is safe: it makes nothing new. To change an existing service, destroy it, then up again. stack in the call brings the file up as another stack: a branch's.

Fields

The service name is the briq's name, so {{briq:db}} reaches the service db. A recipe that makes several briqs (wiki, plane) keeps its own names.

Recipe service

recipe and the fields of the service it makes. Each recipe's cookbook page lists the ones it takes and their defaults.

Image service

Every field of a briq spec except name: image (required), cmd (a string run with sh -c, or the argv), entrypoint, env, ports, size, volume, files, healthcheck, sleep, and expose as below.

expose

private is a URL only whoever has it can open. See Expose.

env

{{secret:…}} and {{briq:…}} are put in when the service starts, inside a larger value too. Status shows the placeholder, never the secret. The file never holds a secret's value: up refuses { secret, value }.

Good to know

• Services are made after the ones they read with {{briq:…}} or {{secret:…}}, whatever their order in the file.
• Two services of the file that hold the same secret name cannot be read with {{secret:…}}: up refuses it. Name one of them differently in its env.
• A private repo: checkout: { repo, token: { secret: GITHUB_TOKEN } }, and the token's value passed at up in secrets.
• An endpoint that cannot be opened yet comes back in warnings; briq_expose it once it runs.
• JSON is valid too: up reads YAML and JSON.
• A mistake is reported by path: services.db: Unrecognized key(s) in object: 'version'.
• A value in secrets that the file never names is refused: a typo would go unnoticed.
• up counts as use of the stack: its running services go to sleep later.