# Apps

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

URL: https://pier.run/docs/resources/apps

```yaml title="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
```

```bash
pier ls apps
```

```text title="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](/docs/concepts#target) 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](/docs/vars) |
| `previews`                         | app         | Preview targets per branch — [Preview deployments](/docs/guides/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](/docs/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](/docs/resources/domains)                                                                      |
| `targets[].volumes`                | target      | `{ volume, mount_path }` bindings — [Volumes](/docs/resources/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](/docs/concepts#trash)
  for 30 days.

## Tasks

[Deploy an app](/docs/guides/deploy-an-app) · [Set environment variables](/docs/guides/set-environment-variables) ·
[Scale an app](/docs/guides/scale-an-app) · [Roll back a deploy](/docs/guides/roll-back-a-deploy) ·
[Deploy from GitHub](/docs/guides/deploy-from-github) · [Preview deployments](/docs/guides/preview-deployments) ·
[Add Postgres to an app](/docs/guides/add-postgres-to-an-app)