Deployments

Each site can have many deployments. A deployment is one versioned build of your storefront — created from a Git push, from the CLI, or from an uploaded archive — and exactly one of them is active at a time. The active deployment is what your domains serve.

That separation is the whole point: builds accumulate, and switching which one is live is a pointer change rather than a rebuild. It is what makes rollbacks instant.

Deployment status

"Active" is not a status. It is a property of the site — a pointer to whichever ready deployment is currently being served. That is why any ready deployment can be made active, including one from weeks ago, and why activating one doesn't change its status.

Build logs

Every build writes logs as it goes, and they are kept on the deployment. In Cockpit, open the site under Experience Studio → Sites; its Overview tab lists the deployments, and clicking a row opens that build's logs. The Deployment tab shows the source commit and the build configuration that deployment actually ran with — useful when the site's settings have changed since.

The same logs are available over the API — GET /v1/sites/{siteId}/deployments/{deploymentId} returns the deployment including its build output, so a CI job can print the failure that broke it.

Build logs are distinct from the request logs your running storefront produces. Those are covered in Logs.

Download or cancel a build over the API

GET /v1/sites/<SITE_ID>/deployments/<DEPLOYMENT_ID>/download returns the deployment's content as a download. Pass type as source or output. The response has a Content-Disposition: attachment header, so a browser saves the file.

PATCH /v1/sites/<SITE_ID>/deployments/<DEPLOYMENT_ID>/status cancels a build. A build in progress is stopped. A build that has not started yet is marked canceled without running. A build that is already ready or failed cannot be canceled. The response includes the final build status.

Create a deployment

Three ways, in rough order of how often you'll use them:

• From Git — connect a repository once and every push to the production branch builds and activates. This is the default you want for day-to-day work. See Deploy from Git.
• From the CLI — revenexx deploy theme . for a theme, or revenexx deploy site . for any build directory. Useful for a first push, for CI, and when you don't want to connect a repository yet. See Deploy from CLI.
• From an uploaded archive — a .tar.gz of your build output, for one-shot deploys and for build pipelines that live somewhere else entirely. See Deploy manually.

Over the API, POST /v1/sites/<SITE_ID>/deployments uploads a new version of the site's code, and GET /v1/sites/<SITE_ID>/deployments lists a site's deployments. The required activate flag decides what happens when the build finishes: true serves it at once, false leaves it for you to activate later.

Three more operations create a deployment without an upload:

Each of these returns 202 with the deployment object while the build runs. On the template and vcs routes, send activate: true to serve the deployment as soon as its build finishes.

In Cockpit, all three ways above start from Experience Studio → Sites → Create site. A site already connected to a repository offers a redeploy action instead; a site without one offers a fresh upload.

Redeploy after a configuration change

Some settings only take effect on the next build. If you change the Git repository, the build settings (install command, build command, output directory, framework, adapter), or the environment variables, the currently active deployment keeps running with the old configuration until you create a new deployment.

Redeploying is also the way to retry a failed build once you've fixed the cause — a missing lockfile, a build script that needs more heap.

Over the API, POST /v1/sites/<SITE_ID>/deployments/duplicate rebuilds an existing deployment's code with the site's current build commands and output directory. It does not pick up a new repository or branch: POST /v1/sites/<SITE_ID>/deployments/vcs builds from a branch, commit or tag of the connected repository. The CLI example below is the CLI form of the vcs route.

From the CLI:

revenexx sites create-vcs-deployment --site-id <SITE_ID> --type branch --reference main --activate true

Deleting a deployment

DELETE /v1/sites/{siteId}/deployments/{deploymentId} deletes one deployment by its ID, together with its uploaded code and build files, and answers 204 with no body. There is no undo. An unknown site, an unknown deployment, or a deployment that belongs to another site is a 404. Deleting the active deployment is not refused: the site is left with no live deployment. Activate another one first, see Instant rollbacks.

Compute

A deployment gets a build specification and a runtime specification, set independently. There are nine of them, from half a vCPU with 512 MB up to eight vCPUs with 8 GB, and all nine are available to every caller — there is no tier that unlocks a bigger machine.

The table, how to set one, and what to do about an out-of-memory build are in Compute specifications.

Debugging

• Build succeeds locally, fails on the platform. The build runs a plain install against the public registry, not a workspace install — every dependency must resolve from npm, and your lockfile should be committed.
• A configuration change had no effect. Create a new deployment; the active one still carries the old configuration.
• The build ran out of memory. Raise the server specification, or set NODE_OPTIONS=--max-old-space-size=3072 for your build command. See Compute specifications.

Related

• Previews — verifying a ready deployment before it goes live
• Instant rollbacks — activating an earlier deployment
• Build configuration — the settings a redeploy picks up
• Environment variables — the other thing that needs a redeploy
• Logs — request logs from the running storefront