Build Images

mactain build builds an OCI image from a local context directory. Use it when you have a Dockerfile or Containerfile and want the resulting image available to MacTain containers or exported as an OCI layout, tar, or local output.

Command Reference

Command or option	Description	Typical use
`mactain build -t <reference> <context>`	Builds an image and tags it.	Build a local image from the current project.
`--file <path>`, `-f <path>`	Selects a build file.	Use a non-default Dockerfile or Containerfile path.
`--tag <reference>`, `-t <reference>`	Assigns an image tag. Repeatable and required.	Tag an image for local run or registry push.
`--build-arg <KEY=VALUE>`	Sets build-time variables.	Pass non-secret build arguments.
`--label <KEY=VALUE>`	Sets image metadata labels.	Add metadata to the built image.
`--pull`	Refreshes or pulls Dockerfile base images.	Avoid stale base images.
`--no-cache`	Disables layer cache reuse.	Rebuild everything when cache may be wrong.
`--platform <os/arch>`	Sets a target platform.	Build one target such as `linux/arm64` or `linux/amd64`.
`--os <os> --architecture <arch>`	Split form of target platform.	Use when scripting OS and architecture separately.
`--target <stage>`	Builds one Dockerfile stage.	Build a named multi-stage target.
`--output image`	Keeps the default image-store load.	Build and run locally with MacTain.
`--output oci=<path>`	Exports an OCI layout.	Move images through a source-backed portable format.
`--output tar=<path>`	Exports a tar output.	Produce an archive output from the build.
`--output local=<path>`	Exports local filesystem output.	Extract build artifacts.
`--progress <auto\|plain\|tty>`	Controls progress rendering.	Use `plain` for logs and CI.
`--cpu <count>`	Sets build CPU resource limit.	Bound build resource usage.
`--memory <mib>`	Sets build memory resource limit in MiB.	Bound memory-heavy builds.
`--quiet`, `-q`	Suppresses non-essential output.	Scripted output when details are unnecessary.
`--json`	Prints JSON output.	Automation and CI.

Defaults And Behavior

If --file is omitted, MacTain resolves Dockerfile first, then Containerfile in the context directory.
--tag is required and can be repeated.
Baseline Dockerfile instruction support includes RUN, HEALTHCHECK, and ONBUILD; ONBUILD triggers execute for downstream stages in the same build.
--label is repeatable. Duplicate label keys use the last value.
--platform cannot be combined with --os and --architecture.
--os must be paired with --architecture.
linux/amd64 builds on Apple Silicon use the current Rosetta-first build path when Rosetta is available.
The current build surface is single-platform per invocation.
--secret, --ssh, --cache-from, and --cache-to are accepted in help but deferred; current builds return deterministic invalid-argument behavior for those flags.
SBOM, provenance, attestation, QEMU fallback, and multi-platform-per-build are future scope and should not be documented as supported.

Practical Use Cases

Use case: build an image for local MacTain containers

Use this when your project has a Dockerfile in the current directory.

mactain build -t localhost/acme-api:dev .
mactain image inspect localhost/acme-api:dev
mactain container start \
  --name acme-api \
  --image localhost/acme-api:dev \
  --publish 8080:8080 \
  --detach

Use a local reference while iterating. Tag with a registry reference before pushing.

Use case: build with explicit file, target, and plain progress

Use this for a multi-stage build or CI-like output.

mactain build \
  --file ./build/Containerfile \
  --target runtime \
  --progress plain \
  -t ghcr.io/acme/app:dev \
  .

--progress plain is easier to review in logs than terminal-oriented output.

Use case: export an OCI layout

Use this when you need a portable image layout instead of only loading the image into MacTain's local image store.

mactain build \
  --output oci=/tmp/acme-app-oci \
  -t ghcr.io/acme/app:dev \
  .
mactain image import localhost/acme-app:copy --input oci=/tmp/acme-app-oci

Use Images for import, export, and image inventory commands after the build.

Use case: bound build resources

Use this when a build consumes too much local CPU or memory.

mactain build \
  --cpu 4 \
  --memory 4096 \
  -t ghcr.io/acme/app:dev \
  .

If the build fails after lowering resources, raise the limits or inspect the Dockerfile stage that needs more memory.

Troubleshooting Entry Points

Build file is not found: pass --file or run from the intended context directory.
Build needs private base images: configure Registry credentials.
Deferred flags fail: remove --secret, --ssh, --cache-from, or --cache-to until those Build v2 Phase 2 behaviors ship.
A built image does not run: inspect it with Images and start a container with explicit logs from Containers.

Next Steps

Continue to Images to inspect, tag, push, or export the built image. Continue to Registry credentials before pushing to a private registry.