Set up a staging environment

A second, complete environment beside prod — its own apps, Postgres and variables — and how to work in it

Goal. acme has a staging environment with its own copy of api and its own Postgres, deployed from the same repository.

Add the environment

pier environments add staging

output


  Changes:
    + create environment "staging" (new environment)

→  Updated pier.yaml
OK  Created environment "staging"

An environment starts empty. It does not inherit from prod: each environment is a complete declaration (Concepts).

Copy what should exist there

pier copy app api --to staging

output

OK  Copied app "api" to pier.yaml (staging)

copy writes the app's declaration (plan, targets, variable declarations) into the staging block of pier.yaml. Custom domains are not copied, because a hostname belongs to one target. Secret values are not copied; set them for staging with pier vars set … -e staging. Postgres, buckets and volumes hold data, so they are declared explicitly rather than copied:

pier.yaml

  staging:
    apps:
      - name: api
        build_context: ./api
        targets:
          - name: primary
            plan: app-s
    postgres:
      - name: main
        targets:
          - name: primary
            version: "17"
            plan: pg-s
            bootstrap_default_database: app

The block is a declaration; nothing exists on the platform until it is deployed:

pier deploy -e staging

output

→  Comparing staging environment against platform state...

  Changes:
    + create app "api" in staging (plan: app-s, replicas: 1)

  Deploy:
    app "api"    reuse — no build (content unchanged)

OK  Applied 1 config change(s) to staging
→  Building api from ./api
→  Building pier-build/api:latest...

→  Pushing registry.pier.run/01a05313-e4fa-7707-a014-05f1ae901cec/api:9eed0df...
9eed0df: digest: sha256:722f9d0debe5e0de80eccf3bac4ed714cb6ef9e6e8177b5301329c4a7042c4b9 size: 855
OK  Pushed registry.pier.run/01a05313-e4fa-7707-a014-05f1ae901cec/api:9eed0df
→  Deploying api...
→  Waiting for infrastructure provisioning...
OK  Infrastructure ready

OK  Summary: 1 built, 1 deployed

Work in it

pier use staging

output

OK  Switched to environment staging

Every command now acts on staging until pier use prod. For one command only, -e:

pier deploy -e staging
pier ls -e staging

output


  Apps
                                                                                       
 NAME STATUS  REPLICAS AUTOSCALE IMAGE                                    PORT UPDATED 
                                                                                       
 api  running 1/1      -         zot.pier-registry.svc.cluster.local:5... 8080 5m ago

What changed

pier.yaml

version: 1
name: acme
project: acme-1ab0
environments:
    prod:
        apps:
            - name: api
              build_context: ./api
              env:
                API_KEY:
                    secret: true
                DATABASE_URL:
                    from: postgres.main.url
                LOG_LEVEL:
                    value: info
              targets:
                - name: primary
                  plan: app-s
                  replicas: 1
                  domains:
                    - host: api.acme.example
        sites:
            - name: www
              build_context: ./www
              targets:
                - name: primary
        postgres:
            - name: main
              targets:
                - name: primary
                  version: "17"
                  plan: pg-s
                  bootstrap_default_database: app
        buckets:
            - name: uploads
    staging:
        name: staging
        apps:
            - name: api
              build_context: ./api
              targets:
                - name: primary
                  plan: app-s
                  replicas: 1

Variations

Deploy staging from a branch: connect GitHub and set the staging target's trigger to develop (Deploy from GitHub).
Previews instead of a whole environment: a branch preview is a target inside prod that shares its Postgres (Preview deployments). Use staging when the data must be separate.
Pause when idle: pier environments pause staging stops it; resume restarts it with its data.

Set up a staging environment

Add the environment

Copy what should exist there

Work in it

What changed

Variations

See also

On this page