Skip to main content
[ PIER ]

Dockerfile

Paste a Dockerfile (or point at a Git repo) — Pier builds and ships.

Application #docker#build#dockerfile

Bring your own Dockerfile and Pier builds the image, runs the container, and wires it up. Paste the Dockerfile inline or point at a Git repo containing one. Useful when you need full build control — exotic system packages, multi-stage builds, custom entrypoints — that auto-builders (Railpack) can't express.

Deploy with Pier

  1. 1 Open the Pier dashboard and click Add service.
  2. 2 Pick Dockerfile from the template list.
  3. 3 Choose the version, set a service name, and Pier provisions the container, storage, and ports automatically.
  4. 4 Attach a domain if you want HTTPS. Traefik auto-provisions the Let's Encrypt certificate.

What is the Dockerfile template?

Bring your own Dockerfile. Either paste it directly into the Pier UI (good for tiny inline containers) or point at a Git repository containing one (good for everything you’ll iterate on). Pier builds the image with BuildKit, runs the container, attaches it to its Traefik-fronted network for HTTPS, and manages env / volumes / logs / lifecycle.

Use this template when you need explicit control over the build — multi- stage builds, distroless base images, system packages, custom entrypoints, build-time secrets — that auto-builders like Railpack don’t expose. Hand- tuned Dockerfiles consistently beat auto-builders on image size, layer control, and security review surface for the specific app they target.

How Pier deploys it

You provide either the Dockerfile content (textarea) or a Git URL. Pier clones (if Git mode) and runs docker buildx build with BuildKit on the host, producing an OCI image stored locally. The container starts with your configured ports, env vars, and volumes.

BuildKit layer cache persists between builds — typical incremental builds finish in seconds. Build secrets (npm tokens, private registry auth) ride along via BuildKit’s secret mount mechanism without baking into the final image.

Attach a custom domain in Pier for HTTPS via Traefik. Click Redeploy to trigger a rebuild (or wire a Git webhook for push-to-deploy).

When NOT to use Dockerfile

For “I have source, no Dockerfile, want a container” — use Railpack. For “I have a pre-built image in a registry” — use Docker Image. For “I have a multi-container stack” — use Docker Compose. For native Pier services with managed backups and version upgrades (PostgreSQL, Gitea, Grafana, …), pick the dedicated template. Dockerfile is the right answer when you need full control over how your single-container app is built.

Key features

Paste-inline or Git URL

Two input modes — paste a Dockerfile directly into the UI, or give Pier a Git repo URL and it builds from the Dockerfile in the repo root (or a specified path).

Full build control

Multi-stage builds, ARG / ENV / COPY / RUN — anything Docker can do, this template builds.

BuildKit-powered

Layer caching across rebuilds, parallel stages, build secrets. Faster iteration than classic Docker build.

Build args + env vars

Pass build-time ARGs and runtime ENV separately. Build secrets stay out of the final image.

HTTPS via Traefik

Attach a domain in Pier; the running container is fronted with Let's Encrypt TLS automatically.

Webhook redeploys

When pointed at a Git repo, configure a webhook so each push triggers a rebuild and redeploy.

Use cases

When Railpack won't cut it

You need a system package, custom base image, multi-stage build, or build trick Railpack doesn't auto-detect. Write the Dockerfile.

Legacy apps with hand-tuned Dockerfiles

Your existing Dockerfile reflects years of build tuning — keep it, ship it through Pier.

Strict image control

You want a specific base image (distroless, scratch, Alpine), specific user, specific layer order — Dockerfile is the only way.

Builds with secrets

BuildKit secrets keep credentials out of the final image. The Dockerfile template supports them; Railpack and Image don't.

Single-file utility containers

Tiny scripts, init containers, sidecars — paste a 10-line Dockerfile inline, deploy.

Code examples

Minimal Node.js Dockerfile (paste inline) dockerfile 
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]
Multi-stage Go build (~10 MB image) dockerfile 
FROM golang:1.23 AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /app/server ./cmd/server

FROM gcr.io/distroless/static-debian12
COPY --from=builder /app/server /server
EXPOSE 8080
USER nonroot:nonroot
ENTRYPOINT ["/server"]
Python with system packages dockerfile 
FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
      ffmpeg libsndfile1 \
  && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
BuildKit secret (npm private registry token) dockerfile 
# syntax=docker/dockerfile:1
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN --mount=type=secret,id=npm_token \
    export NPM_TOKEN=$(cat /run/secrets/npm_token) && \
    echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > ~/.npmrc && \
    npm ci --omit=dev && \
    rm ~/.npmrc
COPY . .
CMD ["node", "server.js"]

How it compares

vs Railpack (this catalog) Railpack auto-detects and writes a build plan for you. Dockerfile is when you need explicit control or Railpack's detection isn't right. Many teams start with Railpack and move to Dockerfile for specific services that need it.
vs Docker Image (this catalog) Docker Image runs a prebuilt image. Dockerfile builds an image from source. Use Image when CI builds for you; Dockerfile when you want Pier to build.
vs Docker Compose (this catalog) Compose orchestrates multiple containers. Dockerfile builds and runs ONE. Use Compose for multi-service stacks (it can also build from Dockerfiles per service).
vs Buildpacks (CNB) CNB is the spec behind Heroku/Paketo style builders. Railpack is the simpler modern alternative on Pier. Dockerfile is the lower-level escape hatch.

Frequently asked questions

Build from a Git repo URL or paste inline — which?
Inline for tiny test containers and one-offs. Git URL for everything you'll iterate on — push to repo, redeploy.
How big can my context be?
The build context is uploaded to Pier — keep it modest. .dockerignore aggressively. Large contexts slow builds.
BuildKit caching?
BuildKit layer cache lives on the Pier host. Repeated builds reuse layers based on COPY hashes. Typical 80%+ cache hit on incremental code changes.
Multi-arch builds?
Pier builds for the host architecture. For multi-arch images, build in CI (where you can buildx) and ship via the Docker Image template.
Private base images?
Add registry credentials in Pier Settings → Registries — they're used for both FROM pulls and image pushes.
How do build secrets work?
Add a secret in Pier UI, reference it in the Dockerfile via --mount=type=secret,id=NAME. BuildKit keeps it out of the final layers.
Webhook redeploys?
If using Git URL mode, generate a webhook URL in Pier and add it to your Git host. Each push triggers a rebuild and rollout.

Related services

Deploy on your VPS

Bring your own Dockerfile and Pier builds the image, runs the container, and wires it up. Paste the Dockerfile inline or point at a Git repo containing one. Useful when you need full build control — exotic system packages, multi-stage builds, custom entrypoints — that auto-builders (Railpack) can't express.

Deploy this service →