> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peak.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration reference

> Describe your preview in .peak/preview.yml.

## Before you start

Add the file at this path on your default branch.

```text theme={null}
.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

```yaml .peak/preview.yml theme={null}
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.

```yaml .peak/preview.yml theme={null}
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](#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](https://docs.peak.inc/peakviews/detection.md#databases). |
| 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](https://docs.peak.inc/peakviews/environment.md) 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.

```yaml theme={null}
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](https://app.peak.inc/previews).

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.