# Builds

> How an app's source becomes an image — Dockerfile or detected language, on your laptop or on the platform

URL: https://pier.run/docs/builds

An app with a `build_context` is built from that directory. Where the build runs depends
on what triggered it.

| Trigger                          | Builds on                     | Needs                                                                                       |
| -------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
| `pier deploy`                    | your machine, with docker     | docker; the CLI pushes to the project's registry with the credential `pier login` installed |
| a push to a connected repository | the platform, from the commit | [Deploy from GitHub](/docs/guides/deploy-from-github)                                       |

Both produce the same image for the same source: the build strategy is the same, and the
image is tagged with the source hash (`api:24e4848`) so a second build of unchanged
source is a no-op.

## Strategy

| Source                                                               | Strategy                                                                                                                                           |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| a `Dockerfile` in the build context (or `dockerfile:` on the target) | `docker build` of that file                                                                                                                        |
| no Dockerfile                                                        | detection: Node, Python, Go, Rust, Ruby, PHP, Java, .NET, Elixir, Deno, and static file trees; the detected recipe is printed in the deploy output |

Detection is a convenience for the common case; add a `Dockerfile` to control the image
exactly. `pier deploy -f` forces a rebuild of unchanged source.

## Build-time variables

Variables with a plain `value` are available at build time; secrets and links are not
(they resolve when the target starts). A site build that needs a secret must run on the
platform (push-to-deploy).

## Output

Every build is a deploy row: `pier deploys ls api`, `pier deploys logs <id>` for the full
log, `pier deploys info <id>` for the commit, author, image and timing.

## Registry

Images live in the project's private registry at `registry.pier.run/<project>/<app>`.
`docker push` to it works with the same credential helper; an image pushed by hand can be
deployed by setting `image:` on the target.

## See also

[Apps](/docs/resources/apps) · [Deploy an app](/docs/guides/deploy-an-app) · [Deploys](/docs/deploys)