Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/getployz/ployz/llms.txt

Use this file to discover all available pages before exploring further.

The build command builds container images on the local machine and registers them with the cluster. Builds run on the machine where you invoke ployzctl, using either a standard Dockerfile or Railpack for automatic language detection. The resulting image is available for distribution to cluster nodes and subsequent deploys. 
ployzctl build <subcommand> [flags]

​
Build methods

Ployz supports two build methods:
MethodDescription
dockerfileStandard Docker image build. The daemon uses the Dockerfile in the build context directory.
railpackAutomatic language detection and build plan generation. No Dockerfile required — Railpack inspects the project and determines the appropriate build steps.
Use railpack for standard application stacks (Node.js, Python, Ruby, Go, etc.) when you do not want to maintain a Dockerfile. Use dockerfile when you need precise control over the build.

​
Subcommands

Build a container image from a local directory and register it with the daemon. The context directory is the root of the files sent to the builder.
ployzctl build local --method <method> --image <image> [--platform <platform>] <context>
Positional arguments
​
context
PATH
required
Path to the build context directory. All files in this directory are sent to the builder. For dockerfile builds, this directory must contain a Dockerfile.
Required flags
​
--method
dockerfile | railpack
required
The build method to use. dockerfile uses the Dockerfile in the context; railpack auto-detects the build plan.
​
--image
IMAGE
required
The name and optional tag to assign to the built image, e.g. myapp:latest or ghcr.io/myorg/app:v1.2.3. This name is used for distribution and deploy references.
Optional flags
​
--platform
string
Target platform in os/arch format, e.g. linux/amd64 or linux/arm64. If omitted, the builder uses the host platform.
The response includes an operation ID, the built image artifact (digest, size, platform), and an availability record if the image was registered locally.
# Build using Dockerfile
ployzctl build local --method dockerfile --image myapp:latest ./

# Build using Railpack for a Node.js project
ployzctl build local --method railpack --image myapp:latest ./app

# Build for a specific platform
ployzctl build local \
  --method dockerfile \
  --image ghcr.io/myorg/app:v1.2.3 \
  --platform linux/amd64 \
  .
List all build operations tracked by the daemon, including completed, in-progress, and failed builds.
ployzctl build operation list
Use --json for full structured records.
ployzctl --json build operation list
Retrieve the details of a single build operation by its ID.
ployzctl build operation get <id>
​
id
string
required
The operation ID returned when the build was started, or listed by operation list.
The response includes the operation record with status, method, image name, and result artifact.

​
Build and deploy workflow

A typical local build-and-deploy cycle looks like this:
1

Build the image

Build from the project root. Note the digest in the output or retrieve it with --json.
ployzctl --json build local \
  --method dockerfile \
  --image myapp:latest \
  . | tee build-result.json

DIGEST=$(jq -r '.artifact.digest' build-result.json)
2

Distribute to cluster nodes

Push the built image to the machines that will run the workload.
ployzctl image distribute \
  --digest "$DIGEST" \
  --from "$(hostname)" \
  --to machine-a \
  --to machine-b
3

Deploy

Deploy using the image digest to ensure the exact image you built is used.
ployzctl deploy service web \
  --image "myapp@$DIGEST" \
  --namespace production \
  -p 80:8080

​
Examples

# Build with Dockerfile from the current directory
ployzctl build local --method dockerfile --image myapp:latest .

# Build with Railpack from a subdirectory
ployzctl build local --method railpack --image myapp:latest ./src

# Build for linux/amd64 explicitly
ployzctl build local \
  --method dockerfile \
  --image ghcr.io/myorg/app:v1 \
  --platform linux/amd64 \
  .

# List all build operations
ployzctl build operation list

# Get details of a specific build
ployzctl --json build operation get op-abc123

Build docs developers (and LLMs) love

Get started for freeTalk to us