Configuration reference

Before you start

Add the file at this path on your default branch.

.peak/preview.yml

Peak reads it from the default branch only. Expect a pull request’s changes to this file to have no effect, even on its own preview. Merge changes to the default branch to use them.

Example

.peak/preview.yml

version: 2
public: web

services:
  web:
    build: apps/web
    port: 3000
    health: { http: /healthz }
    env:
      API_URL: { service: api, property: url }
      PUBLIC_URL: { template: "{url}" }

  api:
    build:
      context: .
      dockerfile: apps/api/Dockerfile
    command: bun run start
    port: 8080
    migrate: bun run db:migrate
    dependsOn: [main, cache]
    env:
      DATABASE_URL: { database: main, property: url }
      REDIS_URL: { database: cache, property: url }
      SESSION_SECRET: { generate: hex32 }
      STRIPE_KEY: { secret: STRIPE_KEY }
      LOG_LEVEL: debug

databases:
  main: { kind: postgres, version: "17", database: app }
  cache: { kind: redis }

Top-level keys

Key	Required	Value
version	Yes	2
from	No	A Render Blueprint or Compose file to start from
public	Without from, unless there is one service	The service the preview URL serves
services	Without from	Services by name
databases	No	Databases by name

Use lowercase letters, digits, and hyphens in names, up to 63 characters. Don’t start a name with peakviews-.

Start from another file

Set from to keep your Render or Compose setup and change part of it.

.peak/preview.yml

version: 2
from: render.yaml
public: web
services:
  worker: null
  api:
    env:
      LOG_LEVEL: debug
      LEGACY_FLAG: null

Expect Peak to read that file first, then apply this one. Expect a service or database with the same name to keep every field you leave out. Expect env and build args to merge by name. Set a service, database, or variable to null to remove it.

Services

Field	Value
build	A context path with a Dockerfile in it. Or a map of context, dockerfile, target, and args. Paths start at the repository root.
image	An image to pull instead of build
command	A string or a list. Peak runs a string with /bin/sh -c only when it needs a shell.
entrypoint	A string or a list
env	Variables by name. See Values.
port	The port the service listens on, 1 to 65535
health	One of http (a path), tcp: true, or command. Add intervalSeconds, timeoutSeconds, startSeconds, or retries if needed.
migrate	A command that runs once before the service starts
aliases	More host names on the preview network. Use {pr} for the pull request number.
dependsOn	Services or databases that start first
job	true for a service that runs to completion. Services that depend on it wait for exit 0.
volumes	Named volumes, such as uploads:/data/uploads

Set build or image on each service. Set a port on the public service. Use the same value forms for build args as for env.

Databases

Field	Value
kind	postgres, mysql, clickhouse, or redis
version	An image tag, such as “17”. Default: the current version.
database	The database name. Default: the entry name, with - changed to _.
user	The user name. Default: the entry name, with - changed to _, or default for ClickHouse.

Values

Set each env value or build arg in one of these forms.

Form	Value
A string	That string
generate: hex32	32 random bytes as hex
generate: base64-32	32 random bytes as base64
secret: NAME	The repository’s key NAME
database: NAME, property	A value of a preview database
service: NAME, property	A value of another service
template: TEXT	Text with placeholders

Expect each generated value to stay the same for the life of the preview. Give two generate values the same key to share one value.

SESSION_SECRET: { generate: hex32, key: session }

Expect Peak to ask for every secret name before a preview starts. Use letters, digits, and underscores in secret names. Don’t use names that change how Docker Compose runs, such as PATH, HOME, or names that start with COMPOSE_, DOCKER_, BUILDKIT_, BUILDX_, or PEAKVIEWS_.

Database property	Value
url	A connection URL, such as `postgresql://USER:PASSWORD@main:5432/app`
host	The database’s name
port	5432 for Postgres, 3306 for MySQL, 8123 for ClickHouse, 6379 for Redis
user, password, database	The login and database name. Redis has none.

Service property	Value
host	The service’s name
port	The service’s port
hostport	host:port
url	`http://host:port`

Placeholder	Value
{pr}	The pull request number
{sha}	The head commit
{branch}	The pull request’s branch
{label}	The preview’s label, such as pr-42-web-1a2b3c4d
{url}	The preview URL
{host}	The preview host name
{secret:NAME}	The repository’s key NAME

Write {{ and }} for literal braces.

File rules

Keep the file at 64 KiB or less. Use strict YAML: no anchors, aliases, merge keys, or tags. Use only the keys on this page. Expect a version 1 file to be ignored. Check errors under Setup in Previews.

Limit	Value
Services	32
Databases	16
Variables per service	500
Value size	64 KiB

Get started

Move to Peak

Runners

Insights

Peakviews

Developer tools

Workspace

Configuration reference

Before you start

Example

Top-level keys

Start from another file

Services

Databases

Values

File rules

​Before you start

​Example

​Top-level keys

​Start from another file

​Services

​Databases

​Values

​File rules

Before you start

Example

Top-level keys

Start from another file

Services

Databases

Values

File rules