contember/zerops-contrib/zerops

Zerops

Zerops is a PaaS running on bare metal. You describe infrastructure in import YAML and the build/run pipeline in `zerops.yaml`. Both are YAML, both mention services, and they are not interchangeable — confusing them is the single most common failure.

The two YAML files

A service must already exist (via import or GUI) before zerops.yaml can target it. The setup: name in zerops.yaml matches the service hostname unless overridden by zeropsSetup / --setup.

Mental model

Project → private VXLAN network + L7 balancer + core (logger, stats, firewall, SSL). Service → one addressable unit, reachable at <hostname>:<port> from any sibling. Container → the replicas of a service. Runtimes and Linux containers scale 1–10; managed services have a fixed count set by the :single / :ha type variant. Containers are ephemeral and replaced on every deploy.

Managed services (databases, caches, search, queues, storage) are provisioned, not built. Runtime services (nodejs, php, go, …) are built from your repo by the pipeline.

Import is create-only. Re-importing a file updates nothing, and override: true replaces a runtime service and forces a redeploy — so a committed import YAML is a bootstrap script, not a declaration of state, and it drifts from the first GUI change onwards. Where you want it to behave like infrastructure-as-code, use zops apply -f <import.yaml>: it creates what is missing, converges the fields the API can change in place, and reports the rest instead of pretending. See references/zops-cli.md.

zops ships with this plugin — run it as "$CLAUDE_PLUGIN_ROOT/bin/zops", which needs only Bun. Pages below write plain zops for readability.

Minimal working example

zerops-import.yaml — provision once:

project:
  name: myapp
  corePackage: LIGHT
services:
  - hostname: app
    type: alpine/nodejs@22
    enableSubdomainAccess: true   # .zerops.app subdomain — dev/testing only
    minContainers: 1
    maxContainers: 2
  - hostname: db
    type: postgresql:single@18
    profile: oltp-hobby

zerops.yaml — committed to the repo root:

zerops:
  - setup: app
    build:
      base: alpine/nodejs@22
      buildCommands:
        - npm ci
        - npm run build
      deployFiles:            # the whole runtime filesystem, not just build output
        - ./dist
        - ./package.json
        - ./node_modules      # omit only if the build bundles dependencies
      cache: node_modules
    run:
      base: alpine/nodejs@22
      ports:
        - port: 3000
          httpSupport: true
      envVariables:
        DATABASE_URL: ${db_connectionString}
      start: node dist/server.js

Then zcli push.

Webserver runtimes (php-apache, php-nginx, nginx, static) are shaped differently — no start, no ports. See references/zerops-yaml.md.

Rules that break apps when ignored

1. Bind `0.0.0.0`, never 127.0.0.1/localhost — the #1 cause of 502 from the balancer.
2. Internal HTTP is plain `http://` — TLS terminates at the L7 balancer, so https://api:3000

fails. This is about HTTP between services; non-HTTP protocols just connect to hostname:port with their own TLS rules (Postgres 5432 plaintext but 6432 TLS-required, Valkey 6379 plaintext / 6380 TLS).

1. Cross-service env vars are NOT auto-injected. Under the default envIsolation: service you

must declare DB_HOST: ${db_hostname} in run.envVariables. An unresolved ${...} reaches the process as a literal string — no error, no blank.

1. Never write `FOO: ${FOO}` (same name both sides) — it self-shadows and resolves to the literal

${FOO}. Project variables are already inherited; just read them.

1. The container filesystem is replaced on every deploy. Restarts keep it; deploys and scale-ups

do not. Uploads → object storage, sessions → Valkey, SQLite or a single-node stateful app → Local storage (run.volume). Shared storage is deprecated: converted services are SeaweedFS and the runtime mounts them itself.

1. `build.deployFiles` is the entire runtime filesystem, not a list of build outputs. Nothing

reinstalls dependencies at runtime — an unbundled app must ship node_modules / vendor and its manifest too.

1. Each command list item runs in its own shell. cd and export do not carry to the next item;

use a | block scalar when they must.

1. `run.initCommands` run on every container start, in parallel across containers, and a

non-zero exit aborts the deploy. Gate once-per-version work with zsc exec-once ${ZEROPS_appVersionId} -- <cmd> (execOnce still works).

1. Write the OS in every type and base (alpine/nodejs@22, ubuntu/nodejs@22). A bare

version resolves to Ubuntu in import but Alpine in zerops.yaml, and every deploy rewrites the service's OS to match run.base. The os: key is deprecated.

1. HA is immutable. postgresql:single@18 → postgresql:ha@18 is a new service, not an edit —

back up and migrate the data first (references/operations.md).

Where to look

Read only the file you need.

Version tables in references/service-catalog.md are generated — refresh with the repository's scripts/sync-docs.sh (--check to inspect drift first).

Editor validation

Both files have official JSON Schemas, auto-applied via SchemaStore when named zerops.yaml / zerops.yml and zerops-import.yaml / zerops-*-import.yaml. URLs and the modeline for non-standard filenames are in references/zerops-yaml.md and references/import-yaml.md. Prefer schema validation in the editor over guessing key names.

zops schema zerops and zops schema import print the same schemas from the live API, which is the way to read one before writing either file rather than guessing. For zerops.yaml, zops validate -S <service> is the stronger check — it also resolves the target service's type and version, which a schema cannot.

Verification loop

Never claim a deploy works without evidence:

zcli push                                   # build + deploy, streams the build log
zcli service log -S <service-id> --follow   # runtime log
zcli service log -S <service-id> --show-build-logs
zcli service log -S <service-id> --message-type WEBSERVER   # 502s on nginx/apache runtimes

With zops (references/zops-cli.md) the same loop is exit-code driven, which is what you want when scripting it: zops push api exits 8 if the build or deploy failed and 7 if it is still running, so no log parsing is needed to decide what happened.

zops push api                                 # waits; exit 8 = failed, 7 = still running
zops logs api --build                         # why it failed
zops status                                   # project-wide state in one call

Then reach the app. Internally from any sibling or over the VPN — this always works and does not depend on public access being configured:

curl -sS http://app:3000/health

Publicly, the subdomain is {hostname}-{prefix}[-{port}].{rest}, e.g. https://app-1df2-3000.prg1.zerops.app. Do not compose it from memory — read the real value from the GUI or zcli project env, because the port suffix and region segment vary. See references/networking.md.

With the zcp MCP server connected, zerops_verify does the health + readiness probe and zerops_events the deploy history — same evidence, fewer steps. See references/zcp-mcp.md.

Build has a hard 60-minute limit. stack.build reaching FINISHED means the build is done; the deploy is done when the new appVersion is ACTIVE. Neither proves the app does what was asked — a green build means Zerops accepted it, reachability means the process is up. Check the actual behavior.

That is not a platitude. Verified live: a zerops.yaml whose start was sleep 3600 validated, built, deployed and reported ACTIVE exactly like the real one — the only symptom was a 502. And a deployment can serve /healthz 200, serve its admin page, and still refuse every browser sign-in, because TLS terminates at the balancer and the app compares the Origin header against its own internal http scheme. Exercise the behaviour you care about, including one authenticated request, before calling a deploy done.