Quillet
Menu
Menu

Environments

7 min read

An owner creates an environment empty or as a clone of another, gives it a website preview URL and keys of its own, and deletes it once it is no longer needed.

Why staging is its own environment

A project's content managers write in one place, and a site reads one place. When you want a second place, such as a staging copy that a preview deployment reads while prod keeps serving readers, you add an environment. Each environment holds its own documents, versions and publish states. Nothing written in one shows up in another until somebody promotes it.

An environment belongs to the project's shape, not to its content. That makes creating, changing and deleting one an owner's work, done signed in or with a personal token. An API key never has the owner role, and the CMS refuses it these routes by design. Environments and promotion explains why Quillet copies and promotes instead of branching.

What an environment holds and how it starts

The default environment

Every project starts with one default environment, prod unless its creator named others, and a project can be created with up to ten. Projects made before prod became the default keep main. Both work the same way, because the default is the environment marked Default, not a particular name. It is the one the dashboard opens and the one search rebuilds from the dashboard. It cannot be deleted.

Keys and names

An environment has a Key and a Name. The key is what URLs address, such as /d/v1/<project>/staging/…, so it cannot be changed later. It is 2 to 64 characters of lowercase letters, digits and hyphens, starting with a letter or digit, and assets is reserved. The name is what the header and every screen show. You can change it whenever you like.

Created empty, or as a clone

An empty environment has no documents. A clone starts as a copy of another environment in the same project:

  • Every published document is copied as version 1, already published.
  • With Include unpublished drafts, each document's current draft comes too. It arrives as a second version where it differs from the published one, and as the only version of a document that was never published.
  • History is not copied, so every document starts again at version 1.
  • The website preview URL is not copied, and a translation's review mark is not carried over, because a review in one environment says nothing about another.
  • Files are never copied. They belong to the project, so every environment already has them.

The new environment appears only once the copy is complete, and a clone that fails leaves nothing behind. The new environment's promotion trail records every clone, and each copied version says "Cloned from prod" in History.

The website preview URL

Each environment has its own Website preview URL, the address on your site that turns a preview token into a page. A staging site and a production site are two deployments, so each environment points at its own. Until you set it, Preview › On website is unavailable to content managers.

The address must be https:// unless the instance sets WEBHOOK_ALLOW_HTTP, and it may not carry a user name or password. It must also resolve from the CMS, and to a public address unless the instance sets WEBHOOK_ALLOW_PRIVATE_NETWORKS; a host the CMS cannot look up is refused with This host could not be resolved. Quillet never calls the address itself. The content manager's browser does.

Keys per environment

A delivery key is always bound to one environment and reads nothing else, so a site that shows staging needs a delivery key minted for staging. A CLI key is either project-wide or bound to one environment. A bound key is refused on every other environment with 403 This key is bound to another environment. You choose the environment in the Environment field when you mint the key on Settings › Keys.

Deleting

Deleting an environment removes, in one step, the environment itself, every document and version in it, its search entries and the promotion records written into it. Every key bound to it is revoked, not removed: the key stays on the Keys page as revoked, with no environment. The CMS retires cached delivery answers for the environment at once.

How to

Dashboard

Open Settings › Environments. Everyone sees the list, but only an owner sees the buttons.

To create an empty environment:

  1. Press New environment.
  2. Enter a Key, such as staging, and a Name, such as Staging, and confirm.

To clone an environment:

  1. On the row of the environment to copy, press Clone.
  2. Enter the new Key and Name. From names the source.
  3. Tick Include unpublished drafts if the copy should carry work in progress.
  4. Press Clone environment. While the copy runs, the dialog says "Cloning prod… this can take a minute for a large environment."

To set the website preview URL:

  1. On the environment's row, press Edit.
  2. Enter the Website preview URL, such as https://staging.example.com/api/preview, and press Save environment.

To delete an environment:

  1. On its row, press Delete. The default environment has no Delete.
  2. The dialog counts what goes, such as "Its 42 documents and 2 keys go with it. This cannot be undone." Press Delete environment.

Compare & promote, beside New environment, opens the Promote screen with the environment you are on as the target.

API

Each call here needs an owner's personal token, sent as <tokenId>:<secret>.

Create an empty environment:

curl -s -u '<tokenId>:<secret>' -X POST \
  'http://localhost:3000/api/v1/projects/<project>/environments' \
  -H 'Content-Type: application/json' \
  -d '{"key":"<env>","name":"<Name>"}'

Or clone one instead, drafts included. The CMS answers 201 with the new environment once the copy is complete:

curl -s -u '<tokenId>:<secret>' -X POST \
  'http://localhost:3000/api/v1/projects/<project>/environments' \
  -H 'Content-Type: application/json' \
  -d '{"key":"<env>","name":"<Name>","cloneFrom":"<source>","includeDrafts":true}'

Set its website preview URL. Sending "previewUrl":null clears it:

curl -s -u '<tokenId>:<secret>' -X PATCH \
  'http://localhost:3000/api/v1/projects/<project>/environments/<env>' \
  -H 'Content-Type: application/json' \
  -d '{"previewUrl":"https://<staging.example.com>/api/preview"}'

Mint a delivery key for it. The secret is in this answer and nowhere else, so copy it now:

curl -s -u '<tokenId>:<secret>' -X POST \
  'http://localhost:3000/api/v1/projects/<project>/keys' \
  -H 'Content-Type: application/json' \
  -d '{"name":"<site>","kind":"delivery","scopes":["content:read"],"env":"<env>"}'

Before you delete an environment, read what it holds. Any member may read this:

curl -s -u '<tokenId>:<secret>' \
  'http://localhost:3000/api/v1/projects/<project>/environments/<env>'

Then delete it. The answer counts what went, under deleted:

curl -s -u '<tokenId>:<secret>' -X DELETE \
  'http://localhost:3000/api/v1/projects/<project>/environments/<env>'

CLI

Sign in with a personal token first (quillet login), because creating and deleting are owner routes and the CMS refuses them to a CLI key. Listing and reading work with any key.

npx quillet envs list --project <project>
npx quillet envs create <env> --name <Name> --project <project>
npx quillet envs show <env> --project <project>

At a terminal, envs delete asks before it deletes, and --yes answers for you. A script that runs it without --yes stops:

npx quillet envs delete <env> --project <project> --yes

It prints what went, such as Deleted environment qa: 0 documents, 0 versions, 0 keys.

Limits

  • The CLI cannot clone, because envs create always makes an empty environment. Clone in the dashboard or over the API.
  • A clone copies at most 20 000 documents. The CMS refuses a larger source with a sentence such as prod holds 23 410 documents; a clone copies at most 20 000. Create the environment empty and promote it in scopes.
  • Clones share the promotion rate limit, 100 a minute per person by default. Creating an empty environment is not limited.
  • An environment's key cannot be renamed, the choice of default environment cannot be changed, and the default cannot be deleted.
  • A clone does not copy History, so ?at= on the new environment cannot answer for any time before the environment was made.
  • Deleting cannot be undone, and a revoked key stays revoked. A backup taken beforehand is the only way back; see Backups.

Last updated