Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 37 ยท Building and Registries

Building Images with a Containerfile

Build container images with podman build and a Containerfile: instructions, layers and caching, build arguments, .containerignore, OCI vs Docker format and Buildah relationship.

An image is a packaged filesystem plus metadata (the command to run, environment variables, exposed ports). A Containerfile is the recipe that produces one: a text file of instructions, executed from top to bottom. Podman reads files named Containerfile or Dockerfile; the format is the same, so existing Dockerfiles work unchanged.

This lesson covers the instructions you will use every day, how layers and the cache decide build speed, and the options of podman build. Builds need a real Podman, so commands are read-only; the stand-ins are a Containerfile linter and a layer-cache simulator you can experiment with.

Podman and Buildah

podman build is powered by Buildah, a sibling project focused only on building images. Buildah is a library inside Podman, so you do not need to install it separately for podman build, but the buildah command exists too and is useful for scripted builds:

Terminal
ctr=$(buildah from docker.io/library/alpine:3)
buildah run $ctr -- apk add --no-cache curl
buildah config --cmd 'curl --version' $ctr
buildah commit $ctr localhost/alpine-curl

Everything in this course uses the Containerfile approach, which is easier to read and review.

A first Containerfile

DOCKERFILE
FROM docker.io/library/python:3.13-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
USER 1000
EXPOSE 8000
CMD ["python", "-m", "http.server", "8000"]

Build and run it:

Terminal
podman build -t localhost/myapp:1.0 .
podman run --rm -p 8000:8000 localhost/myapp:1.0

-t names the image; . is the build context, the folder whose files COPY can see. Use -f path/Containerfile for a file elsewhere.

The instructions

Instruction Purpose
FROM image Starting point; every build begins with one
RUN cmd Run a command and save the result as a new layer
COPY src dest Copy files from the build context
ADD src dest Like COPY, plus URL and archive extraction (prefer COPY)
WORKDIR dir Set the working directory (creates it)
ENV K=V Environment variable, kept in the image
ARG K=V Build-time variable, not kept at run time
USER name Run later instructions and the container as this user
EXPOSE port Document a port; does not publish it
ENTRYPOINT / CMD What runs when the container starts
LABEL k=v Metadata
VOLUME path Declare a mount point
HEALTHCHECK Health command (needs the Docker image format, below)

ENTRYPOINT is the fixed program, CMD the default arguments that podman run image args... replaces. Always use the exec form (JSON array) so signals reach your program and podman stop works quickly.

Layers and the cache

Each RUN, COPY and ADD creates a layer. Podman remembers the result: on the next build, if an instruction and everything before it are identical, it reuses the layer. The moment one instruction changes, that layer and all later ones are rebuilt. So order matters:

  • Put things that rarely change first (installing system packages, dependency files).
  • Put things that change often last (your source code).

In the example above, requirements.txt is copied before the rest of the code, so editing a source file does not reinstall every dependency.

Python Layer cache simulator (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice the "bad order" build reinstalls dependencies even though only source changed, because the source COPY came before pip install.

Build options you will use

Terminal
podman build -t name:tag .                   # basic
podman build --no-cache -t name:tag .        # ignore the cache
podman build --build-arg VERSION=2 -t name .  # sets ARG VERSION
podman build --target test -t name:test .    # stop at a named stage
podman build --platform linux/arm64 -t name . # other architecture (needs emulation)
podman build --secret id=npm,src=$HOME/.npmrc -t name .
podman build --format docker -t name .       # Docker image format

Secrets are mounted only during the instruction that asks for them, so they are not stored in a layer:

DOCKERFILE
RUN --mount=type=secret,id=npm,target=/root/.npmrc npm ci

OCI versus Docker format

Podman builds images in the OCI format by default. OCI images do not support the HEALTHCHECK instruction. If you rely on it, build with --format docker (or set the health check at run time instead, with --health-cmd). Both formats run identically in Podman.

Keeping the context small: .containerignore

Everything in the build context is sent to the build. A .containerignore (or .dockerignore) file excludes files, which speeds up builds and keeps secrets out:

TEXT
.git
node_modules
*.log
.env

Linting a Containerfile

Review habits can be automated. This stand-in applies a handful of common checks and prints findings; real linters such as Hadolint cover far more.

Python Containerfile linter (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Good habits

  • Pin base image versions (python:3.13-slim, not latest) so builds are repeatable.
  • Combine related RUN steps and clean caches in the same step (apt-get install -y ... && rm -rf /var/lib/apt/lists/*).
  • Use COPY, not ADD, unless you need ADD's special behavior.
  • Run as a non-root USER.
  • Use multi-stage builds to keep tools out of the final image: next lesson, Multi-Stage Builds and Build Caching.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens to layers after an instruction that changed?

    A changed instruction invalidates its layer and every later layer in the build.
  2. 2. Why copy requirements.txt before the rest of the source?

    The pip install layer stays cached until requirements.txt changes.
  3. 3. What is the build context?

    The directory passed to podman build (usually .) is sent to the build and is the only source for COPY.
  4. 4. Why might HEALTHCHECK seem ignored in a Podman-built image?

    The OCI image format has no health check field. Use --format docker or define the check at run time.

Summary

  • A Containerfile (or Dockerfile) is the recipe; podman build -t name . builds it with Buildah's engine.
  • Layers are cached; put rarely-changing steps first and frequently-changing steps last.
  • Use exec-form CMD/ENTRYPOINT, pin base images, prefer COPY, run as a non-root user.
  • --build-arg, --target, --platform, --secret and --format adjust builds; .containerignore trims the context.
  • OCI is the default format and lacks HEALTHCHECK; use --format docker when needed.

Next: Multi-Stage Builds and Build Caching