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

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": { "min": 0, "max": 2, "concurrency": 500 }
}
  • ingress.domains — the hostname(s) the service answers on. For an internal-only service, use { "public": false } instead.
  • scaling.min: 0 — the service scales to zero when idle and cold-starts on the next request. Set min: 1 to keep one instance warm.

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 config           # the config the running revision resolves
putnami cloud whoami           # the identity that owns the deploy

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