cube-js · igorlukanin · Jan 20, 2025 · Jan 17, 2025
diff --git a/docs/pages/product/deployment/cloud/deployments.mdx b/docs/pages/product/deployment/cloud/deployments.mdx
@@ -75,22 +75,20 @@ user-specific state of the deployment:
 
 ## Cube version
 
-Each deployment in Cube Cloud runs a specific version of Cube, depending on the
-branch of the source code and the selected [update channel](#update-channels).
+Each [environment][ref-environments] within a Cube Cloud deployment runs a specific
+version of Cube that depends on the environment type and the selected [update
+channel](#update-channels).
 
 ### Current version
 
-You can check the current version of Cube that your deployment runs by
+You can check the current version of Cube that your deployment (environment) runs by
 navigating to <Btn>Overview → Resources & Logs → Cube API</Btn>:
 
 <Screenshot
   src="https://ucarecdn.com/83a5010a-3c02-4ce1-8e4f-fdbb2efc6a90/"
   highlight="inset(42.5% 42.5% 32.5% 4% round 10px)"
 />
 
-Non-main branches and [development mode][ref-dev-mode] branches always run
-the most up-to-date version of Cube.
-
 ### Update channels
 
 Cube Cloud provides two update channels:
@@ -110,25 +108,12 @@ General → Cube version</Btn>:
 
 ## Resource consumption
 
-Each deployment allocates and consumes the following resources:
-
-* For the main branch of the source code, a set of resources in line with
-  the [deployment type][ref-deployment-types].
-* For any other branch of the source code, a [development
-  instance][ref-dev-instance].
-* For any user-specific [development mode][ref-dev-mode] branch, a
-  [development instance][ref-dev-instance].
-* If pre-aggregations are used, a minimum of two Cube Store workers.
-
-Cube Cloud only consumes resources when they are needed to run workloads:
-
-* For the main branch, resources are always consumed unless a deployment is
-  [auto-suspended][ref-auto-sus].
-* For any other branch or any user-specific development mode branch,
-  a development instance is allocated while there's some activity in the
-  branch, e.g., API endpoints are serving requests, a user is active in
-  Cube Cloud, etc. After a period of inactivity, the development instance
-  is deallocated.
+Cube Cloud deployments only consume resources when they are needed to run workloads:
+
+* For the [production environment][ref-environments-prod], resources are always consumed
+unless a deployment is [suspended][ref-auto-sus].
+* For any other [environment][ref-environments], a development instance is allocated
+while it's active. After a period of inactivity, the development instance is deallocated.
 * For pre-aggregations, Cube Store workers are allocated while there's some
   activity related to pre-aggregations, e.g., API endpoints are serving
   requests to pre-aggregations, pre-aggregations are being built, etc.
@@ -140,7 +125,6 @@ resource consumption in different scenarios.
 
 [cube-cloud-signup]: https://cubecloud.dev/auth/signup
 [ref-deployment-types]: /product/deployment/cloud/deployment-types
-[ref-dev-instance]: /product/deployment/cloud/deployment-types#development-instance
 [ref-dev-mode]: /product/workspace/dev-mode
 [ref-auto-sus]: /product/deployment/cloud/auto-suspension
 [ref-total-cost]: /product/deployment/cloud/pricing#total-cost-examples
@@ -150,4 +134,6 @@ resource consumption in different scenarios.
 [ref-dynamic-data-models]: /product/data-modeling/dynamic
 [ref-config-options]: /product/configuration#configuration-options
 [ref-data-model]: /product/workspace/data-model
-[ref-playground]: /product/workspace/playground
+[ref-playground]: /product/workspace/playground
+[ref-environments]: /product/workspace/environments
+[ref-environments-prod]: /product/workspace/environments#production-environment
diff --git a/docs/pages/product/workspace.mdx b/docs/pages/product/workspace.mdx
@@ -19,7 +19,6 @@ In Cube Cloud, you can:
   the data model of your semantic layer.
 - Use [Visual Modeler][ref-visual-modeler] to build and edit your data model
   using a canvas-based UI.
-- Access the data model through different [Environments][ref-environments].
 - Use [Playground][ref-playground] to run queries and test the data model.
 - Use [Chart Prototyping][ref-vizard] to generate code of a front-end
   application that works with Cube.
@@ -35,6 +34,7 @@ to BIs, spreadsheets, and other visualization tools.
   of your deployment as a whole.
 - Use [Monitoring Integrations][ref-monitoring-integrations] to export logs and
 metrics to external monitoring tools.
+- Access the data model through different [environments][ref-environments].
 - Use the [access control page][ref-access-control] to manage users of your
   Cube Cloud account and [single sign-on][ref-sso].
 - Use [Audit Log][ref-audit-log] to review security-related events in your

diff --git a/docs/pages/product/workspace/dev-mode.mdx b/docs/pages/product/workspace/dev-mode.mdx
@@ -6,9 +6,7 @@ redirect_from:
 # Development mode
 
 Development mode allows to test and debug the data model in an isolated
-environment before releasing any changes to production. When the development
-mode is enabled, you'll have access to your personal API endpoints that will track the branch you're on and will be updated automatically when you make changes to the data model.
-Read more about environments on the [Environments][ref-environments] page.
+[development environment][ref-environments-dev] before releasing any changes to production.
 
 <SuccessBox>
 
@@ -17,6 +15,10 @@ Development mode is available in Cube Cloud on
 
 </SuccessBox>
 
+When you enter the development mode, you'll have access to your personal API endpoints
+that will track the branch you're on and will be updated automatically when you make
+changes to the data model.
+
 ## Development flow
 
 ### Save changes
@@ -87,7 +89,7 @@ They will be shown on the Overview page:
   />
 </div>
 
-Read more about the available endpoints on the [Environments][ref-environments] page.
+Read more about the available endpoints on the [Environments][ref-environments-endpoints] page.
 
 ## Limitations
 
@@ -106,10 +108,6 @@ Scheduled refresh is also disabled in the Development API. If you need to test
 scheduled refreshes, we recommend creating a separate deployment using a
 different Git branch of the same repository.
 
-### Cube version guarantees
-
-The version of Cube used in the Development API **is not** guaranteed to be the
-same each time. If this affects your development process, we recommend reaching
-out to our support team.
 
-[ref-environments]: /product/workspace/environments
+[ref-environments-dev]: /product/workspace/environments#development-environments
+[ref-environments-endpoints]: /product/workspace/environments#api-endpoints
diff --git a/docs/pages/product/workspace/environments.mdx b/docs/pages/product/workspace/environments.mdx
@@ -1,49 +1,118 @@
 # Environments
 
-An environment provides access to your data model. Cube Cloud provides the following environments:
-- production (default)
-- staging - providing access to the data model on a specific branch.
-  Each branch in the repository corresponds to a separate staging environment.
-  Changes must be committed to a branch to be viewable in this environment.
-- development - providing access to the data model that you are currently working on.
-  The development environment is automatically created when you enter [development mode][ref-dev-mode].
-  One development environment is allocated per user.
-  It tracks the branch you're currently on and is updated automatically when you save changes to the data model.
-  You cannot query the development enviornment unless your user is in dev mode on the branch you are trying to access.
-
-## Staging Environments
-Staging environments are created for each branch in your repository. By default, these environments are only accessible when the branch is being viewed on the Data Model screen by at least one user. When no users are viewing the branch, the environment becomes inactive and inaccessible.
-
-To maintain continuous access to a staging environment regardless of user activity, you can use the "Always Active" toggle in Settings > Staging Environments. Here's how it works:
-
-- Toggle OFF (default): The environment is only accessible when users are viewing the branch. When no users are viewing the branch, queries to this environment will fail.
-- Toggle ON: The environment remains active and accessible 24/7, regardless of user activity.
-
-### Cost Implications
-Please note that staging environments consume resources only when they are being used:
-- Environments automatically suspend after 10 minutes of inactivity, regardless of the "Always Active" toggle setting
-- You are only charged for the time when environments are being used
-
-Therefore, the "Always Active" toggle only affects accessibility to inactive branches and does not impact your costs directly.
-
-<Screenshot
-  src="https://ucarecdn.com/b0e81a61-5887-424b-af89-d5e9cebb24f2/"
-  alt="Staging Environments settings"
-/>
-
-## API Endpoints
-Each environment provides its own set of API and SQL API endpoints.
-You can reference them on the [Data Model][ref-data-model]'s Overview page and <Btn>BI Integrations</Btn> SQL API Connection tab.
-To query a development environment's API endpoints, your user must be in dev mode and on the branch that has the saved changes.
-
-<Screenshot
-  src="https://ucarecdn.com/e1cddf72-3044-4d72-a0b9-023bf3285786/"
-  alt="Data Model's Overview page"
-/>
-<Screenshot
-  src="https://ucarecdn.com/64e244dc-3632-4403-bea5-38b9632094cc/"
-  alt="BI Integrations SQL API Connection tab"
-/>
+Every Cube Cloud deployment provides a number of environments:
+- A single [production environment](#production-environment).
+- Multiple [staging environments](#staging-environments).
+- Per-user [development environments](#development-environments).
+
+<SuccessBox>
+
+Environments are available in Cube Cloud on
+[all product tiers](https://cube.dev/pricing).
+
+</SuccessBox>
+
+## Production environment
+
+This is the main environment. It runs the data model from the _main branch_.
+
+### Availability
+
+The production environment is _always available_ unless [suspended][ref-suspend].
+
+### Resources and costs
+
+Depending on the [deployment type][ref-deployment-types], the production environment
+either runs on a development instance or on a production cluster with [multiple API
+instances][ref-api-instance-scalability], incurring [relevant
+costs][ref-pricing-deployment-tiers].
+
+### Cube version
+
+Production environments run a [Cube version][ref-version] from the selected
+[update channel][ref-version-channel].
+
+## Staging environments
+
+Staging environments are activated automatically for specific source code branches
+when a branch is switched to in the Cube Cloud UI. Any [development mode][ref-dev-mode]
+changes must be committed to a branch to be available in this environment.
+
+### Availability
+
+By default, they are only active and accessible while viewed by at least one user.
+When no users are viewing the branch, the environment becomes inactive and inaccessible.
+
+If you'd like to update this setting for a specific branch (e.g., for testing purposes),
+go to <Btn>Settings → Staging Environments</Btn> and check the toggle next to it:
+
+- **Toggle off** (default). A staging environment is only active when viewed by users.
+When no users are viewing the branch, queries to this environment will fail.
+- **Toggle on**. A staging environment remains _always active_ and accessible,
+regardless of user activity.
+
+<Screenshot src="https://ucarecdn.com/e0dcce34-a53a-4087-b021-25dbaf730a92/"/>
+
+### Resources and costs
+
+Staging environments run on development instances, incurring [relevant
+costs][ref-pricing-deployment-tiers]. However, they automatically suspend after 10 minutes
+of inactivity, regardless of the [availability](#availability) setting, so you are only
+charged for the time when staging environments are being used.
+
+### Cube version
+
+Staging environments always run the _most up-to-date_ Cube version.
+
+## Development environments
+
+A development environment is activated automatically when a user enters the [development
+mode][ref-dev-mode] on a specific branch of the source code. It updates automatically
+when a user saves changes to the data model.
+
+Only one development environment is allocated per user.
+
+### Availability
+
+A development environment is only active and accessible while viewed by a user in the
+development mode. Otherwise, queries to this environment will fail.
+
+### Resources and costs
+
+Development environments run on development instances, incurring [relevant
+costs][ref-pricing-deployment-tiers]. However, they automatically suspend after 10 minutes
+of inactivity, so you are only charged for the time when development environments are
+being used.
+
+### Cube version
+
+Development environments always run the _most up-to-date_ Cube version.
+
+{/*
+
+TODO:
+Consumption? Resources? Move from  http://localhost:3000/product/deployment/cloud/deployments#resource-consumption
+
+*/}
+
+## API endpoints
+
+Each environment provides its own set of API endpoints.
+
+You can access them on the [<Btn>Overview</Btn> page][ref-overview] of your deployment
+or by navigating to the <Btn>Integrations</Btn> page and [clicking <Btn>API
+credentials</Btn>][ref-credentials].
+
+<Screenshot src="https://ucarecdn.com/36cdf2c0-311f-4023-b7ca-e156c6ac288b/" />
+
 
 [ref-dev-mode]: /product/workspace/dev-mode
 [ref-data-model]: /product/workspace/data-model
+[ref-deployment-types]: /product/deployment/cloud/deployment-types
+[ref-api-instance-scalability]: /product/deployment/cloud/scalability#auto-scaling-of-api-instances
+[ref-pricing-deployment-tiers]: /product/deployment/cloud/pricing#deployment-tiers
+[ref-suspend]: /product/deployment/cloud/auto-suspension
+[ref-overview]: /product/workspace/integrations#review-integrations
+[ref-credentials]: /product/workspace/integrations#view-api-credentials
+[ref-version]: /product/deployment/cloud/deployments#cube-version
+[ref-version-channel]: /product/deployment/cloud/deployments#update-channels