Configuration

Your whole project lives in one versionable file: up.yaml. up apply and up diff read it, and the schema is strict: unknown keys are rejected, so a typo fails loudly instead of being ignored.

The smallest working config:

project: myapp

services:
  - name: api
    source:
      type: image
      image: nginx:latest
    port: 8080

The file has six top-level sections. Each is documented on its own page.

project

Required. The name of the project this configuration applies to. Services are deployed into the project’s environments, so the project must exist or be created by the first apply.

project: myapp

environments

Optional. Declares the environment catalog: one entry per git branch, with the environment name, the deploy node, the default flag, and the preview policy. Only declared branches deploy.

environments:
  - branch: main
    name: production
    default: true
    previews: true

See Environments for details.

previews

Optional. Declares the base domain that preview environments derive their URLs from. An environment can override it with its own previews.base_domain.

previews:
  base_domain: preview.example.com

base_domain

The domain that preview hostnames are subdomains of. A service named web in environment pr-42 is served at pr-42-web.preview.example.com, which requires a wildcard DNS record for *.preview.example.com. The proxy obtains a certificate for each preview host through ACME, so no wildcard certificate is needed. A preview environment needs a base domain from this field or from its own previews.base_domain.

See the Preview environments guide for the full workflow.

registries

The container registries up pulls base images from and pushes build output to. Each entry has a name that services reference, plus connection details:

registries:
  - name: ghcr
    host: ghcr.io
    username: deploy-bot
    password: $GHCR_TOKEN

See Registries for details, and the Registries concept for background and how to get a registry.

nodes

The nodes that run builds and deployments. Each entry names the node, how to reach it over SSH, and the roles it may perform:

nodes:
  - name: builder-1
    roles: [build]
    host: 10.0.0.1
    user: root
    key_path: ~/.ssh/id_ed25519

See Nodes for details.

services

The workloads: long-running containers and one-shot jobs. This is the heart of the file; see Services for the complete reference.

services:
  - name: api
    source:
      type: image
      image: nginx:latest
    port: 8080