Your first deploy

You will make a project deployable, ship it, and confirm it is running — using only real commands and config.

By the end you will have added one file (infra/runtime.json), run one command (putnami deploy), and released a revision attributable to your commit.

Before you start

Complete the earlier steps once:

  1. Install the cloud extension — putnami deps add @putnami/cloud
  2. Log in — putnami cloud login
  3. Set up the workspace — putnami cloud setup
  4. Check the workspace contracts — know which file owns each change

You also need a project that builds:

putnami build

1) Declare how the project runs

Add infra/runtime.json to the project. Its presence is what makes the project deployable. A minimal scale-to-zero service:

{
  "ingress": { "domains": ["hello.example.com"] },
  "scaling": { "max": 2, "concurrency": 500 }
}
  • ingress.domains — the hostname(s) the service answers on. For an internal-only service, use { "public": false } instead.
  • scaling.max and scaling.concurrency — workload-owned capacity ceilings. Infra protocol v2 does not expose a workload-level min override. The CPA owns the variable-cost posture: the service always scales to zero and cold-starts on the next request.

See Deploy & hosting for every field.

2) Deploy

putnami deploy --wait

--wait blocks until the new revision is Ready (or --timeout fires, default 5m). Deploy runs two stages:

putnami deploy
  ├─ publish   build + push the image, register config, apply migrations
  └─ release   roll out a new revision, then cut traffic over

The release is zero-downtime: the previous revision keeps serving until the new one is Ready.

3) Preview the plan first (optional)

To see what a deploy would do without provisioning anything — and without publishing — ask for the plan:

putnami deploy --preview

It reports a per-project skip or roll decision from the control plane. Nothing is pushed or released.

4) Confirm it

putnami cloud status --env prod --health
putnami cloud config           # the config the running revision resolves
putnami cloud whoami           # the identity that owns the deploy

Status shows the serving revision, the most recent run, recent errors, and whether the served commit is on your local main. It never fetches, so update your local Git refs before relying on the ON MAIN result. If the deploy failed, re-read the CLI output: deploy failures are reported with the failing stage and reason.

Redeploy and roll back

  • Redeploy by running putnami deploy again. Unchanged projects are skipped (their content digest is identical); use --force to re-roll anyway.
  • Roll back is an operator workflow today. The serving revision is retained, but the public cloud CLI does not yet expose a revision-revert command.

Next