Deploy an image to a Rivet cluster
A deploy is a local build, one upload, and two Code Mode operations run through the execute tool. It needs Docker and a shell. It does not need the Rivet CLI or any other login.
Before starting
- Confirm the session can deploy. If
searchdoes not listrivet.deploy.prepare, the session is read-only or is pinned to a project or namespace, and the deploy cannot run from here. Say so instead of retrying. - Pick the cluster. Run
return (await rivet.cloud.v2.clusters.list()).items;inexecuteand use theclusterfield of the one to deploy to, which is its name. On a connection pinned to a cluster,rivet.context()reports it, andclusteris left out of every call below. - Check the image. When the app has no Dockerfile for a runner yet, or the first deploy fails to start, follow
references/runner-image.md.
Steps
Build and measure the image in the shell. The platform must be
linux/amd64.docker build --platform linux/amd64 -t app . docker image save app -o image.tar wc -c < image.tar # content_length openssl md5 -binary image.tar | base64 # content_md5The tarball must be 5 GiB or smaller. Measure the exact file that will be uploaded, because the build fails verification when either value differs.
Register the build.
return await rivet.deploy.prepare({ cluster: "my-cluster", image: "app:latest", content_length: 48213504, content_md5: "1B2M2Y8AsgTpgAmY7PhCfg==", });content_lengthis a number, not a string. Passfilewhen the tarball is not namedimage.tar. Keep the returnedbuild_id.Run the returned
uploadcommand in the shell, unchanged. It is a curl command against a presigned URL that is good for that one tarball untilexpires_at, so it carries no Rivet credentials.Roll out, repeating until
doneistrue.return await rivet.deploy.rollout({ cluster: "my-cluster", build_id: "<build_id>" });Each call advances one step and returns immediately, so call it again while
doneisfalse. A deploy takes 5 to 10 minutes, and the previous build keeps serving until it finishes. Seereferences/rollout.mdfor each step, the errors, and how to roll back.Report the
build_idand theendpointsfrom the final result to the user. Thebuild_idis what a later rollback needs.
Rules
- Never rebuild or re-upload to retry a rollout. Call
rivet.deploy.rolloutagain with the samebuild_id. - Use
rivet.deploy.*for the whole deploy. Do not driverivet.cloud.v2.builds.*orrivet.cloud.v2.runnerPools.upsertby hand, because an upsert replaces the pool's settings wholesale and would drop its allowlist. - Do not guess a
cluster,region, orpoolname. List them first. - When a step fails with a
platformfault, or the deploy only goes through after a workaround, send one report with the feedback tool after telling the user the result, if the server offers that tool.