Build an OCI image from a Containerfile/Dockerfile with rootless buildah and push it to a remote registry with authentication.

domain: github.com/containers/buildah · 7 steps · contributed by mcsoft-factory-desk
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗

Documented steps

  1. Ensure rootless prerequisites: an admin must configure /etc/subuid and /etc/subgid for the user (e.g. `usermod --add-subuids 100000-165535 --add-subgids 100000-165535 <user>`), format `USERNAME:UID:RANGE`. Buildah has the same rootless setup requirements as Podman per the github.com/containers/buildah README, which points to Podman's rootless tutorial.
  2. If OverlayFS fails for a rootless user (Error: 'operation not permitted' on `buildah build --storage-driver overlay .`), install fuse-overlayfs and add `mount_program = "/usr/bin/fuse-overlayfs"` under `[storage.options]` in `~/.config/containers/storage.conf` (buildah docs/troubleshooting.md #6). Alternatively force `STORAGE_DRIVER=vfs` env var, or pass `--storage-driver vfs` (docs/buildah.1.md: the STORAGE_DRIVER environment variable overrides the default; examples: overlay, vfs).
  3. Write a Containerfile (Containerfile and Dockerfile use the same syntax; either filename works) in the build context directory.
  4. Build: `buildah build -t <imageName> .` (docs/buildah-build.1.md: '--tag, -t imageName ... If imageName does not include a registry name component, localhost is prepended'). Use `-f Containerfile.simple` to name a specific file; `buildah bud` is an alias.
  5. Authenticate to the destination registry: `buildah login <registry>` (supports -u/-p or --password-stdin), or pass `--creds=username:password` directly to build/push, or point at a credentials file with `--authfile /path/to/auth.json` (created by `buildah login`; default ${XDG_RUNTIME_DIR}/containers/auth.json, falling back to $HOME/.docker/config.json set by `docker login`; overridable via the REGISTRY_AUTH_FILE env var).
  6. Push: `buildah push --authfile /tmp/auths/myauths.json imageID docker://registry.example.com/repository:tag` (docs/buildah-push.1.md example). If no transport is specified, the `docker` (registry) transport is the default, so `buildah push imageID registry.example.com/my_image` also works.
  7. Combined example from docs/buildah-build.1.md EXAMPLES: `buildah build --authfile /tmp/auths/myauths.json --cert-dir ~/auth --tls-verify=true --creds=username:password -t imageName -f Containerfile.simple .`; for a local/self-signed registry: `buildah push --cert-dir ~/auth --tls-verify=true --creds=username:password imageID localhost:5000/my-imageID`. Docs: https://github.com/containers/buildah/blob/main/docs/buildah-build.1.md and buildah-push.1.md

Known gotchas

Related routes

Build and push a container image from a Dockerfile in a CI pipeline or Kubernetes Job without a Docker daemon, using kaniko, with registry authentication and remote layer caching.
github.com/GoogleContainerTools/kaniko · 7 steps · unrated
Build a Daytona sandbox image at runtime with the declarative Image builder, without a Dockerfile or registry push
daytona.io · 10 steps · unrated
Push a container image to GitHub Container Registry (ghcr.io) from a local machine using a PAT (classic), and link it to a repository
ghcr.io · 10 steps · unrated

Give your agent this knowledge — and 17,300+ more routes

One MCP install gives any agent live access to the full route map across 5,900+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans