Deploy & hosting
A project deploys through an environment that follows a channel. A merge to
main publishes the project's artifacts into an immutable release set and
moves a channel. Every environment that follows that channel then deploys the
projects whose content changed. A project becomes deployable when it has an
infra/runtime.json; that file declares how the service is hosted — ingress,
scaling, resources.
Each release is attributable to a specific commit. Zero-downtime cutover is the default, and the previous revision keeps serving until the new one is Ready.
Deploy
There is no deploy command. You set an environment up once, then merge:
| Want to… | Do this |
|---|---|
| Check what an environment still needs | putnami cloud env doctor <env> |
| Apply the fixes your workspace owns | putnami cloud env enable <env> |
| Deploy | Merge to main; the environment follows its channel |
| See what runs where | putnami cloud env status <env> |
| Read one release | putnami cloud deploy status <release-id> |
| Promote or roll back an environment | `putnami cloud channels set --from <channel |
Start with the walkthrough: Your first deploy. Environments follow channels covers every field and outcome.
Where your image goes
A deploy publishes your container image to the platform OCI registry, then asks the control plane to run that exact digest. You declare one coordinate:
{
"options": {
"publish": { "dockerRegistry": "oci.putnami.dev/<namespace>" }
}
}Declare the bare host or a namespace under it; both work. With nothing declared,
the deploy uses oci.putnami.dev.
The control plane copies the published digest into the registry your runtime pulls from and pins the new revision to the copy. You do not name that registry, grant it access, or know which cloud it belongs to — the request carries only the registry you published to and the digest you published. That is the same request whichever channel move or release triggered the deploy, so every path rolls the identical image.
Declaring a cloud provider registry path instead (for example
<region>-docker.pkg.dev/<project>/<repo>) skips the copy: the revision pulls
straight from where you published. Use it only when you own that registry.
Hosting: infra/runtime.json
A deployable project declares its runtime in infra/runtime.json. The fields
below are verified against services running in production today; the
managed runtime page covers scaling, config, and
bindings in depth.
{
"ingress": { "domains": ["service.example.com"] },
"scaling": { "max": 2, "concurrency": 500 },
"resources": { "cpu": "1000m", "memory": "512Mi" }
}| Field | Meaning |
|---|---|
ingress.domains |
custom hostnames the service answers on |
ingress.public |
set false for an internal-only service (no public URL) |
scaling.max |
maximum active instances; the CPA always owns a zero floor |
scaling.concurrency |
requests per instance before scaling out |
resources.cpu / memory |
per-instance resources |
security.platformAuth |
"disabled" when the service handles its own authentication |
Infra protocol v2 does not expose scaling.min. All managed services scale to
zero and use request-based CPU; those settings are CPA-owned platform invariants
rather than manifest options. A workload that must continue after an HTTP
response must use a job or worker execution contract instead of changing the
service billing posture.
Ship the declaration with each release
When an environment follows a channel,
each release set can carry the workload's deployment declaration: its
infra/runtime.json settings and its resolved requirements (databases,
events, storage, secrets, scheduled jobs) as one document. The platform then
sets up the service, its scheduled jobs and its domains from the release set it
deploys. A change to infra/runtime.json or to a schedule ships with the next
channel move, like a code change.
Turn it on per workload, in the workload's own putnami.json:
{
"options": {
"@putnami/go": { "deployment": true }
}
}Use @putnami/typescript instead for a TypeScript workload. The workload must
also be continuously deployed (options["@putnami/cloud"].deploy.enabled: true) and publish a Config member (a @putnami/cloud:publish-config
namespace). Your Go or TypeScript extension must be a version that has the
deployment package step. The setting counts only in the workload's own
putnami.json, not in putnami.workspace.json.
| When | What happens |
|---|---|
| The first release after you turn it on | The workload rolls once, even when its code did not change. |
| Only the declaration changes in a release | The workload rolls once. |
| A channel moves back to a set from before you turned it on | The workload rolls once and uses the declaration its last release without a member recorded. |
| You turn it off | The next release carries no declaration. The workload rolls once and uses the declaration its last release without a member recorded. |
The workload publishes an image channel |
No declaration is published. |
To undo a bad declaration, turn the setting off or fix the declaration and
release again. Do not downgrade the framework below the version that added the
deployment package step once a release set carries a declaration: older
versions refuse those release sets.
Public vs authenticated
Ingress controls reachability. Set ingress.public: false for a service with no
public URL. A public service that owns its own authentication declares
security.platformAuth: "disabled"; use the current runtime schema when the
platform, rather than the service, is to enforce authentication.
Generated HTTP route intent
Frameworks may emit a canonical route inventory at
.gen/schema/http-routes.json. Deploy carries that artifact byte-for-byte,
validates the putnami.http-routes.v1 protocol and digest before provisioning,
and records the exact inventory on the deployment. A route-only change or
removal is release content, so it prevents an otherwise-unchanged deploy from
being skipped.
Path enforcement is default-off. A project opts its release into the generated
route policy through putnami.json:
{
"options": {
"@putnami/cloud": {
"deploy": { "enforceHttpRoutes": true }
}
}
}The managed Putnami gateway currently suspends this opt-in at the operator
master switch: generated artifacts are still carried and validated,
but the effective gateway policy remains host-to-service routing without a
path/method allowlist. Do not rely on enforceHttpRoutes for 404 filtering
until a scalable replacement is announced.
An opted-in deploy fails before provisioning when the generated artifact is
missing, malformed, noncanonical, or uses an unsupported protocol version.
Without the setting, a project that emits no artifact keeps the existing
hostname-level routing behavior. When the managed gateway, its shared reject
backend, and the operator master switch are configured, enforcement projects
only publicEdge: true exact,
slash-terminated prefix, and supported segment-template paths to the workload;
all unmatched paths go to the reject backend without invoking the workload's
Cloud Run service. Removing a declared path removes its gateway rule. Disable
the setting and merge to roll the host matcher back to legacy host-default
routing. Each public route method is enforced with an exact gateway :method
match; undeclared methods and private methods on the same path go to the reject
backend without reaching the workload.
Pages
| Page | Status |
|---|---|
| Your first deploy | Ready |
| Environments follow channels | Ready |
| Environments (prod, preview, per-env config) | Planned |
| Preview environments (per-branch URLs) | Planned |
| Rollback | Planned |
| Ingress & custom domains | Planned |
| Public vs authenticated services | Planned |