Environments

An environment is an isolated namespace within a project. Each environment gets its own Docker network and its own scoped named volumes, so two environments of the same project never share state or resolve each other’s services.

You declare the environment catalog in the environments block of up.yaml. Each entry maps a git branch to an environment name and a deploy node. The control node projects the catalog onto stored environments on every apply.

project: acme

previews:
  base_domain: preview.example.com

environments:
  - branch: main
    name: production
    default: true
    previews: true
  - branch: staging
    node: edge-1

A branch that is not declared does not deploy. The GitHub App deploys only the branches in this catalog, and a pull request deploys a preview only when the environment for its base branch enables previews.

Changes to environments never delete an environment. Apply creates a missing environment and updates a declared one, but an environment that is absent from the catalog stays in place. Remove an environment by hand with up environment remove.

branch

The git branch this environment deploys. The field is required and must be unique in the catalog. A push to this branch deploys the environment.

environments:
  - branch: main
    name: production

name

The environment name. When you omit it, the name defaults to the branch name. The name must be unique in the catalog.

environments:
  - branch: staging
    name: staging

node

The deploy node this environment lives on. Services in the environment deploy to this node. The value is the name of a node from the nodes section, or the name of a node that is already registered.

When node is empty, the control node keeps the node the environment already has. A new environment with no node is placed on the first available deploy node that is online.

environments:
  - branch: main
    name: production
    node: edge-1

default

Set default: true on one entry to mark the environment that up apply and up diff target when you pass no --env flag. Only one entry may set it.

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

When no entry is marked default, apply targets the first declared entry. When you pass --env <name>, the flag wins.

previews

previews controls whether a pull request that targets the environment’s branch deploys a preview environment. It accepts two forms.

A boolean turns previews on or off:

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

A mapping turns previews on and can override the shared base domain:

environments:
  - branch: main
    name: production
    previews:
      base_domain: preview.example.com

Previews are off when the field is omitted. A pull request deploys the environment pr-<number> only when the environment for its base branch enables previews. When the base branch is not declared, the pull request does not deploy.

previews.base_domain

The base domain for derived preview URLs. A service named web in environment pr-42 becomes pr-42-web.<base_domain>. Set the domain once at the top level for every environment, or on one environment to override the shared value.

previews:
  base_domain: preview.example.com

A preview environment needs a base domain. Set either the top-level previews.base_domain, or previews.base_domain on the environment itself.

Creating environments

Create an environment imperatively with up environment create:

up environment create staging --node edge-1

The environment’s network and volumes are created on the chosen node. The create and set-node commands are imperative overrides: the next up apply resets the environment catalog to the environments declared in up.yaml.

Preview environments

An environment has a kind: standard for a stable target such as production, staging, or uat, and preview for an ephemeral environment that hosts one pull request. Pass --preview to create the ephemeral kind by hand:

up environment create pr-42 --preview

The GitHub App creates a preview environment for a pull request automatically when the base environment enables previews. Preview environments are listed with their kind in up environment list. The kind is set when the environment is created and apply never changes it. See the Preview environments guide for the full workflow, including per-pull-request URLs.

Scoped resources

• Network : every environment has a dedicated Docker network, named up-net-{id}.
• Volumes : a logical volumes: [{source: data}] on a service becomes the physical volume up-{environmentId}-data, so the same logical name in two environments never points at the same data.

Because scoped volumes are new physical resources, data in a pre-existing volume is not carried over automatically. Copy it once per environment:

docker run --rm \
  -v data:/from \
  -v up-{environmentId}-data:/to \
  busybox cp -a /from/. /to/

Moving an environment

Move an environment to another node with up environment set-node:

up environment set-node staging --node edge-2

The environment’s network and volumes are recreated on the new node.

Removing environments

Removing an environment with up environment remove cascades to its services and deployments:

up environment remove staging --force

Without --force, removal is refused while the environment still has services.