> ## Documentation Index
> Fetch the complete documentation index at: https://www.towbar.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Dockerfile

> Build an app from an existing Dockerfile and control its build context, target, and cache.

Choose `dockerfile` when the repository already contains a Dockerfile, or when the build needs credentials through BuildKit's protected secret path. Towbar builds the committed revision, then runs the resulting image on the selected server.

## Example manifest

This is the validated example from the Towbar `examples/platform-modes` project. Replace the documentation IP, domain, and image choices with values for your environment.

```yaml title=".towbar/apps/dockerfile.app.yml" theme={"system"}
id: dockerfile-example
name: Dockerfile example
deployment:
  type: dockerfile
  context: examples/platform-modes/node-app
  dockerfile: examples/platform-modes/node-app/Dockerfile
  target: runtime
  architecture: amd64
  cache:
    enabled: true
    scope: platform-dockerfile-example
container:
  port: 3000
health:
  path: /health
environments:
  production:
    server: 192.0.2.10
```

## Configure it

The example builds only `examples/platform-modes/node-app` and selects its `runtime` stage. `context` limits the files sent to Docker; `dockerfile` points to the file in that context. Keep both paths inside the repository checkout. The declared `container.port` and `health.path` describe the result after build.

If this app needs private packages during build, declare a build secret name in the app manifest and use a BuildKit secret mount in the Dockerfile. Do not put credentials in build arguments or a committed file. A cache is workload-scoped unless an authorized shared `cache.scope` is configured.

Map the named environment to a branch, register and prepare its server, then sync the repository. Start with a manual deployment and verify the running service before opting into automation. See [Application manifest](/docs/apps/manifest) for shared fields and [Deployment modes](/docs/platform-deployments) to compare modes.