Containerfile and multi-stage builds with Podman on Fedora

No Docker is needed to build images on Fedora: podman build reads a Containerfile (Dockerfile syntax is fully compatible).

podman --version
dnf list --available buildah | tail -1

podman version 6.1.0
buildah.x86_64   2:1.45.1-1.fc45   fedora

Containerfile or Dockerfile

Both names work and the syntax is identical. Podman looks for Containerfile first, then Dockerfile.

podman build -t myapp:1 .
podman build -f Containerfile -t myapp:1 .

Convention: Containerfile for Podman/Buildah, Dockerfile for Docker. Mixing them breaks nothing.

Multi-stage builds: why they matter

Compiled languages (Go/Rust/Java) need large build dependencies that the runtime does not. Multi-stage builds separate the build environment from the runtime so only the binary ships.

Measured with a small Go program:

mkdir -p /tmp/cf && cd /tmp/cf
cat > Containerfile <<'EOF'
FROM docker.io/library/golang:1.27-alpine AS build
WORKDIR /src
RUN echo 'package main' > main.go && echo 'import "fmt"' >> main.go && echo 'func main(){ fmt.Println("built in stage 1") }' >> main.go
RUN go build -o /out/hello main.go

FROM docker.io/library/alpine:latest
COPY --from=build /out/hello /usr/local/bin/hello
CMD ["hello"]
EOF
podman build -t demo:1 .

podman images --format "{{.Repository}}:{{.Tag}} {{.Size}}" | grep demo
podman run --rm demo:1

localhost/demo:1 11.1 MB
built in stage 1

The final image is 11.1 MB. A single-stage build would carry the whole Go toolchain — hundreds of megabytes.

Approach	Final size	Note
single stage (golang base)	hundreds of MB	compiler and sources stay in the image
multi-stage (measured)	11.1 MB	only the binary and the alpine base

COPY --from=build is the key: it pulls files from the previous stage, which itself never enters the final image.

Layers and caching

Every RUN/COPY is a layer, and layer order decides cache hits:

# bad: a one-line code change reinstalls every dependency
COPY . /app
RUN npm install

# good: install dependencies first, copy code last
COPY package.json package-lock.json /app/
RUN npm install
COPY . /app

The effect is visible:

podman build -t demo:1 .          # first build: everything
podman build -t demo:2 .          # second build: every layer cached

STEP 1/3: FROM ...
--> Using cache

--> Using cache marks a hit. After a code change only the layers after COPY . /app rebuild.

Where buildah fits

Tool	Good for
podman build	everyday builds
buildah	scripting, fine-grained work without a daemon, stepwise CI builds
podman buildx	multi-architecture builds

sudo dnf install buildah
buildah --version

buildah can build without any Containerfile:

ctr=$(buildah from alpine)
buildah run $ctr -- apk add --no-cache curl
buildah commit $ctr mycurl:1
buildah rm $ctr

Note

podman build calls buildah internally. Use podman day to day, and reach for buildah when you need layer-level control or cross-architecture work.

Pushing to a local registry

podman run -d --name registry -p 5000:5000 docker.io/library/registry:2
curl -s http://127.0.0.1:5000/v2/_catalog

Tag and push:

podman tag demo:1 127.0.0.1:5000/demo:1
podman push 127.0.0.1:5000/demo:1
curl -s http://127.0.0.1:5000/v2/_catalog

{"repositories":["demo"]}

Caution

A registry on localhost/127.0.0.1 is treated as plain HTTP. Switch to a hostname or IP and Podman demands HTTPS unless you add an insecure [[registry]] entry in /etc/containers/registries.conf.

Common traps

Symptom	Cause
base image pull times out	no registry mirror; see domestic mirrors
enormous image	single-stage build kept the toolchain
code changed but the build did not	an unintended cache hit; check COPY order or use --no-cache
COPY --from=build cannot find the stage	the AS build name must match exactly
push to port 5000 fails	registry not running, or SELinux/firewall blocking the port
multi-arch build fails	qemu-user-static and podman build --platform are required

Related pages

• Podman in practice — install, run, mirrors, Quadlet
• Containers and rootless — uid mapping and security boundaries
• Domestic mirrors — registry mirror setup
• SELinux — the :Z on mounted volumes
• Official: Buildah documentation