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.

Ployz deploys are explicit, phase-aware operations. You run ployzctl deploy, Ployz inspects the cluster, builds a plan, starts candidate containers, and commits routing facts — in that order. Every step is visible. The deploy either completes cleanly or fails with a clear reason; there is no silent partial state.

​
Deploying from a manifest

The primary deploy path reads a manifest file that describes your namespace, services, and volumes: 
ployzctl deploy -f deploy.toml
FlagDescription
-f, --filePath to the manifest file (TOML or JSON)
-n, --dry-runPreview the plan without applying any changes
Run a dry run first to see exactly what Ployz will do before committing anything: 
ployzctl deploy -f deploy.toml --dry-run

​
Manifest structure

A minimal manifest declares a namespace and at least one service: 
{
  "namespace": "production",
  "services": [
    {
      "name": "web",
      "placement": {
        "replicated": { "count": 2 }
      },
      "template": {
        "image": "myapp:sha256-abc123",
        "env": {
          "PORT": "8080"
        }
      },
      "network": "overlay",
      "service_ports": [
        { "name": "http", "container_port": 8080, "protocol": "tcp" }
      ],
      "readiness": {
        "http": { "service_port": "http", "path": "/healthz" },
        "start_period": "10s"
      },
      "restart": "unless-stopped"
    }
  ]
}

​
Previewing a deploy

deploy preview computes the plan against current cluster state and prints it without making any changes. It is equivalent to deploy --dry-run but available as an explicit subcommand: 
ployzctl deploy preview -f deploy.toml
The preview shows participating machines, service changes (create, replace, or unchanged), volume moves, and any warnings about unreachable participants.

​
Deploying a service inline

For quick one-off deploys, deploy service accepts service parameters directly as flags instead of a manifest file: 
ployzctl deploy service my-api \
  --image registry.example.com/my-api:sha256-def456 \
  --namespace production \
  --publish 8080:8080 \
  --env PORT=8080 \
  --env LOG_LEVEL=info \
  --volume /data:/app/data \
  --network overlay \
  --pull \
  --restart unless-stopped
FlagDescription
nameService name (positional, required)
--imageContainer image reference (required)
--namespaceNamespace to deploy into (required)
-p, --publishPort mapping in HOST:CONTAINER format
-e, --envEnvironment variable in KEY=VALUE format; repeatable
-v, --volumeVolume mount in SRC:DST format; repeatable
--networkNetwork attachment (default: overlay)
--pullForce pulling the image before starting
--restartRestart policy (default: unless-stopped)
-n, --dry-runPreview the service deploy without applying
Use --dry-run with deploy service to verify placement and flag any issues before the container starts.

​
Deploy phases

Every deploy moves through a fixed sequence of phases:
1

Plan

Ployz reads the manifest, resolves the current cluster state from the store, and builds a placement plan. It checks image availability, probes participant machines for live capacity, and validates that preconditions are met. The deploy fails here — before any mutation — if preconditions are missing.
2

Apply

Candidate containers start on their assigned machines. Volume moves and ZFS transfers happen in phase order. For multi-phase deploys, each phase runs to completion before the next begins. The cluster is in transition during this step.
3

Commit

Ployz appends an immutable deploy commit to the control-plane store. This is the point of no return. Routing facts are published and the gateway and DNS rebuild from the committed state. Traffic switches to the new instances.
4

Cleanup

Old instances are drained and removed. If cleanup fails, the failure is recorded as visible status — it does not roll back the commit or erase the fact that the new version is live.

​
The commit boundary

The commit point is where routing flips. Before the first commit, any failure aborts the deploy and the cluster returns to its prior state. After a checkpoint commit, a later failure is reported as FailedAfterCheckpoint — the committed facts remain durable and traffic is already on the new version.
Cleanup failures after the commit do not indicate a failed deploy. The new version is live. The FailedAfterCheckpoint status means old instances may need manual cleanup. Check ployzctl status for details.

​
Building images locally

If you need to build a container image before deploying, use the build local command: 
ployzctl build local \
  --method dockerfile \
  --image myapp:latest \
  ./app
FlagDescription
--methodBuild method: dockerfile or railpack
--imageTarget image name and tag (required)
--platformTarget platform (e.g. linux/amd64)
CONTEXTBuild context directory (positional, required)
After building, push the image to your cluster machines with ployzctl image push before deploying with a pull: never policy.

​
Next steps

Branch and promote

Fork a namespace for a PR, then atomically promote it to production.

Rollback

Restore the previous deploy point, including persistent state.

Build docs developers (and LLMs) love

Get started for freeTalk to us