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 target an environment with the environment block in up.yaml, or with the --env flag on the CLI.

environment:
  name: staging
  node: edge-1

name

The environment name. Defaults to production. The CLI --env flag selects the environment when this is omitted.

node

The deploy node this environment lives on. Services in the environment are deployed to this node. When node is empty, apply never moves an existing environment.

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.

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:

up environment create pr-42 --preview

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.