From 41b1f5b13fcbf1093be76a4d1c0ac8e67300bc9a Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Thu, 5 Nov 2026 09:57:34 -0800 Subject: [PATCH 1/2] Cleaned up environments and added maintenance mode. --- docs/cloud/environments.md | 50 ++++++++++++++++++++++++++------------ 1 file changed, 34 insertions(+), 16 deletions(-) diff --git a/docs/cloud/environments.md b/docs/cloud/environments.md index 7f4188040..e52d5d5ae 100644 --- a/docs/cloud/environments.md +++ b/docs/cloud/environments.md @@ -1,12 +1,12 @@ # Environments -Craft Cloud projects allow you to manage multiple distinct environments or “versions” of your site, each with their own [resources](#resources) and [settings](#environment-settings). Environments are perfect for testing changes before rolling them out to a live site. +Craft Cloud projects allow you to manage multiple distinct environments or “versions” of your site, each with its own [resources](#resources) and [settings](#environment-settings). Environments are perfect for testing changes before rolling them out to a live site. -Team plans include two environments; Pro plans include three. +Team plans include two environments and Pro plans include three. ## Features -Most of your work in Cloud will be in the context of an environment. Each environment’s landing page has a summary of actions that are available to you. +Most of your work in Craft Cloud will take place within an environment. Each environment’s landing page includes a summary of actions available to you. ### Deployments @@ -18,17 +18,17 @@ Review + search logs from your live app. ### Backups -Create and download snapshots of your [database](databases.md). Backups are created nightly, and you can start a new one at-will—they’re retained for 30 days, either way. +Create and download snapshots of your [database](databases.md). Backups are created nightly, and you can start a new one at will. They’re retained for 30 days, either way. ### Variables -Configure this’s environment variables. Adding, updating, or removing a variable requires a deployment to take effect—but you can make multiple changes, then trigger a deployment to keep related or dependent changes in sync. +Configure this environment’s variables. Adding, updating, or removing a variable requires a deployment to take effect—but you can make multiple changes, then trigger a deployment to keep related or dependent changes in sync. -Cloud automatically sets a number of variables that are essential to your application. These are listed in the **System Variables** section, and they cannot be changed or overridden. +Craft Cloud automatically sets several variables essential to your application. These are listed in the **System Variables** section, and they cannot be changed or overridden. ### Commands -Run a Craft console command from your browser. History and logs for past commands are available here, as well. +Run a Craft console command from your browser. History and logs for past commands are available here as well. Every deploy also triggers a `cloud/up` command, so you’ll see those records among any commands you’ve manually run. @@ -38,15 +38,33 @@ Get credentials to this environment’s database and [asset storage](assets.md). ### Settings -Rename the environment, or change the branch it’s associated with (and when it will be [deployed](deployment.md)). +#### Name + +Where you can rename the environment. + +#### Deploy Trigger + +Change how the environment is [deployed](deployment.md)) — either “On Push” or “Manual”. + +#### Branch + +Change the branch the environment is associated with. + +#### Maintenance Mode + +Enabling this returns a 503 Service Unavailable response to all web traffic for this environment. It can take up to a minute to take effect. + +#### Danger Zone + +Where you can delete the environment. ## Resources -Every environment gets its own database. Data is not automatically cloned from one environment to another, so you will need to manually restore a backup—that backup could come from another Cloud environment, or a local development database. +Every environment gets its own database. Data is not automatically cloned from one environment to another, so you will need to manually restore a backup. That backup could come from another Craft Cloud environment, or a local development database. All environments in a project share a single asset storage bucket, but they are separated into top-level directories named after their environment’s ID (or, more accurately, its UUID). -Cloud generates a [preview domain](domains.md) for each environment—or allows you to connect a [custom domain](domains.md#adding-a-domain) or [subdomain](domains.md#subdomains) thereof. +Craft Cloud generates a [preview domain](domains.md) for each environment, or allows you to connect a [custom domain](domains.md#adding-a-domain) or [subdomain](domains.md#subdomains). ## Environment Settings @@ -58,25 +76,25 @@ In your project’s main **Settings** screen, you can select a **Production Envi ### Warming -The production environment’s function is kept “warm” by our infrastructure by periodically invoking it. +The production environment’s function is kept “warm” by our infrastructure through periodic invocations. -To conserve compute resources (and therefore energy consumption), Cloud allows non-production environments’ functions to “sleep” after about 15 minutes. This means that—following a period of no activity—there may be a 1–2 second delay prior to the first request being served. +To conserve compute resources (and therefore energy consumption), Cloud allows functions in non-production environments to “sleep” after about 15 minutes. This means that—following a period of inactivity—there may be a 1–2-second delay before the first request is served. These invocations do not fully bootstrap Craft, so they will be invisible to your application. ### Front-End URLs -Craft Console uses the production environment’s preview domain (or a custom domain connected to it, once verified) when generating public URLs to the project. You may see these at the project level—but when you’re managing a single environment, those URLs will always link to that environment. +Craft Console uses the production environment’s preview domain (or a custom domain, once verified) when generating public URLs for the project. You may see these at the project level—but when you’re managing a single environment, those URLs will always link to that environment. ### robots.txt -For any environment that is not marked as production, Cloud injects a `robots.txt` with this body, to prevent indexing: +For any environment that is not marked as production, Cloud injects a `robots.txt` with this body to prevent indexing: ``` User-agent: * Disallow: / ``` -Production environments allow the application to dictate the contents of `robots.txt`. This is typically handled by creating `templates/robots.txt.twig` and populating it with static text, or using a plugin like [SEOMatic](plugin:seomatic) that expose an editing interface in the control panel. +Production environments allow the application to dictate the contents of `robots.txt`. This is typically handled by creating `templates/robots.txt.twig` and populating it with static text, or using a plugin like [SEOMatic](plugin:seomatic) that exposes an editing interface in the control panel. ## Deleting an Environment @@ -93,4 +111,4 @@ Always capture a database backup—and download it—before destroying an enviro Domains pointed at a deleted environment will also stop resolving. -Instead of deleting an environment, we recommend creating a new one, then pointing custom domains at that—the “old” environment can stay around until you’re confident the new one is properly configured. You are not billed for inactive environments. +Instead of deleting an environment, we recommend creating a new one and pointing custom domains to it—the “old” environment can stay around until you’re confident the new one is properly configured. You are not billed for inactive environments. From fe4e3b89578262bb30aadc895b4ae5d01374b1d0 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Thu, 5 Nov 2026 10:08:40 -0800 Subject: [PATCH 2/2] Revise environment settings and delete section Updated environment settings section and removed deletion details. --- docs/cloud/environments.md | 48 +++++++++++--------------------------- 1 file changed, 14 insertions(+), 34 deletions(-) diff --git a/docs/cloud/environments.md b/docs/cloud/environments.md index e52d5d5ae..ea1fb8d2d 100644 --- a/docs/cloud/environments.md +++ b/docs/cloud/environments.md @@ -36,27 +36,28 @@ Every deploy also triggers a `cloud/up` command, so you’ll see those records a Get credentials to this environment’s database and [asset storage](assets.md). Don’t share these details with anyone! -### Settings - -#### Name - -Where you can rename the environment. +## Environment Settings -#### Deploy Trigger +When you create an environment, you’ll give it a name, select a Git branch, and choose a [deployment trigger](deployment.md#deployment-triggers). All three options can be changed any time from the environment’s **Settings** screen. -Change how the environment is [deployed](deployment.md)) — either “On Push” or “Manual”. +You can also enable Maintenance Mode for this environment, which will return a 503 Service Unavailable response to all web traffic. It can take up to a minute to take effect. -#### Branch +## Deleting an Environment -Change the branch the environment is associated with. +Environments can be deleted at any time. Keep in mind that their resources will be destroyed, and they will immediately stop serving traffic. **Everything below will be unrecoverable:** -#### Maintenance Mode +- Your **database** and everything in it will be deleted; +- Any **assets** uploaded to the environment will be deleted; +- We remove all **system and custom variables** belonging to the environment; +- The environment’s **settings**, **deployment history**, **command history**, **logs**, and **temporary credentials** are all deleted; -Enabling this returns a 503 Service Unavailable response to all web traffic for this environment. It can take up to a minute to take effect. +::: warning +Always capture a database backup—and download it—before destroying an environment. +::: -#### Danger Zone +Domains pointed at a deleted environment will also stop resolving. -Where you can delete the environment. +Instead of deleting an environment, we recommend creating a new one and pointing custom domains to it—the “old” environment can stay around until you’re confident the new one is properly configured. You are not billed for inactive environments. ## Resources @@ -66,10 +67,6 @@ All environments in a project share a single asset storage bucket, but they are Craft Cloud generates a [preview domain](domains.md) for each environment, or allows you to connect a [custom domain](domains.md#adding-a-domain) or [subdomain](domains.md#subdomains). -## Environment Settings - -When you create an environment, you’ll give it a name, select a Git branch, and choose a [deployment trigger](deployment.md#deployment-triggers). All three options can be changed any time from the environment’s **Settings** screen. - ## Production Environment In your project’s main **Settings** screen, you can select a **Production Environment**. This setting has three effects: @@ -95,20 +92,3 @@ User-agent: * Disallow: / ``` Production environments allow the application to dictate the contents of `robots.txt`. This is typically handled by creating `templates/robots.txt.twig` and populating it with static text, or using a plugin like [SEOMatic](plugin:seomatic) that exposes an editing interface in the control panel. - -## Deleting an Environment - -Environments can be deleted at any time. Keep in mind that their resources will be destroyed, and they will immediately stop serving traffic. **Everything below will be unrecoverable:** - -- Your **database** and everything in it will be deleted; -- Any **assets** uploaded to the environment will be deleted; -- We remove all **system and custom variables** belonging to the environment; -- The environment’s **settings**, **deployment history**, **command history**, **logs**, and **temporary credentials** are all deleted; - -::: warning -Always capture a database backup—and download it—before destroying an environment. -::: - -Domains pointed at a deleted environment will also stop resolving. - -Instead of deleting an environment, we recommend creating a new one and pointing custom domains to it—the “old” environment can stay around until you’re confident the new one is properly configured. You are not billed for inactive environments.