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 five 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

environment

Optional. Selects the deploy target for this apply. name defaults to production; node places the environment on a specific deploy node. When node is empty, apply never moves an existing environment.

environment:
  name: staging
  node: edge-1

See Environments for details.

preview

Optional. Declares the base domain that preview environments derive their URLs from. It is inert unless an apply passes --preview:

preview:
  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 and TLS certificate for *.preview.example.com. There is no default: an apply that passes --preview without this field fails.

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