podplane build
Builds an OCI container image from a Containerfile or Dockerfile using the ocimage library and stores it in Podplane’s local registry cache. Images built this way are immediately available to any local Podplane cluster/VM.
podplane build [PATH] [flags]If no tag is provided, Podplane detects an app name from project metadata such as package.json, go.mod, Cargo.toml, or a single .csproj, then tags the image as:
default-registry.local/apps/<app-name>:latestExplicit tags are normalized into the local registry’s apps/ namespace. For example, -t api, -t api:v1, and -t apps/api:v1 are stored as apps/api and printed as default-registry.local/apps/api:<tag>. Tags with a local registry host, such as default-registry.local/apps/api:v1 or other-registry.local/apps/api:v1, are accepted and stored in the same shared registry cache path, apps/api.
podplane build rejects tags outside apps/, remote registry tags such as ghcr.io/me/api:v1, and mirror/ tags. The mirror/ namespace is reserved for Podplane-managed dependency mirrors.
After a successful build, Podplane prints a podplane deploy web ... --image <built-image> example and a podplane logs <name> command.
Containerfile and Dockerfile detection
If --file is not set, ocimage selects the default build file. When neither Containerfile nor Dockerfile exists, Podplane tries to generate a conservative Containerfile for self-contained project templates such as Go, Rust, C# ASP.NET, and supported TypeScript examples - see ocimage examples for the reference Containerfile examples.
Note: Containerfile is the OCI-neutral name for what many tools historically called a Dockerfile. You can still use Dockerfile if you prefer.
If multiple supported templates match, Podplane prompts you to choose one. If no safe template matches, Podplane prints an error and asks you to create a Containerfile or Dockerfile first.
ocimage and Docker fallback
Podplane first tries to build with its built-in ocimage support directly. If your Containerfile or Dockerfile uses syntax ocimage cannot build, such as RUN or multi-stage COPY --from, Podplane falls back to Docker Buildx when available.
The fallback runs one docker buildx build --output type=docker,dest=... build per target platform, then imports the resulting Docker archive into Podplane’s local registry cache under the same normalized apps/ tag. This approach enables support for multi-arch image builds on par with the ocimage approach and avoids leaving temporary images in Docker’s local image store.
If Docker or Buildx is not available, Podplane prints the unsupported instruction with file and line context and asks you to either simplify the build file or install Docker with Buildx support.
Options
| Flag | Description |
|---|---|
-f, --file string | Name of the Containerfile or Dockerfile |
-t, --tag stringArray | Name and optionally a tag. May be specified multiple times. |
--platform string | Target platform(s), comma-separated. Defaults to the local Podplane VM architecture. |
--build-arg KEY=VALUE | Set build-time variables. May be specified multiple times. |
--label KEY=VALUE | Set image labels. May be specified multiple times. |
--docker[=PATH|false] | Use Docker Buildx fallback, optionally with a Docker binary path. Defaults to docker; use --docker=false to disable fallback. |
--pull | Always attempt to pull base images instead of using the local OCI store first |
--sbom[=true|false] | Generate an SBOM attestation with syft |
Docker-compatible flags that ocimage does not support, such as --target, --no-cache, --output, and --provenance, fail with a friendly error.
Examples
Build the current directory and use Podplane’s default local image name:
podplane buildBuild with an explicit tag:
podplane build -t api:v1 .Build with an explicit file and build argument:
podplane build -f Containerfile --build-arg VERSION=1.2.3 .Equivalent ocimage flow inside a cluster
podplane build is optimized for local VM development: it writes directly into the local registry cache and prints a deploy command.
If you need to build and push a container image from inside a cluster, a build pod/container should use the lighter-weight, lower-level ocimage commands instead:
ocimage build -t apps/api:v1 .
ocimage push apps/api:v1 default-registry.local/apps/api:v1The first command writes the image to the pod’s ocimage store (which can be overridden using OCIMAGE_STORE env var). The second command pushes that stored image to the cluster registry under the same apps/ namespace that podplane build uses locally.
If the build pod should publish to a different local Podplane registry host, push to that host explicitly:
ocimage push apps/api:v1 other-registry.local/apps/api:v1Keep user-built app images under apps/. The mirror/ namespace is reserved for Podplane-managed dependency mirrors.