Apps

Containers Pier builds or pulls, runs in microVMs, and fronts with an HTTPS hostname

pier.yaml

environments:
  prod:
    apps:
      - name: api
        build_context: ./api             # build ./api/Dockerfile
        env:
          DATABASE_URL: { from: postgres.main.url }
          API_KEY: { secret: true }
        targets:
          - name: primary
            plan: app-s
            replicas: 2
      - name: whoami
        targets:
          - name: primary
            image: traefik/whoami:v1.10.1   # pull as-is, no build
            port: 80
            plan: app-s

pier ls apps

output

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

An app is a container image with an HTTP port. Pier either builds it from a build_context (a Dockerfile, or a detected language) or pulls a given image. Each of its targets runs in its own microVM with an HTTPS hostname; the environment's variables and links are injected as environment variables.

Configuration

Key	On	Meaning
`build_context`	app	Directory to build, relative to `pier.yaml`. Exclusive with `targets[].image`
`template`	app	Start from a starter template (`node_hono`, `python_fastapi`, `go_fiber`, `rust_axum`, `dockerfile_caddy`)
`env`	app, target	Variables; a target's entry overrides the app's, which overrides the environment's — Environment variables
`previews`	app	Preview targets per branch — Preview deployments
`targets[].image`, `port`	target	Pull this image; `port` is required with `image` and defaults to 8080 for builds
`targets[].plan`	target	Size — Plans
`targets[].replicas` / `autoscale`	target	Fixed count, or `min`/`max` with `triggers`; exclusive
`targets[].deploy.branch`	target	Branch that deploys this target on push
`targets[].dockerfile`	target	Dockerfile path for this target, relative to the build context
`targets[].domains`	target	Custom domains — Domains
`targets[].volumes`	target	`{ volume, mount_path }` bindings — Volumes
`targets[].primary`	target	The default target when several exist; otherwise the first listed

Commands

Command	Does
`pier add app`, `pier set app api`, `pier rm app api`	declare, change, remove; `--stage` edits `pier.yaml` only
`pier deploy api`	build (if `build_context`) and roll the target
`pier info api`, `pier logs api`, `pier monitor api`, `pier events`	inspect; `api/canary` names another target
`pier restart api`	roll the running target with its current image
`pier rollback api --to <id>`	run a previous deploy's image
`pier add target api canary --branch main`, `pier promote api/canary`	more targets; change the primary
`pier ssh api`	a shell in a running instance
`pier pause api`, `pier resume api`	stop and keep; start again

Behaviour

A roll starts the new instance and retires the old one once the new one is ready.
A change to plan, replicas or autoscale is applied immediately; a variable change is released by the next pier deploy without a build; a change to the source, image, port or dockerfile is a build and a roll.
autoscale: 0-N with idle_after scales to zero after that period without traffic; the next request starts an instance.
Logs and metrics are kept per target; pier logs api --since 24h, pier monitor api --range 7d.
A removed app keeps its deploy history and bound volumes in trash for 30 days.

Tasks

Deploy an app · Set environment variables · Scale an app · Roll back a deploy · Deploy from GitHub · Preview deployments · Add Postgres to an app

Configuration

Commands

Behaviour

Tasks

On this page