> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/project/settings/environments.md).

# Environments

Create an environment (TEST, QA …) with its own database, switch to it, promote its content to PROD, and delete it.

**Where:** Project → Settings → **Environments** · `/projects/<project>/settings?tab=Environments`

An **environment** is a separate set of integrations, users, templates and campaigns inside one project — for example a **TEST** environment that never touches production. **PROD** always exists and is the top of the ladder. Promotion copies content (schemas, templates, triggers, footers, signatures) **up** the ladder. More: [Projects and environments](/codemash/cloud/concepts/projects-and-environments.md).

## Before you start

* An account role that may create environments and manage the project (for example **Account Administrator**).
* A paid subscription: a trial account may not create environments (`CM-ERRORS-ENVIRONMENTS-011`).
* A database for the new environment — a MongoDB connection string, or Norbix Flex on the managed service.

## Steps

1. Open **Settings → Environments**. A new project has only **PROD** with the badges **top of ladder** and **current**.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-0bf9e7208abc01934f633a73d9c31bf600d5ad34%2Fenvironments-1.png?alt=media" alt="Environments tab with PROD, top of ladder, current, and the New environment button"><figcaption><p>Only PROD.</p></figcaption></figure>
2. Press **New environment**, fill in the form, press **Connect** on a database card and press **Create environment**:

   | Field             | Required | What it does                                                                                                                       | Example                                           |
   | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
   | Environment name  | yes      | Upper-case name of the environment.                                                                                                | `TEST`                                            |
   | Database          | yes      | **Mongo DB (Connection String)** or **Norbix Flex** (managed service, pick a **Cluster tier**). **Change database** picks another. | Mongo DB (Connection String)                      |
   | Integration name  | yes      | Name of the environment's database integration.                                                                                    | `Test database`                                   |
   | Connection string | yes      | Your MongoDB address.                                                                                                              | `mongodb+srv://user:password@cluster.mongodb.net` |
   | Database name     | no       | Empty = the database in the connection string.                                                                                     | `acme_store_test`                                 |

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-b65d480c6c64568cc27e881a4586a429598d4796%2Fenvironments-2.png?alt=media" alt="New environment form: TEST, Mongo DB (Connection String), Test database, connection string, acme_store_test, Create environment"><figcaption><p>The New environment form.</p></figcaption></figure>
3. The new environment becomes **current** — Cloud now shows its data. Press **Switch to this** on **PROD** to go back. The arrows on a non-PROD row move it up or down the ladder.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-ff120e188051ab57272e99bba84417c2c14704c0%2Fenvironments-3.png?alt=media" alt="Ladder with TEST (current) and PROD (top of ladder, Switch to this) and the Promote button"><figcaption><p>TEST is created and current.</p></figcaption></figure>
4. To move content up, press **Promote**, pick **Source** (`TEST`) and **Target** (`PROD`), press **Preview** to see the plan (mirrored, deleted in target, integrations seeded or kept, blockers), then **Promote TEST → PROD**.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-ba3c8581167a63781175569fa97eb2493472f979%2Fenvironments-4.png?alt=media" alt="Promote environment dialog with Source TEST, Target PROD, Preview, Cancel and Promote TEST → PROD"><figcaption><p>The Promote dialog.</p></figcaption></figure>

## Result

The ladder lists the new environment with its rank. The environment switch in the left menu offers it, and every module screen shows the data of the current environment. After a promotion the tab shows a card *Promoted TEST → PROD* with **Roll back**.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-b07a4788c243e2862d84f0acc0a64a122117d8fc%2Fenvironments-5.png?alt=media" alt="Ladder with TEST (Switch to this, delete icon) and PROD (current)"><figcaption><p>Back on PROD.</p></figcaption></figure>

Promotion never overwrites integration secrets: an integration that exists in both environments keeps its own settings in each.

## Change or remove it later

* **Roll back** — on the promotion card; the target goes back to its state before that promotion.
* **Delete** — press the trash icon (**Delete environment**) on the row, tick *I understand this deletes the environment and its integrations.* and press **Delete environment**. The integrations of the environment are removed with it; there is no undo. PROD cannot be deleted.

  <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-8d6e4c04a6e48e6763ca5661178c77464b8e4b9e%2Fenvironments-6.png?alt=media" alt="Delete environment TEST dialog with the note about cleanup and the ticked checkbox"><figcaption><p>The delete dialog.</p></figcaption></figure>

  <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-0bf9e7208abc01934f633a73d9c31bf600d5ad34%2Fenvironments-1.png?alt=media" alt="Ladder with only PROD again"><figcaption><p>TEST is gone.</p></figcaption></figure>

## Do it from code

```ts
const { item } = await norbix.hub.environments.list({ projectId: 'pr_7FUKofhEBNMnISkqust2De' });
console.log(item.environments); // ["PROD"]
```

```sh
norbix hub account projects environments get
```

The client setup is on the [Account page](/codemash/cloud/account.md#use-it-from-code). API: [Get Project Environments](/codemash/api-reference/account/projects/get-project-environments.md) · [Create Project Environment](/codemash/api-reference/account/projects/create-project-environment.md) · [Promote Environment](/codemash/api-reference/account/projects/promote-environment.md) · [Delete Project Environment](/codemash/api-reference/account/projects/delete-project-environment.md)