diff --git a/umbraco-cloud/.gitbook/assets/environments-overview-new.png b/umbraco-cloud/.gitbook/assets/environments-overview-new.png new file mode 100644 index 00000000000..5a15262baed Binary files /dev/null and b/umbraco-cloud/.gitbook/assets/environments-overview-new.png differ diff --git a/umbraco-cloud/README.md b/umbraco-cloud/README.md index 393258cc5c7..2b3e2faab9c 100644 --- a/umbraco-cloud/README.md +++ b/umbraco-cloud/README.md @@ -34,7 +34,7 @@ The easiest way to start with an Umbraco Cloud project is to take a [14-day free Since everything is already set up for you, it is recommended that you get to know your project before you start building. -To start working with and building your site, you can either work directly in the backoffice on the Cloud environment or [clone down the project to your local machine](set-up/working-locally.md). +You can either work directly in the backoffice on the Cloud environment or [clone down the project to your local machine](set-up/working-locally.md). ### Umbraco Cloud Portal Project diff --git a/umbraco-cloud/SUMMARY.md b/umbraco-cloud/SUMMARY.md index 7d13c74155d..8e4265dce6a 100644 --- a/umbraco-cloud/SUMMARY.md +++ b/umbraco-cloud/SUMMARY.md @@ -81,7 +81,6 @@ ## Deployments -* [Streamline Your Deployments](deployment/streamline-your-deployments.md) * [Deployment](deployment/README.md) * [Deploying between environments](deployment/cloud-to-cloud.md) * [Transferring Content, Media, Members, and Forms](deployment/content-transfer.md) @@ -132,6 +131,7 @@ * [Extraction error: Config transforms failing](troubleshooting/deployments/changes-not-being-applied.md) * [Extraction error: Data Type collisions](troubleshooting/deployments/colliding-datatypes.md) * [Dependency Exception](troubleshooting/deployments/dependency-exceptions.md) + * [Merge Conflicts on Flexible Environments](troubleshooting/deployments/merge-conflicts-on-flexible-environments.md) * [Troubleshooting deployments failing with no error message](troubleshooting/deployments/deployment-failed.md) * [Troubleshooting duplicate dictionary items](troubleshooting/deployments/duplicate-dictionary-items.md) * [Troubleshooting language mismatches](troubleshooting/deployments/language-mismatch.md) diff --git a/umbraco-cloud/databases/README.md b/umbraco-cloud/databases/README.md index 5ce0ce24d77..cb381965ff4 100644 --- a/umbraco-cloud/databases/README.md +++ b/umbraco-cloud/databases/README.md @@ -1,7 +1,7 @@ # Working with databases {% hint style="info" %} -The databases on your Umbraco Cloud environments are specific to their environment. This means that no matter what you have configured in the `connectionstring` in your `web.config` or `appSettings.json` file, we overwrite the connectionstring to use the SQL Azure Server we provide. +The databases on your Umbraco Cloud environments are specific to their environment. This means that the connectionstring to use the SQL Azure Server is overwritten no matter what else is configured. {% endhint %} When working with Umbraco Cloud, the way you work with databases might differ from what you're used to. One important aspect of Umbraco Cloud is that you always work isolated to avoid interfering with colleagues or a running website. This includes the database as well. diff --git a/umbraco-cloud/databases/backups.md b/umbraco-cloud/databases/backups.md index d67848e3fd6..7379290dfc9 100644 --- a/umbraco-cloud/databases/backups.md +++ b/umbraco-cloud/databases/backups.md @@ -79,9 +79,6 @@ Once you have uploaded a backup, you might want to restore it to one of your env
Choose which environment to restore the backup on

Choose which environment to restore the backup on

- - - 3. **Optional:** Create a Cloud Backup of the selected environment's database before restoring the backup. 4. Click **"Restore backup"** @@ -93,10 +90,10 @@ Make sure to check your environment and see if everything works as expected and Use the following steps: -* Connect to your SQL Server using SQL Server Management Studio (SSMS). -* Expand "Databases", right-click "Databases", then select "Import Data-tier Application...". -* Proceed through the dialog, by browsing to the saved location of your `bacpac` file, and then setting the options appropriate to your configuration -* Complete the import dialog and the database will be restored. +1. Connect to your SQL Server using SQL Server Management Studio (SSMS). +2. Expand "Databases", right-click "Databases", then select "Import Data-tier Application...". +3. Proceed through the dialog, by browsing to the saved location of your `bacpac` file, and then setting the options appropriate to your configuration +4. Complete the import dialog and the database will be restored. {% hint style="info" %} If a `bacpac` restore fails in SQL server, ensure the 'Contained Database Authentication' flag is set to true for resolution. diff --git a/umbraco-cloud/deployment/README.md b/umbraco-cloud/deployment/README.md index bf9d720c99d..4a66c4b8876 100644 --- a/umbraco-cloud/deployment/README.md +++ b/umbraco-cloud/deployment/README.md @@ -6,29 +6,32 @@ description: >- # Deployment -Umbraco Cloud uses a deployment model based on Git, Kudu, and Umbraco Deploy core technology to move changes between environments. This follows a "left to right" model. Changes start in the local or left-most environment and are deployed to the production environment. +Umbraco Cloud uses a deployment model based on Git, Kudu, and Umbraco Deploy to move changes between environments. This follows a left-to-right deployment approach. Changes start in the local or left-most environment and are deployed to the production/Live environment. This workflow is called the mainline. -![Left to right model](images/left-to-right.png) +The mainline environments are used when building and deploying the initial website. Upgrades, both manual and automatic also go through the mainline environments. -## Deployment Approach +Flexible environments can be used to work on features separate from the mainline. This is done without interfering with upgrades or other changes being worked on in the mainline. + +![Left to right model](images/left-to-right-approach.png) -Umbraco Cloud separates metadata and content during deployment. Metadata includes Document Types, Templates, Forms, Views, and config files. Content includes content items and media. +## Deployment Approach -**Key Terms:** +Umbraco Cloud separates schema and content during deployment. Schema includes Document Types, Templates, Forms, Views, and config files. Content includes content items and media. -* **Deploy:** Moves metadata between environments using a Git client or the Umbraco Cloud Portal. -* **Transfer:** Moves content and media directly via the Umbraco backoffice. +* **Deploy:** Moves schema between environments using a Git client or the Umbraco Cloud Portal. +* **Transfer:** Move content and media directly via the Umbraco backoffice. -**Deployment Types:** +### Types of Deployments -* **Metadata Deployment:** Metadata, including Document Types, Templates, Forms, Views, and config files, is stored in a Git repository. These are **deployed** between environments using a Git client or the Umbraco Cloud Portal. -* **Content and Media Transfer:** Content and Media items are **not** stored in the Git repository. Instead, they must be **transferred** directly from the Umbraco backoffice using the **Queue for Transfer** option. Once all required items are queued, the **Deployment** Dashboard in the **Content** section is used to complete the transfer. +| Schema Deployments | Content and Media Transfers | +| ----------- | ------------- | +| Schema is stored in a Git repository. These are **deployed** between environments using a Git client or the Umbraco Cloud Portal. | Content and Media items are not stored in the Git repository. They must be **transferred** directly from the Umbraco backoffice using the **Queue for Transfer** option. Once queued, use the **Deployment** Dashboard in the **Content** section to complete the transfer. | -Content editors do not need Umbraco Cloud Portal access. They can manage content through the backoffice, while developers handle metadata deployments via Git. +Content editors do not need Umbraco Cloud Portal access. They can manage content through the backoffice, while developers handle schema deployments via Git. -### Deploying Metadata +### Deploying Schema -The source and target environments must be in sync before transferring content and media. Deploy metadata first to ensure consistency. +The source and target environments must be in sync before transferring content and media. Deploy schema first to ensure consistency. * [Deploy changes from Local to Cloud](local-to-cloud.md) * [Deploy changes between Cloud environments](cloud-to-cloud.md) @@ -56,7 +59,7 @@ Some deployments can trigger an Umbraco Cloud environment to restart. The table | Action: | Application Restart? | | ----------------------------------- | -------------------- | | Config file change | Yes | -| Metadata deployment | No | +| Schema deployment | No | | File change (for example, CSS file) | No | | Content or Media transfer | No | @@ -79,4 +82,3 @@ The `name` attribute in the `umbraco-cloud.json` can be updated to clarify deplo ![clone dialog](images/change-env-name-v8.png) *** - diff --git a/umbraco-cloud/deployment/cloud-to-cloud.md b/umbraco-cloud/deployment/cloud-to-cloud.md index 5d5d41b519b..27bdd175e37 100644 --- a/umbraco-cloud/deployment/cloud-to-cloud.md +++ b/umbraco-cloud/deployment/cloud-to-cloud.md @@ -2,36 +2,55 @@ updatedLinks: true --- -# Deploying between environments +# Deploying between Environments -When your are Working in your Development environment, changes made through the Backoffice are automatically detected and committed to the site's Git repository. This includes Umbraco-specific items like Document types and templates. +When you are working in your Cloud environment, changes made through the Backoffice are automatically detected and committed to the site's Git repository. This includes Umbraco-specific items like Document Types and Templates. These changes are also referred to as metadata. -Changes made on your Cloud environments will show up in the Umbraco Cloud portal. You'll be able to see what files have been added/changed and who made the changes. +## Deploying between Mainline Environments -To deploy metadata changes from one Cloud environment to another, click the **'Deploy changes to ..'** button on the environment where the changes have been made. +Changes made in your Cloud environments will appear in the Umbraco Cloud portal. You can see what files have been added or changed and who made the changes. + +To deploy metadata changes from one Cloud environment to another, click the **Deploy changes** button on the environment where the changes were made.
-The deployment initiates, and you can see the process in the **Overview of your project.** +The deployment starts, and you can follow the progress in the **Overview** section of your project.
Deployment in progress

Deployment in progress

-Once it's done, the changes will be deployed to the next Cloud environment. If you have more Cloud environments, follow the same procedure to deploy the changes up to your Live site. +Once complete, the changes are deployed to the next Cloud environment in the deployment flow. If you have additional environments, repeat this process to deploy the changes through each environment. + +## Syncing Changes Between Mainline and Flexible Environment + +When working with a flexible environment alongside your mainline environments, it's important to keep them aligned to avoid conflicts and ensure consistent deployments. + +If any changes have been made in a mainline environment those changes must be pulled into the flexible environment before pushing updates back. The changes can be updated Document Types, content, or other schema changes. + +![Pull changes from Mainline Environment](images/pull-changes-from-mainline.png) + +If what you've been working on in the flexible environment has also been changed in the mainline, a merge conflict will occur. These conflicts need to be resolved before you can continue with the deployment. For information on how to resolve them, see the [Merge Conflicts on Flexible Environments](../troubleshooting/deployments/merge-conflicts-on-flexible-environments.md) article. + +Once you’ve completed your feature or update in the flexible environment and it’s synced with the latest mainline changes: + +* Push your changes from the flexible environment to the mainline environment. +* From there, the changes become part of the regular deployment flow. + +![Push changes to the Mainline Environment](images/push-changes-to-mainline.png) ## Important Notes -When you deploy, for example, from your Development environment to your Live environment, changes are made to the Live environment. These changes will then be merged back into the Development environment. +When you deploy, for example, from your left-most mainline environment to your Live environment, changes are made to the Live environment. These changes will then be merged back into the left-most mainline environment. -Here are the automatic steps Umbraco Cloud goes through when you hit the _"Deploy changes to .."_ button: +Here are the automatic steps Umbraco Cloud goes through when you hit the _"Deploy changes"_ button: * Before pushing your changes from the source environment, the engine running Umbraco Cloud - **Umbraco Deploy** - looks for changes in the repository on the target environment * If changes are found, Umbraco Deploy _merges_ the changes from the target environment into the repository on the source environment. * After the merge, the changes from the source environment are pushed to the repository on the target environment. * Finally, the changes pushed to the target repository are extracted to the site, and you will now see your changes reflected in the Backoffice and on the Frontend. -If you have more than one Umbraco Cloud environment, we strongly recommend that you **only make changes to metadata on the Development environment**. Making changes directly on your Staging and/or Live environments can cause merge conflicts when you deploy from your Development environment. +It is recommended that you **only make changes to metadata on the left-most mainline environment or a flexible environment**. Making changes directly on other mainline environments can cause merge conflicts when you deploy. -{% hint style="danger" %} +{% hint style="warning" %} It is important to be aware of how deletions work between environments. Some deletions are environment-specific and others are not. For more information see the [Deploying Deletions article](deploying-deletions.md). {% endhint %} diff --git a/umbraco-cloud/deployment/deploying-deletions.md b/umbraco-cloud/deployment/deploying-deletions.md index 8c58b8f2717..601174ad841 100644 --- a/umbraco-cloud/deployment/deploying-deletions.md +++ b/umbraco-cloud/deployment/deploying-deletions.md @@ -10,28 +10,36 @@ The databases are environment specific. During deployment across environments, U The workflow described above does not recognize deletions of content and schema from the database. You'll need to delete the content and/or schema on all your environments to fully complete the deletion. -The main reason we do not delete schema and content on deployments is that it could lead to an unrecoverable loss of data. Imagine you delete a Document Type in your Development environment. Then, push this deletion to your Live environment, where many content nodes depend on the deleted Document Type. When the deployments go through, all those content nodes would be instantly removed. There is no option to roll back because the Document Type they rely on no longer exists. To prevent such situations, manual deletion is necessary. You must actively decide on each environment for the process to occur. +The main reason not to delete schema and content on deployments is that it could lead to an unrecoverable loss of data. + +Here's an example of what can happen when a Document Type is deleted and deployed: + +* A Document Type is deleted in the left-most mainline environment. +* This deletion is then pushed to the Live environment, where many content nodes depend on the deleted Document Type. +* When the deployment is completed, all those content nodes would be instantly removed. + +In the scenario described above, there is no option to roll back because the Document Type they rely on no longer exists. To prevent such situations, manual deletion is necessary. You must actively decide on each environment for the process to occur. Below is the same scenario explained in more detail. ## Example scenario -Let's say you've deleted a Document Type on your Development environment. Now, you want to deploy this deletion to the Live environment, along with some other changes you've made. +The following example will build in the scenario outlined above, calling the left-most mainline environment the **Development** environment. In addition to the deletion, additional changes that have been made will also be deployed. Before you deploy the changes, the Development environment will show that the following changes are ready to be deployed:

Changes ready for deployment

-Following the **Activity log** in the browser, you'll notice the UDA file for the Document Type gets deleted. Additionally, other files with changes are copied to the new environment. +Following the **Activity log** in the browser, you'll notice that the `.uda` file for the Document Type gets deleted. Additionally, other files with changes are copied to the Live environment. -Once the deployment is completed, you will notice the following: +Once the deployment is completed, the following changes has taken place: -* The template is correctly updated -* The Document Type you deleted on Development is still present in the backoffice on the Live environment +* The template is correctly updated. +* The Document Type you deleted on the Development environment is still present in the backoffice on the Live environment. -You might wonder why the Document Type that you have deleted, is still there. The reason is, that we only delete the associated UDA file and not the actual Document Type in the database. +The reason for the Document Type to still be there is, that the associated `.uda` file is deleted. The Document Type still exists in the database. -To delete the Document Type from your entire project, you need to delete it from the backoffice of the other environments. When the Document Type has been deleted from the Backoffice of all the environments and no UDA file exists, you can consider it gone. +To delete the Document Type from your entire project, you need to delete it from the backoffice of the other environments. When the Document Type has been deleted from the backoffice of all the environments and no `.uda` file exist, it is fully removed. -You should keep in mind that if you save your Document Type during the process, a UDA file is regenerated. This can recreate your deleted Document Type when deploying changes between environments. +If you save your Document Type during the process, a new `.uda` file is generated. This can recreate your deleted Document Type when deploying changes between environments. ## Which deletions are deployed? @@ -41,30 +49,21 @@ Here's an overview of what happens when you deploy deletions to the next environ ### Deleting Schema (Document Types, Datatypes, etc.) -Deleted: - -* The associated `.UDA` file - -Not deleted: - -* The entry in the database -* The item will still be visible in the backoffice +| Deleted | Not Deleted | +| --------------------------- | ------------------------------------------------ | +| The associated `.uda` file. | The entry in the database. | +| | The item will still be visible in the backoffice.| ### Deleting a Template -Deleted: - -* The associated `.UDA` file -* The associated `.cshtml` file (the view file) - -Not deleted: - -* The entry in the database -* The template file will be empty, but still be visible in the backoffice +| Deleted | Not Deleted | +| -------------------------------------------- | ----------------------------------------------------------------------- | +| The associated `.uda` file. | The entry in the database. | +| The associated `.cshtml` file (the view file)| The template file will be empty, but still be visible in the backoffice.| ### Deleting Files (CSS files, config files, etc.) -As these are **only** files, everything will be deleted in the next environment upon deployment. +All files are deleted in the next environment upon deployment. ### Deleting Content and/or Media @@ -72,13 +71,9 @@ Deletions of content and media won't be detected during deployments. You must ma ### Deleting Backoffice Languages -Deleted: - -* The associated `.UDA` file - -Not deleted: - -* The entry in the database -* The language will still be visible in the Backoffice/Content dashboard (for multilingual content) +| Deleted | Not Deleted | +| -------------------------- | ------------------------------------------------------------------------------------------------- | +| The associated `.uda` file.| The entry in the database. | +| | The language will still be visible in the Backoffice/Content dashboard (for multilingual content).| Deleting the language in the backoffice on the target environment will ensure the environments are in sync. diff --git a/umbraco-cloud/deployment/deployment-webhook.md b/umbraco-cloud/deployment/deployment-webhook.md index 6827a72019c..997a25e9cd7 100644 --- a/umbraco-cloud/deployment/deployment-webhook.md +++ b/umbraco-cloud/deployment/deployment-webhook.md @@ -1,19 +1,16 @@ ---- ---- - # Deployment Webhook -You can now configure a deployment webhook to be triggered upon successful deployments to any of your Umbraco Cloud environments. For example, when deploying from your local environment to your Cloud Development environment. Upon successful deployment, general information about the deployment will be posted in a JSON format to the specific URL you have configured. +You can now configure a deployment webhook to be triggered upon successful deployments to any of your Umbraco Cloud environments. For example, when deploying from your local environment to one of your Cloud environments. Upon successful deployment, general information about the deployment will be posted in a JSON format to the specific URL you have configured. ## Use cases -There are many use cases for deployment webhooks such as providing a detailed audit trail. Here are some scenarios where Webhooks could be useful: +There are many use cases for deployment webhooks such as providing a detailed audit trail. Here are some scenarios where webhooks could be useful: -1. Any deployments to the Live site could be relevant for many parties in a company. Posting information about a deployment in internal communication channels like _Slack_ is made possible using this feature. -2. Monitoring of the whole deployment cycle. A successful deployment might cause an error to show on the website! Integrating the webhook with other monitoring services, you could find out which deployment caused the issue. +1. Any deployments to the Live site could be relevant for many parties in a company. Posting information about a deployment in internal communication channels like Slack is made possible using this feature. +2. Monitoring of the whole deployment cycle. A successful deployment might cause an error to show on the website. Integrating the webhook with other monitoring services, you could find out which deployment caused the issue. 3. Letting content editors know about particular deployments such as when a new Document Type was added. Will inform them that they can now use the new Document Type. -## Configuration steps +## How to set up a webhook ![Adding deployment webhook](images/Post-deployment-webhooks.gif) diff --git a/umbraco-cloud/deployment/hotfixes/README.md b/umbraco-cloud/deployment/hotfixes/README.md index b1ed3d35c61..f4f8499b14f 100644 --- a/umbraco-cloud/deployment/hotfixes/README.md +++ b/umbraco-cloud/deployment/hotfixes/README.md @@ -4,7 +4,7 @@ When managing an Umbraco Cloud project with multiple environments, you might nee ## Scenario -Imagine you have two environments: Live and Development. You are currently working on some changes in your local clone of the Development environment. These changes will not be ready for the Live environment for couple of weeks. However, you now need to apply a minor change to your Live environment – a *hotfix*. +Imagine you have two environments: Live and Development. You are currently working on some changes in your local clone of the Development environment. These changes will not be ready for the Live environment for a couple of weeks. However, you need to apply a minor change to your Live environment – a _hotfix_. ### Standard Workflow @@ -18,8 +18,8 @@ Following Umbraco Cloud's workflow, you should never make changes directly to th It is possible to apply specific changes to your Live environment without breaking Umbraco Cloud workflow. Here are two approaches: -1. [Deploy hotfix with Git branching](#deploy-hotfix-with-git-branching) -2. [Move files manually](#move-files-manually) +1. [Deploy hotfix with Git branching](./#deploy-hotfix-with-git-branching) +2. [Move files manually](./#move-files-manually) ## [Deploy hotfix with Git branching](using-git.md) diff --git a/umbraco-cloud/deployment/images/left-to-right-approach.png b/umbraco-cloud/deployment/images/left-to-right-approach.png new file mode 100644 index 00000000000..c2ba5e5199c Binary files /dev/null and b/umbraco-cloud/deployment/images/left-to-right-approach.png differ diff --git a/umbraco-cloud/deployment/images/left-to-right.png b/umbraco-cloud/deployment/images/left-to-right.png deleted file mode 100644 index ffe8d03dd6c..00000000000 Binary files a/umbraco-cloud/deployment/images/left-to-right.png and /dev/null differ diff --git a/umbraco-cloud/deployment/images/pull-changes-from-mainline.png b/umbraco-cloud/deployment/images/pull-changes-from-mainline.png new file mode 100644 index 00000000000..5b16d1b8966 Binary files /dev/null and b/umbraco-cloud/deployment/images/pull-changes-from-mainline.png differ diff --git a/umbraco-cloud/deployment/images/push-changes-to-mainline.png b/umbraco-cloud/deployment/images/push-changes-to-mainline.png new file mode 100644 index 00000000000..07b65a5e35a Binary files /dev/null and b/umbraco-cloud/deployment/images/push-changes-to-mainline.png differ diff --git a/umbraco-cloud/deployment/local-to-cloud.md b/umbraco-cloud/deployment/local-to-cloud.md index 33921108ae3..6a06ec875c7 100644 --- a/umbraco-cloud/deployment/local-to-cloud.md +++ b/umbraco-cloud/deployment/local-to-cloud.md @@ -10,28 +10,28 @@ In this article, you can learn more about deploying your code changes and metada Local changes in your Umbraco Cloud project are automatically detected and synced with your Git client for seamless collaboration. -There are two ways this can be done. You can push the changes using a Git GUI or your terminal. This guide will show how you can use both ways to deploy your local changes to Umbraco Cloud. +There are two ways this can be done. You can push the changes using a Git UI or your terminal. This guide will show how you can use both ways to deploy your local changes to Umbraco Cloud. ## Prerequisites * A clone of your Cloud project. -* A [Git GUI](https://git-scm.com/downloads/guis) or a Terminal. +* A [Git UI](https://git-scm.com/downloads/guis) or a Terminal. * Created some Document Types and Data Types with corresponding `.uda` files. * The files are located in the `/umbraco/Deploy/Revision` folder. -## Deploying using a Git GUI +## Deploying using a Git UI -Once you have created some Documents and Data types, follow the steps below to deploy your local changes using a Git GUI. The guide will use [Fork](https://git-fork.com/) as the Git GUI, however you can use your own preferred Git GUI. +Once you have created some Documents and Data types, follow the steps below to deploy your local changes using a Git UI. The guide will use [Fork](https://git-fork.com/) as the Git UI, however you can use your own preferred Git UI. -1. Go to your Git GUI. -2. Check for local changes in your GUI. +1. Go to your Git UI. +2. Check for local changes in your UI. -
Local changes in Git GUI.

Local changes in Git GUI.

+
Local changes in Git UI.

Local changes in Git UI.

3. Prepare changes, so they are ready to be committed. - 1. Write a commit subject - 2. Write a description of the commit. - 3. Commit the files. + 1. Write a commit subject + 2. Write a description of the commit. + 3. Commit the files.
@@ -39,7 +39,7 @@ Once you have created some Documents and Data types, follow the steps below to d
-4. Push the files to your cloud project in the GUI. +4. Push the files to your cloud project in the UI.
Push changes to Umbraco Cloud.

Push changes to Umbraco Cloud.

@@ -52,15 +52,15 @@ After deploying changes locally to your Cloud environment, use the Umbraco Cloud To deploy your local changes from local to Umbraco Cloud using a terminal follow the steps below: 1. Navigate to your local projects folder using the `cd YourProjectName` command in the terminal. -2. Check for pending changes in your project with `git status` -3. Add the pending changes with `git add -` -4. Commit the staged files using `git commit -m "Adding updated schema changes"` +2. Check for pending changes in your project with `git status`. +3. Add the pending changes with `git add -`. +4. Commit the staged files using `git commit -m "Adding updated schema changes"`. 5. Push the changes to Umbraco Cloud using `git push`. 1. Do a `git pull` if the push is rejected. -If you have to pull down, make sure to see if any of these commits contain changes to the schema (anything in `umbraco/Deploy/Revision/`). +If you have to pull down, make sure to see if any of these commits contain changes to the schema (anything in `umbraco/Deploy/Revision/`). -To validate your local site and ensure compatibility with the updated schema, use the [**Deploy Dashboard**](https://docs.umbraco.com/umbraco-cloud/deployments/deploy-dashboard) in the **Settings** section of the Umbraco backoffice. +To validate your local site and ensure compatibility with the updated schema, use the [**Deploy Dashboard**](https://docs.umbraco.com/umbraco-cloud/deployments/deploy-dashboard) in the **Settings** section of the Umbraco backoffice. Here, you can see the status of ongoing or completed deployment processes. The status will show whether an operation has been triggered and is in progress has been completed, or has failed. diff --git a/umbraco-cloud/deployment/restoring-content/README.md b/umbraco-cloud/deployment/restoring-content/README.md index 1c199feea20..308d6f3e3cc 100644 --- a/umbraco-cloud/deployment/restoring-content/README.md +++ b/umbraco-cloud/deployment/restoring-content/README.md @@ -1,10 +1,10 @@ # Restoring Content -When you have content on your Cloud environment and you clone down your Umbraco Cloud project to your local machine, you will need to do an extra step, to see your content locally. You will also need to use the restore option when setting up new Umbraco Cloud environments. +When you have content on your Cloud environment and clone down your project to your local machine, you need to restore the content. You will also need to use the restore option when setting up new Cloud environments. -The restore option comes in handy when you have content editors creating content on the Live or Staging environments. You will be able to restore and work with that content in your Development and local environments. +The restore option can be used to always ensure you work with the latest content when delevoping new features. -## Step-by-step +## How to Restore Content You can restore the content in the following ways: @@ -21,10 +21,12 @@ The first time you run your project locally you will have the option to restore This will restore **all** the content nodes and any media dependencies. {% endhint %} -1. When your site is done spinning up, click the green **Restore** button to restore all the content nodes and media files. -2. Wait till the process completes. This might take a while depending on the amount of content and media you have on your project. -3. When it's completed, select **Open Umbraco** to go to the Backoffice. -4. You will now see all your content and media in the Umbraco Backoffice. +1. Run the website locally. +2. Click the green **Restore** button to restore all the content nodes and media files. +3. Wait till the process completes. This might take a while depending on the amount of content and media you have on your project. +4. Select **Open Umbraco** to go to the Backoffice. + +All your content and media is now available in the Umbraco Backoffice. ![Restore from start-up](images/Normal-Restore.gif) @@ -32,21 +34,15 @@ This will restore **all** the content nodes and any media dependencies. Use this option when setting up new Cloud environments. The Workspace restore option restores all the entities (content, media, forms, datasources, and prevalue sources from Umbraco Forms) of a workspace via the Backoffice. -1. Log in to the Umbraco Backoffice in the environment you want to restore the content and media. +1. Log in to the Umbraco Backoffice on the environment you want to restore the content and media. 2. Click **...** and select **Do something else** or Right-click the **Content** Tree in the Content section. 3. Choose **Workspace Restore**. 4. Select the environment from the **Restore this workspace from** dropdown. -5. To ensure the restore succeeds, make sure that your environments have the [same metadata and structure files](../cloud-to-cloud.md). -6. Click **Restore from \** and wait till the process completes. This might take a while depending on the amount of content and media you have on your project. -7. Once the content restore is completed, you will get a notification with a timestamp. Click **Okay** to complete the process. +5. Make sure that your environments have the [same schema](../cloud-to-cloud.md). +6. Click **Restore from ** and wait till the process completes. This might take a while depending on the amount of content and media you have on your project. +7. Click **Okay** to complete the process once the restore is done. 8. Right-click the **Content** tree and choose **Reload** to see your content in the tree. -{% hint style="info" %} -If any of your content nodes depends on media items, these will also be restored in the process. - -To see the media, go to the **Media** section and **reload** the tree. -{% endhint %} - ![Workspace Restore](images/Workspace\_Restore.gif) {% embed url="https://www.youtube.com/embed/0jIhKZOSeLc?rel=0" %} @@ -55,15 +51,15 @@ Workspace restore ### Tree Restore -The Tree restore option restores all the entities available for the selected tree in that section. It's available in the **Content**, **Media**, **Members**, **Forms** (root node of Forms, Datasources, and Prevalue sources), or **Translation** (Dictionary menu if configured) sections. Using Tree Restore, you can, for example, restore all your content only. This will restore any media that’s referenced in that content, but it won’t attempt to restore the full media library. +The Tree restore option restores all the entities available for the selected tree in that section. It's available in the **Content**, **Media**, **Members**, **Forms** (root node of Forms, Datasources, and Prevalue sources), or **Translation** (Dictionary menu if configured) sections. Using Tree Restore, you can choose to restore only content. This will restore any media that’s referenced in that content, but it won’t attempt to restore the full media library. 1. Log in to the Umbraco Backoffice in the environment you want to restore the tree. 2. Click **...** and select **Do something else** or Right-click the **Content** Tree in the Content section. 3. Choose **Tree Restore**. 4. Select the environment from the **Restore this tree from** dropdown. -5. To ensure the restore succeeds, make sure that your environments have the [same metadata and structure files](../cloud-to-cloud.md). -6. Click **Restore from \** and wait till the process completes. This might take a while depending on the amount of content and media you have on your project. -7. Once the content restore is completed, you will get a notification with a timestamp. Click **Okay** to complete the process. +5. Make sure that your environments have the [same schema](../cloud-to-cloud.md). +6. Click **Restore from ** and wait till the process completes. This might take a while depending on the amount of content and media you have on your project. +7. Click **Okay** to complete the process when the restore is done. 8. Right-click the **Content** tree and choose **Reload** to see your content in the tree. ![Tree Restore](images/Tree-Restore.gif) @@ -74,4 +70,4 @@ Video example. ### [Partial Restore](partial-restore.md) -Using the Partial Restore option, you can restore only a single node from a tree (optionally with descendants) that you need to work with. +Using the Partial Restore option, you can restore single nodes from a tree (optionally with descendants) that you need to work with. diff --git a/umbraco-cloud/deployment/restoring-content/partial-restore.md b/umbraco-cloud/deployment/restoring-content/partial-restore.md index a35ab0ac767..111990e8a60 100644 --- a/umbraco-cloud/deployment/restoring-content/partial-restore.md +++ b/umbraco-cloud/deployment/restoring-content/partial-restore.md @@ -1,6 +1,6 @@ # Partial Restores -In some cases, you might not want to restore the entire content tree but only the parts that you need. **Partial restore** is a feature that allows for restoring specific parts of your content instead of restoring everything. +In some cases, you might not want to restore the entire content tree but only the parts that you need. Partial restore is a feature that allows for restoring specific parts of your content instead of restoring everything. You can use Partial Restore on: @@ -13,48 +13,42 @@ You can use Partial Restore on: This feature is only available with Umbraco Deploy 3.3+ {% endhint %} -In this scenario, you've cloned down your Cloud environment to your local machine or set up a new Cloud environment. In both cases, the new environment will have an empty Content section as well as an empty Media section. +In this scenario, the Cloud environment is cloned to your local machine or a new Cloud environment has been created. In both cases, the new environment will have an empty Content section as well as an empty Media section. {% hint style="info" %} -This feature will also restore all dependencies of the selected content. For example, when you restore a content node that references media items as well as other content nodes, these will all be restored, including any parent nodes that these nodes depend on. +This feature will also restore all dependencies of the selected content. When you restore a content node that references media items and other content nodes, these will all be restored. This includes any parent nodes that these nodes depend on. {% endhint %} To partially restore the parts you need: 1. Go to the **Content** section of the Umbraco backoffice on your new environment (local or Cloud). 2. Right-click the **Content** tree or click the three dots and select **Do something else**. -3. Choose **Partial Restore** +3. Choose **Partial Restore**. 4. Select the environment that you would like to restore the content from. -5. Click **Select content to restore** and a dialog with a preview of the content tree from the environment you selected opens. +5. **Select content to restore** to open a dialog with a preview of the content tree. 6. Select the content node you would like to restore. -7. Enable **Including all items below** if you want to restore any child nodes _below_ the selected node. +7. Enable **Including all items below** if you want to restore any child nodes below the selected node. 8. Click **Restore**. -9. Once the restore is completed, right-click the Content tree and select **Reload**. - -{% hint style="info" %} -If you select a content node deeper down the tree, all the parents above it, required for the node to exist, will be restored as well. -{% endhint %} +9. Right-click the Content tree and select **Reload** once the restore is complete. ![Partial restore on empty environment](<../../../umbraco-deploy/deployment-workflow/restoring-content/images/partialRestore-onEmpty (1) (1) (1) (1).gif>) -Partial Restores on empty environments are especially helpful when you have a large amount of content and media and do not necessarily need it all for the task you need to do. Instead of having to restore everything which could potentially take a long time, doing a partial restore can be used to shorten the waiting time by only restoring the parts you need. This will ensure that you can quickly get on your way with the task at hand. +Partial Restores on empty environments are helpful when not all content or media is necessary for the tasks to be performed on the new environment. Instead of having to restore everything, doing a partial restore can be used to only restore the parts you need. This will ensure that you can quickly get on your way with the task at hand. ## Environment with existing Content or Media -It is also possible to use the Partial Restore feature in environments where you already have content in the Content tree. - -Imagine that you are working with your Umbraco Cloud project locally. One of your content editors updates a section in the content tree on the Live environment. You would like to see how this updated content looks with the new code you are working on. To partially restore the updated content node, do the following: +It is possible to use the Partial Restore feature in environments where you already have content in the Content tree. 1. Go to the **Content** section of your Umbraco backoffice. 2. Right-click the content node which you know contains updates. -3. Choose **Partial Restore** +3. Choose **Partial Restore**. 4. Select the environment that you would like to restore the content from. 5. Enable **Including all items below** if you want to restore any child nodes _below_ the selected node. 6. Click **Restore**. -7. Once the restore is completed, right-click the Content tree and select **Reload**. +7. Right-click the Content tree and select **Reload** once the restore is complete. ![Partial restore](../../../umbraco-deploy/deployment-workflow/restoring-content/images/partialRestore-onEnvWithContent.png) {% embed url="https://www.youtube.com/embed/C5SnrEf78bQ?rel=0" %} -Video example. +A video showing how to use partial restores between Umbraco Cloud environments. {% endembed %} diff --git a/umbraco-cloud/deployment/streamline-your-deployments.md b/umbraco-cloud/deployment/streamline-your-deployments.md deleted file mode 100644 index e309cc9dbbb..00000000000 --- a/umbraco-cloud/deployment/streamline-your-deployments.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: Follow these guides to ensure smooth and efficient Deployments ---- - -# Streamline Your Deployments - -This section covers everything you need to know about deploying changes, transferring content, managing deletions, and handling hotfixes. Whether deploying between environments or restoring content, these articles will help you streamline your workflow. - -
DeploymentUnderstand the basics of deployments in Umbraco Cloud, including how environments interact and what happens when you deploy changes.deploymentDocumentations Icons_Umbraco_Cloud_Deploying (1).png
Deploying Between EnvironmentsMove changes smoothly between Development, Staging, and Production environments. Learn the best practices for a seamless deployment process.cloud-to-cloud.mdDocumentations Icons_Umbraco_CMS_Tutorials_Multilingual_Website.png
Transferring Content, Media, Members, and FormsThis section explains how to transfer content, media, members, and Umbraco Forms between environments.content-transfer.mdDocumentations Icons_Umbraco_CMS_Extending_Backoffice_UI_API.png
Deploying DeletionsBy default, deletions are not deployed automatically to prevent accidental data loss. Learn how to manage deletions correctly.deploying-deletions.mdDocumentations Icons_Umbraco_CMS_Implementation_Composing.png
Deployment WebhookAutomate and integrate deployments with external systems using Deployment Webhooks.deployment-webhook.mdDocumentations Icons_Umbraco_CMS_Extending_Property_Editors.png
Deploying ChangesExplore how schema changes, configuration updates, and code changes are handled in Umbraco Cloud.local-to-cloud.mdDocumentations Icons_Umbraco_CMS_Tutorials_Umbraco_Forms_and_Zapier.png
- -## Also in this section - -{% content-ref url="../deployment/umbraco-forms-on-cloud.md" %} -[umbraco-forms-on-cloud.md](../deployment/umbraco-forms-on-cloud.md) -{% endcontent-ref %} - -{% content-ref url="../deployment/deploy-dashboard.md" %} -[deploy-dashboard.md](../deployment/deploy-dashboard.md) -{% endcontent-ref %} - -{% content-ref url="../deployment/hotfixes/" %} -[hotfixes](../deployment/hotfixes/) -{% endcontent-ref %} - -{% content-ref url="../deployment/restoring-content/" %} -[restoring-content](../deployment/restoring-content/) -{% endcontent-ref %} diff --git a/umbraco-cloud/deployment/umbraco-forms-on-cloud.md b/umbraco-cloud/deployment/umbraco-forms-on-cloud.md index 9b3fd68b159..baa9184389c 100644 --- a/umbraco-cloud/deployment/umbraco-forms-on-cloud.md +++ b/umbraco-cloud/deployment/umbraco-forms-on-cloud.md @@ -32,7 +32,7 @@ Umbraco Forms is part of the [auto-upgrades on Umbraco Cloud](../product-upgrade To avoid having the auto-upgrades overwrite any of your custom settings, we strongly encourage that you use [config transforms](../set-up/config-transforms.md) when you need custom configuration. Additionally, use [Themes](https://docs.umbraco.com/umbraco-forms/developer/themes) when you need to customize your forms. -Whenever a new minor version of Umbraco Forms is ready, eg. 10.x or 11.x, you will get the option to apply the upgrade to your project. When your project is eligible to receive the new version, you will see an "_Upgrade available!_" label on your Development environment. +Whenever a new minor version of Umbraco Forms is ready, eg. 10.x or 11.x, you will get the option to apply the upgrade to your project. When your project is eligible to receive the new version, you will see an "_Upgrade available!_" label on your left-most environment. ### Version-specific changes @@ -54,7 +54,7 @@ To switch to persisting all definitions for Umbraco Forms data in the Umbraco da 1. Make sure all environments are upgraded to **at least Umbraco Forms version 8.5.2 and Deploy 3.5.0**. 2. Make sure your Forms are in sync between all your Cloud environments. -3. Clone down your Development environment. +3. Clone down your left-most environment. 4. Restore content and Forms to the local clone. 5. Open the configuration file `App_Plugins\UmbracoForms\UmbracoForms.config` from your local clone. 6. Add the following key in the `` section and make sure the value is set to `True`: @@ -94,7 +94,7 @@ You will need to follow the steps below to persist Umbraco Forms data in the Umb ``` 3. Remove all existing `data\revision\forms-form__*.uda` files, so it's not possible to accidentally revert to this state (removing `UDA` files won't remove the actual form on deploy). 4. Push the change back to the Cloud environment. - * If you have more than 1 Cloud environment, make sure to deploy the change through to all of them. + * If you have more than one Cloud environment, make sure to deploy the change through to all of them. 5. You are now able to queue your Forms for transfer between the Cloud environments, like content and media. If you do not have the `transferFormsAsContent` setting in the `UmbracoDeploy.settings.config` file, you do not need to make any further changes. diff --git a/umbraco-cloud/frequently-asked-questions.md b/umbraco-cloud/frequently-asked-questions.md index dba0e0b7da3..a4bd0c6df38 100644 --- a/umbraco-cloud/frequently-asked-questions.md +++ b/umbraco-cloud/frequently-asked-questions.md @@ -1003,7 +1003,7 @@ Other reasons for missing the upgrade: For more details, see the [Upgrades](product-upgrades/README.md#the-process-of-auto-upgrading-a-umbraco-cloud-project) article. -### Do pending commits (dev to live environment) derail the upgrade process? +### Do pending commits between environments derail the upgrade process? Pending commits do not stop the auto-upgrade. @@ -1085,7 +1085,7 @@ Yes, TDE is enabled by default for sites created after May 2, 2017. For older si ### Can a shared SQL Server be used for a development team instead of the SQL/LocalDb database created by Umbraco Cloud? -No, a shared database should not be used. Umbraco Cloud is designed so each team member can safely make changes and push them to the development environment. Other developers can do the same, allowing changes to be tested in a structured way. Once changes are confirmed, developers can pull updates and continue working on new features. +No, a shared database should not be used. Umbraco Cloud is designed so each team member can safely make changes locally and push them to the Cloud environment. Other developers can do the same, allowing changes to be tested in a structured way. Once changes are confirmed, developers can pull updates and continue working on new features. Using a shared database can cause two major issues: diff --git a/umbraco-cloud/getting-started/baselines/README.md b/umbraco-cloud/getting-started/baselines/README.md index 367c2049f00..739da776d49 100644 --- a/umbraco-cloud/getting-started/baselines/README.md +++ b/umbraco-cloud/getting-started/baselines/README.md @@ -1,10 +1,10 @@ # Baselines -A Baseline Child project is very similar to a Fork (forked repository) on GitHub where we create a clone of an existing project while maintaining a connection between the two projects. The connection exists between the _Live_ environment of the existing project, the **Baseline project**, and the _Development_ or Live environment - of the newly created project, the **Child project**. +A Baseline Child project is similar to a Fork (forked repository) on GitHub. A clone is created of an existing project while maintaining a connection between the two projects. The connection exists between the Live environment of the **Baseline project**, and the left-most mainline environment of the **Child project**. Any project can act as a Baseline project. -The basic idea is that you have a project that contains all your standard Umbraco packages/components, maybe even configured with some default Document Types, which you want to use as a baseline for future projects. When you've made changes to your Baseline project, you can then push these changes out to all the Child projects with a click of a button. +The basic idea is that you have a project that contains all your standard Umbraco packages/components. Some default Document Types which you want to use as a baseline for future projects is also configured. When you've made changes to your Baseline project, you push these changes out to all the Child projects with a click of a button. ![Baseline workflow](images/baseline-workflow.gif) @@ -14,7 +14,7 @@ The basic idea is that you have a project that contains all your standard Umbrac Learn how to work with Baselines. {% endembed %} -## Creating a Child Project +## Create a Child Project To create a child project: diff --git a/umbraco-cloud/getting-started/baselines/configuration-files.md b/umbraco-cloud/getting-started/baselines/configuration-files.md index 9a3e914eb0a..4932761e966 100644 --- a/umbraco-cloud/getting-started/baselines/configuration-files.md +++ b/umbraco-cloud/getting-started/baselines/configuration-files.md @@ -28,7 +28,9 @@ When you need a specific configuration on Child projects, you should always use Here is a few examples of what could be transformed in the child sites. -## Adding or updating appsettings (i.e. child-appsettings.web.live.xdt.config) +## Adding or updating appsettings + +{% code title="child-appsettings.web.live.xdt.config" %} ```xml @@ -45,7 +47,11 @@ Here is a few examples of what could be transformed in the child sites. ``` -## Setting the SMTP settings for the child project (i.e. child-smtpsettings.web.live.xdt.config) +{% endcode %} + +## Setting the Simple Mail Transfer Protocol (SMTP) settings for the child project + +{% code title="child-smtpsettings.web.live.xdt.config" %} ```xml @@ -61,7 +67,11 @@ Here is a few examples of what could be transformed in the child sites. ``` -## Setting custom rewrite rules for the child project (i.e. child-iisrewrite.web.live.xdt.config) +{% endcode %} + +## Setting custom rewrite rules for the child project + +{% code title="child-iisrewrite.web.live.xdt.config" %} ```xml @@ -86,12 +96,14 @@ Here is a few examples of what could be transformed in the child sites. ``` -The above could either be added to its config files or be split up into one config file per setting. Umbraco Cloud will run through all the config files for the project. i.e. in one file +{% endcode %} + +The above could either be added to its config files or be split up into one config file per setting. Umbraco Cloud will run through all the config files for the project. -* child.web.live.xdt.config +* `child.web.live.xdt.config` or having multiple files -* child-appsettings.web.live.xdt.config -* child-iisrewrite.web.live.xdt.config -* child-smtpsettings.web.live.xdt.config +* `child-appsettings.web.live.xdt.config` +* `child-iisrewrite.web.live.xdt.config` +* `child-smtpsettings.web.live.xdt.config` diff --git a/umbraco-cloud/getting-started/environments.md b/umbraco-cloud/getting-started/environments.md index 933950b0934..54181fc2542 100644 --- a/umbraco-cloud/getting-started/environments.md +++ b/umbraco-cloud/getting-started/environments.md @@ -1,66 +1,92 @@ +--- +description: >- + Environments are a core part of your Umbraco Cloud project. This is where you + develop, write, build, and eventually publish your website. +--- + # Environments -## What is an environment? +An Umbraco Cloud environment is defined as a _workspace_ and is also a Git repository. When you have more than one environments on your project, these environments act as branches of the main repository. -An environment on an Umbraco Cloud project can be defined as a _workspace_ and is at the same time a Git repository. When you have more than one environment on your project, these environments will act as branches of the main repository. +Umbraco Cloud uses a deployment model that relies on Git and other core technology. This gives you the option to move both content and structure files from one environment to another. Learn more in the [Deployment section](../deployment/). -Umbraco Cloud uses a deployment model that relies on Git and other core technology, which gives you the option to move both content and structure files from one environment to another. Learn more in the [Deployment section](../deployment/). +You can have multiple environments in your Umbraco Cloud project, with two types available: **Mainline Environments** and **Flexible Environments**. -When you have multiple environments in your Umbraco Cloud project: +The image below shows a Cloud setup including two mainline environments and one flexible environment connected to the left-most mainline environment. -* The _Development_ environment is the first environment in the workflow. +![A Cloud setup including 2 mainline environments and 1 flexible environment connected to the left-most mainline environment](images/cloud-environments.png) - This is the environment you are going to work with when building the structure of your website. This is also the environment you clone down when you want to work on your project locally. +## Mainline Environments - The Development environment is included in the Standard and Professional plans on Umbraco Cloud. In the Starter plan, you have the option to add the Development environment. -* The environment next in line in the workflow is the _Staging_ environment. +A mainline environment serves as the root deployment pipeline, responsible for managing code and content flow. Each mainline environment is a part of the [left-to-right deployment workflow](../deployment/). - This environment enables you to give your team members different workspaces - the developers can work with code in the Development environment while content editors can work with content in the Staging environment. All of this without affecting the actual public site. +The **left-most mainline environment** is where you can connect to your local machine using Git. This environment is often called the Development environment. - The Staging environment is included in the Professional plan. In the Standard plan, you have the option to add the Staging environment. +The **right-most mainline environment** is your live website, often called the Live or Production environment. -{% hint style="info" %} -Both the Development and the Staging environments are protected with **basic authentication**. This means that you must log in to see the frontend of these environments. -{% endhint %} +Each mainline environment can have one or more flexible environments branching off from it. -* The final environment is the _Live_ environment. +## Flexible Environments - This is your live site - the site that's visible to the public. When you are in trial mode the Live environment will be protected by basic authentication - this will be removed as soon as you set up a subscription for the project. +A flexible environment is an environment that branches off a mainline environment. It is positioned vertically from the mainline deployment flow. - The Live environment is included in the Standard and Professional plans on Umbraco Cloud. +Changes made on a flexible environment can only be pushed to the next designated Mainline Environment in the pipeline. -For more information about the workflow on Umbraco Cloud, see the [Deployments](../deployment/) article. Below you will find a technical overview of the different parts that make up an environment on your Umbraco Cloud project: +Technically, the flexible environment is connected only to its mainline environment using a Git remote. This ensures that changes follow a structured path while allowing flexibility in development workflows. -![Umbraco Cloud Environment Technical Overview](images/environment-tech-overview.png) +Learn more about how this works in the [Flexible Environments](flexible-environments.md) article. + +## Plans and availability -## Site and Git Repository +
PlanMainline EnvironmentsFlexible Environments
Starter2false
Standard3true
Professional4true
+ +## Environment Components + +### Site and Git Repository Each environment on Umbraco Cloud has both a Git repository and a folder with your actual live site. The Git repository is what you clone down when you work with the project locally, and it's where your changes are pushed to. -The live site (`/site/wwwroot/`) contains the files used to show your website to the world. When you push changes from your local machine, they are pushed to the Git repository (`/site/repository/`), and when this finishes successfully the changes are copied into the live site. +The live site (`/site/wwwroot/`) contains the files used to show your website to the world. When pushing changes from your local machine, they are pushed to the Git repository (`/site/repository/`). When this finishes successfully, the changes are copied into the live site. + +### Configuration files + +An `appSettings.json` file holds all configurations for the Umbraco CMS project within the Cloud project. This file follows ASP.NET standards as they are tied to the Umbraco CMS installation. -## Team Members/Invite Users +It is possible to set up specific configurations for each environment: -All the team members you add through the Umbraco Cloud Portal will also be added as backoffice users in your environments. As with any other Umbraco CMS installation, you can also add users directly in the backoffice of your Umbraco Cloud environments. If you do this, the user will not have the option to deploy changes between the environments. +1. Clone the `appSettings.json` file. +2. Rename it by adding the environment name: `appSettings.{EnvironmentAlias}.json`. + +The `EnvironmentAlias` is fetched from the Environment variable named `DOTNET_ENVIRONMENT`. This variable can be found in the Environment Variables section of Kudu on the environment. You can read more about ASP.NET Configuration in the official [Microsoft documentation](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-9.0). + +{% hint style="info" %} +Make sure that when you start up the Umbraco Application, you load the correct JSON file as per the ASP.NET Configuration in the official [Microsoft documentation](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-9.0). +{% endhint %} + +### Team Members + +All the team members you add through the Umbraco Cloud Portal will also be added as backoffice users in your environments. You can also add users directly in the backoffice of your Umbraco Cloud environments. If you do this, the user will not have the option to deploy changes between the environments. Read more about this and team member roles in the [Team Members](../set-up/project-settings/team-members/) article. -## SQL Database +### SQL Database Each of your Umbraco Cloud environments has its own SQL Azure database. You have full access to the databases, and you can create custom tables as you'd expect from any other hosting provider. Learn more about how to connect to your Umbraco Cloud databases in the [Database](../databases/) article. -## Power Tools (Kudu) +### Power Tools (Kudu) -Aside from viewing the files on your Umbraco Cloud environments when cloning down the project to your local machine, you also have access to what we call **Power Tools** - Kudu. +Aside from viewing the files when cloning down the project to your local machine, you also have access to Kudu (Power Tools). -This is a dashboard that allows you to browse, view, and edit all the files in your Umbraco Cloud environment. We recommend using the tool _only_ when you are following one of our guides in the Troubleshooting section. +Kudu is a dashboard that allows you to browse, view, and edit all the files in your environments. We recommend using the tool _only_ when you are following one of our guides. In the [Power Tools](../set-up/power-tools/) article, you can read more about how to access the dashboard, and how we recommend using it. -## Environment History +### Environment History -Each of your Umbraco Cloud environments has a Git repository and therefore also a Git history. We've made a simplified view of this Git history in the Umbraco Cloud Portal - the **Environment History**. +Each of your Umbraco Cloud environments has a Git repository and therefore also a Git history. We've made a simplified view of this Git history in the Cloud Portal. The **History** is found via the action menu available on each environment in the environments overview on your project. -In this view, you'll be able to see what file changes have been made in each environment. +In the History view, you'll be able to see what file changes have been made in the environment. + +![Umbraco Cloud Environment Technical Overview](images/environment-tech-overview.png) diff --git a/umbraco-cloud/getting-started/explore-umbraco-cloud.md b/umbraco-cloud/getting-started/explore-umbraco-cloud.md index 7182fe74d8d..1e3c0f503f7 100644 --- a/umbraco-cloud/getting-started/explore-umbraco-cloud.md +++ b/umbraco-cloud/getting-started/explore-umbraco-cloud.md @@ -7,7 +7,6 @@ description: Begin your journey with Umbraco Cloud by exploring the essentials. This section will help you get up and running with the core features of Umbraco Cloud. Whether you are new to Umbraco or migrating from another platform, these articles will walk you through everything you need to know to get started. -
The Cloud PortalLearn how to log in, navigate the interface, and start managing your Umbraco projects.the-umbraco-cloud-portalDocumentations Icons_Umbraco_CMS_Fundamentals_Backoffice.png
Project OverviewUnderstand how the Umbraco Cloud environment is structured and what each section of your project means.project-overview.mdDocumentations Icons_Umbraco_CMS_Tutorials_Custom_Dashboard.png
EnvironmentsEnvironments are the foundation of your Umbraco Cloud project. Learn how to set up and manage your environments.environments.mdDocumentations Icons_Umbraco_Sustainability_Best_Practices_Infrastructure.png
BaselinesLearn how to create and manage baselines in Umbraco Cloud.baselinesDocumentations Icons_Umbraco_CMS_Implementation_Composing (1).png
Migrate to Umbraco CloudIf you're moving from another platform or version of Umbraco, you'll want to understand the steps involved in migrating to Umbraco Cloud. This section covers everything from preparation to execution.migrate-to-umbraco-cloud.mdDocumentations Icons_Umbraco_CMS_Reference_Querying_and_Models.png
Repositories in a Cloud ProjectLearn how to work with Git repositories, including setting them up, syncing, and managing changes.git-repository-in-a-cloud-project.mdDocumentations Icons_Umbraco_CMS_Reference_Caching.png
## Also in this section diff --git a/umbraco-cloud/getting-started/flexible-environments.md b/umbraco-cloud/getting-started/flexible-environments.md index 594c0c3ce6c..0196ae6fda3 100644 --- a/umbraco-cloud/getting-started/flexible-environments.md +++ b/umbraco-cloud/getting-started/flexible-environments.md @@ -2,7 +2,6 @@ description: >- Use flexible environments to create a separate workflow along side the left-to-right deployment approach in Umbraco Cloud. -hidden: true --- # Flexible Environments (beta) @@ -11,15 +10,13 @@ hidden: true Beta feature: Some features might not be fully available. {% endhint %} -Flexible Environments allow users to create and manage environments outside the regular left-to-right deployment flow. This enhancement provides greater flexibility in orchestrating both code and content workflows, empowering developers and content editors to work in a way that best suits their needs. +Flexible Environments allow users to create and manage environments outside the regular left-to-right deployment flow. This enhancement provides flexibility in orchestrating code and content workflows, empowering developers and content editors to work in a way that best suits their needs. -{% hint style="info" %} -Limitations +While the mainline environments use a horizontal deployment flow, flexible environments work differently. A flexible environment is added to an existing mainline environment and only deploys to and from that environment. Get an overview of the different types of environments in the [Environments](environments.md) article. -* Only one flexible environment is available. -* Flexible environments are only available to Projects paid with Invoices or Credits. -* CI/CD Pipelines are not supported. -{% endhint %} +![A Cloud project set up with two mainline environments and one flexible environment](images/cloud-environments.png) + +The image above shows a project setup including two mainline environments and one flexible environment attached to the left-most mainline environment. With Flexible Environments, teams can create environments as needed, allowing for more efficient and tailored workflows. @@ -30,16 +27,28 @@ This feature enables: * **Easier hotfixes and feature releases**: Urgent fixes can be deployed directly without being blocked by unfinished work in other environments. * **Improved Content Management**: Content editors can create, test, and validate content changes without depending on a specific environment. +## How it works + +* A flexible environment is added and connected to a single mainline environment. +* Developers can develop and build features in the flexible environment without affecting the mainline environment. +* Once a feature is complete, it can be merged back into the mainline environment and become part of regular deployment flow. +* When changes are made to the mainline environment, they must be pulled into the flexible environment before changes can be pushed. + +Learn more about the deployment process in the [Deployments](../deployment/) section. + ## Project Prerequisites Before you can add a Flexible environment to your project, the following prerequisites must be met: -* Uses Umbraco Version 10, 13, 14 or greater. +* Uses Umbraco Version 10 or greater. * Uses Deploy Version Greater than 10.4.1, 13.3.0, 14.2.0 or greater. -{% hint style="info" %} -Flexible Environments are not available on Heartcore projects. -{% endhint %} +### Limitations + +* Only one flexible environment is available. +* Flexible environments are available only for projects paid with invoices or credits. +* CI/CD Pipelines are not supported. +* Flexible Environments are not available for Heartcore projects. ## Plans and Availability diff --git a/umbraco-cloud/getting-started/git-repository-in-a-cloud-project.md b/umbraco-cloud/getting-started/git-repository-in-a-cloud-project.md index 87f9aadf4b2..3e2a716f7dc 100644 --- a/umbraco-cloud/getting-started/git-repository-in-a-cloud-project.md +++ b/umbraco-cloud/getting-started/git-repository-in-a-cloud-project.md @@ -1,9 +1,9 @@ # Repositories in a Cloud Project -Each Umbraco Cloud project can have multiple environments: Development, Staging, and Live depending on your Cloud project plan. Each environment has its own git repository that is hosted on Umbraco’s Cloud platform. +Each Umbraco Cloud project can have multiple environments: Mainline and Flexible Environments. Each environment has its own git repository that is hosted on Umbraco’s Cloud platform. {% hint style="info" %} -Umbraco Cloud repositories are _only_ deployment repositories and should not be used as source code repositories. +Umbraco Cloud repositories are only deployment repositories and should not be used as source code repositories. {% endhint %} Ideally, your Umbraco Cloud setup should look like this: @@ -31,15 +31,15 @@ You need to put your custom code in a different source control repository of you {% endtab %} {% endtabs %} -## A Git Umbraco Cloud source control repository with the locally cloned Umbraco project +## A source control repository with the locally cloned Umbraco project -We recommend creating a Cloud project with at least two environments: a Development environment and a Live environment. To work with a local copy of your site, you then clone down the Development environment using the **Clone project** option from the Cloud Portal and start building your website locally. This repository is different from your source control repository. +It is recommended to create a Cloud project with at least two environments: a Live environment including one extra mainline environment. Work with a local copy of the site by cloning down the left-most environment. This repository is different from your source control repository. -Once you're happy with the results or wish to see how your website has progressed, you push the changes back to the Development environment. If everything is working as expected you then deploy your changes to the Live environment. +Once you're happy with the results or wish to see how your website has progressed, you push the changes back to the Cloud. If everything is working as expected, deploy your changes to the Live environment. {% tabs %} {% tab title="Umbraco 10+" %} -#### Code Deployment Summary +### Code Deployment Summary ![Umbraco Cloud Overview](images/UCP.png) @@ -47,14 +47,14 @@ In the above diagram, the Umbraco Git repository contains the source code of a c With this setup, once you commit your code in the Umbraco Cloud Git repository, your C# source code is built by Umbraco Cloud and then deployed to the `wwwroot` folder. -#### Disadvantages of using an Umbraco Cloud Project repository as a source code repository +### Disadvantages of using an Umbraco Cloud Project repository as a source code repository * We only guarantee to maintain and keep the `master` branch. If there are any other branches, they might be removed without any notification causing data loss. * You will need to commit your frontend artifacts as the build pipeline only builds dlls from your C# code. {% endtab %} {% tab title="Legacy Umbraco 7 and 8" %} -#### Code Deployment Summary +### Code Deployment Summary

Umbraco cloud overview Legacy versions

@@ -62,11 +62,9 @@ In the above diagram, the external git repository contains the source code of a With this setup, you commit your changes twice. Once to commit your code in your source control and the other commit to the Umbraco Cloud Git repository to deploy your website. Your source code is not hosted on Umbraco Cloud but only your cloned project will be in the Umbraco Cloud Git Repository. Your code is built and compiled into the cloned project and then pushed to Umbraco Cloud. Thus updating the site with your latest code changes. -#### Disadvantages of using an Umbraco Cloud Project repository as a source code repository +### Disadvantages of using an Umbraco Cloud Project repository as a source code repository * We only guarantee to maintain and keep the `master` branch. If there are any other branches, they might be removed without any notification causing data loss. * You will always need to commit your dll files. {% endtab %} {% endtabs %} - -## diff --git a/umbraco-cloud/getting-started/images/cloud-environments.png b/umbraco-cloud/getting-started/images/cloud-environments.png new file mode 100644 index 00000000000..a54256de6a8 Binary files /dev/null and b/umbraco-cloud/getting-started/images/cloud-environments.png differ diff --git a/umbraco-cloud/getting-started/images/project-components.png b/umbraco-cloud/getting-started/images/project-components.png deleted file mode 100644 index 25aeb5fbe23..00000000000 Binary files a/umbraco-cloud/getting-started/images/project-components.png and /dev/null differ diff --git a/umbraco-cloud/getting-started/images/project-overview.png b/umbraco-cloud/getting-started/images/project-overview.png new file mode 100644 index 00000000000..e013b1a9a04 Binary files /dev/null and b/umbraco-cloud/getting-started/images/project-overview.png differ diff --git a/umbraco-cloud/getting-started/migrate-to-umbraco-cloud.md b/umbraco-cloud/getting-started/migrate-to-umbraco-cloud.md index c6ba48e092b..3a483470f38 100644 --- a/umbraco-cloud/getting-started/migrate-to-umbraco-cloud.md +++ b/umbraco-cloud/getting-started/migrate-to-umbraco-cloud.md @@ -117,7 +117,7 @@ You can create a new Umbraco Cloud project in one of the two ways: 1. Click **Create project** in the Umbraco Cloud Portal. 2. Choose **Umbraco Cloud** as the Type. -3. Choose a **plan** that enables you to add a Development environment. +3. Choose a **plan** that enables you to add an extra mainline environment. 4. Select the **version** that matches the project you want to migrate. 5. Give the project a **name**. 6. Choose from which **Region** the site should be hosted. @@ -128,10 +128,16 @@ You can create a new Umbraco Cloud project in one of the two ways: 11. Check the "Terms and conditions" box. 12. Click **Create Project**. -Once the project is set up, **add a Development** environment. This will enable you to start over with the migration, should something go amiss. +Once the project is set up: + +1. Select **Configure environments**. +2. Add a new **mainline environment**. + * Throughout this guide, this mainline environment will be referred to as the **Development environment**. + +Having more than one environment on your project, will enable you to start over with the migration process should it be needed. {% hint style="info" %} -Many processes happen in the background when a new Cloud environment is set up. It might take several minutes before the environments are ready to use. +Many processes happen in the background when a new Cloud environment is set up. It might take some time before the environments are ready to use. {% endhint %} With the Cloud project set up and ready, the migration can start in the next step. @@ -152,7 +158,7 @@ The Umbraco Cloud project is now ready for the next step where the two projects To continue the migration the next step is to clone down the Umbraco Cloud environment to merge it with the Umbraco CMS project. -Follow the steps outlined in the [Working with a Local Clone](../set-up/working-locally.md#cloning-an-umbraco-cloud-project) article to clone down the **Development** **environment** of the Umbraco Cloud project. +Follow the steps outlined in the [Working with a Local Clone](../set-up/working-locally.md#cloning-an-umbraco-cloud-project) article to clone down the Development environment on the project. {% hint style="info" %} Do not run the project after cloning it down. diff --git a/umbraco-cloud/getting-started/project-overview.md b/umbraco-cloud/getting-started/project-overview.md index d7d57c4b7c7..2900c6385d9 100644 --- a/umbraco-cloud/getting-started/project-overview.md +++ b/umbraco-cloud/getting-started/project-overview.md @@ -1,24 +1,21 @@ # Project Overview -Umbraco Cloud Projects are made of three major components: Environments, Team Members/Invite Users, and a Settings section. +Umbraco Cloud Projects are made of three major components: Environments, Team Members/Invite Users, and Settings. -![Project overview](images/project-components.png) +![Project overview](images/project-overview.png) ## Environments -The number of _Environments_ in your project is dependent on which plan you are on: +The number of Environments in your project is dependent on which plan you are on: -* With the **Starter Plan**, you have the option to add a _Development_ environment. -* With the **Standard Plan**, you get a _Development_ and a _Live_ environment with the option to add a _Staging_ environment. You can add/remove environments as needed -* With the **Professional Plan**, you get a _Development_, a _Staging_, and a _Live_ environment - as with the Standard Plan you can add/remove environments as needed. -* With the **Enterprise Plan**, you get a _Development_, a _Staging_, and a _Live_ environment - as with the Professional Plan you can add/remove environments as needed. +
PlanEnvironmentsFlexible EnvironmentsEnvironment Combinations Examples
Starter2falseQA + Production
Standard3trueFlexible + QA + Production
Development + QA + Production
Professional4trueFlexible + Development + QA + Production
To get a technical overview of your Cloud environments, see the [Environments](environments.md) article. For more information on how to add or remove environments, see the [Manage Environments](../set-up/manage-environments.md) article. ## Team Members/Invite Users -Another major component of your Umbraco Cloud project is _Team Members_. When you add team members to a project, they will automatically be added as backoffice users in all the environments. Team members can be added as _Admins_, _Writers_, or _Readers_. Refer to the [Team Members](../set-up/project-settings/team-members/) article to learn more about these roles. +Another major component of your Umbraco Cloud project is Team Members. When you add team members to a project, they will automatically be added as backoffice users in all the environments. Team members can be added as _Admins_, _Writers_, or _Readers_. Refer to the [Team Members](../set-up/project-settings/team-members/) article to learn more about these roles. ## Settings -In the _Settings_ section, you can manage and configure your project to fit your needs. Learn more about the different settings in the [Project Settings](../set-up/project-settings/) article. +There are many different settings available for you to configure your project for your needs. Learn more about the settings in the [Project Settings](../set-up/project-settings/) article. diff --git a/umbraco-cloud/getting-started/team-workflow-on-cloud.md b/umbraco-cloud/getting-started/team-workflow-on-cloud.md index 02da5ef2e02..ec45d3b5bc2 100644 --- a/umbraco-cloud/getting-started/team-workflow-on-cloud.md +++ b/umbraco-cloud/getting-started/team-workflow-on-cloud.md @@ -1,11 +1,9 @@ # Best Practice for Working in Teams on Umbraco Cloud -In this article, we will look at some of the best practices and recommendations when you are working in teams on your Umbraco Cloud projects. +This article will look at some of the best practices and recommendations when you are working in teams on your Umbraco Cloud projects. ## Working with Git in Teams -### Pull before you Push - Always start by making a pull request from your project before you push anything back up to Cloud. This way you ensure that you do not accidentally overwrite the work that someone else in your team has worked with. ### Create branches locally @@ -14,16 +12,18 @@ Umbraco Cloud is built on top of Git which means that you can create branches lo ## Working with Environments in a team -### Set up a Development environment +It is recommended to use multiple environments when you are working in teams. With additional environments, members of a team can work locally, pushing up changes to the Cloud environment for testing. + +Having multiple environments enables developers to continue developing, while content editors can focus on creating content in a separate environment. -We highly recommend that you use a Development environment when you are working in teams. With the Development environment, members of a team can work on their local version of the project. They can then push back up to the development environment to be tested and approved before being deployed to either the staging or the live environment. +### Flexible Environments -### Set up a Staging environment +When you need to work on a new feature, using a flexible environment ensures that the regular workflow isn't affected. The flexible environment is connected to a single mainline environment and isn't part of the left-to-right deployment workflow. -When working in a bigger team with both developers and content editors, we highly recommend that you set up a Staging environment. This way the developers can continue developing in the Development environment, while the content editors can focus on creating delightful content in the Staging environment. +Learn more about how this works in the [Flexible Environments](flexible-environments.md) article. ## Team development workflow On Cloud -For a more in-depth example of how to work in teams on Umbraco Cloud projects, Our Gold Partner ProWorks have created an article about how they have set up a [Team development workflow on Umbraco Cloud](https://skrift.io/issues/integrating-umbraco-cloud-with-team-development-workflow/). +For a more in-depth example of how to work in teams, our Gold Partner ProWorks has written an article on [Team development workflows](https://skrift.io/issues/integrating-umbraco-cloud-with-team-development-workflow/). -This article can serve as inspiration if you are an agency and are looking into setting up a bigger project where several people will be working on Umbraco Cloud. +This article serves as inspiration if you looking into setting up a bigger project where multiple people will be working on Umbraco Cloud. diff --git a/umbraco-cloud/product-upgrades/README.md b/umbraco-cloud/product-upgrades/README.md index 5fe484cb97f..f029f4b55bf 100644 --- a/umbraco-cloud/product-upgrades/README.md +++ b/umbraco-cloud/product-upgrades/README.md @@ -1,6 +1,6 @@ # Product Upgrades -_This document describes when & what product updates are rolled out on Umbraco Cloud_ +This document describes when and what product updates are rolled out on Umbraco Cloud. ## What products are auto-upgraded? @@ -9,7 +9,7 @@ _This document describes when & what product updates are rolled out on Umbraco C * Deploy * Internal Umbraco Cloud services (generally these updates will not affect running websites but in some cases, if they do we will notify Umbraco Cloud users via the status page) -When minor upgrades are available, you will need a Development environment on your project in order to get the new version. Read the [Minor Upgrades](minor-upgrades.md) article for more details. +When minor upgrades are available, you will need an additional mainline environment on your project in order to get the new version. Read the [Minor Upgrades](minor-upgrades.md) article for more details. ## When do upgrades happen? @@ -47,17 +47,17 @@ This describes how a Umbraco Cloud project is auto-upgraded: * The upgrade payload will have been created for the specific product(s) being upgraded * The payload is a set of files (such as DLLs, and other ASP.NET website files) -* The upgrader will verify that the home page of all the environments (dev/staging/live) is healthy, meaning they don’t return an HTTP status error. If all environments are ok, it will proceed. -* The upgrader will take a snapshot of the Dev site’s home page including its HTTP status code result and its HTML contents. -* The payload is deployed to the Dev site’s Git repository and committed with a tag for the product version being updated. This new Git repository commit will replace the Umbraco product assembly (DLL) files along with other product files such as files located in /umbraco, /umbraco\_client folders +* The upgrader will verify that the home page of all the environments in the mainline environment is healthy, meaning they don’t return an HTTP status error. If all environments are ok, it will proceed. +* The upgrader will take a snapshot of the left-most environments home page including its HTTP status code result and its HTML contents. +* The payload is deployed to the left-most environments Git repository and committed with a tag for the product version being updated. This new Git repository commit will replace the Umbraco product assembly (DLL) files along with other product files such as files located in /umbraco, /umbraco\_client folders * The normal Umbraco Cloud deployment process is invoked and the repository files are deployed to the website * The upgrader will automatically ensure the web.config version and the database version are updated so that the Installer/upgrade page is not shown -* The upgrader will verify that the new HTTP status code returned from the Dev site’s home page is OK and will verify that the HTML contents of the home page match that of the snapshot originally taken. +* The upgrader will verify that the new HTTP status code returned from the left-most environments home page is OK and will verify that the HTML contents of the home page match that of the snapshot originally taken. * If either of these tests fails we will be notified and Umbraco will take appropriate measures to roll back the site to its previous state * The failed upgrade is then tracked for reporting and the customer will be notified if necessary -* When the Dev site is upgraded successfully, the upgrader will continue this same process for the next environment in the chain (that is Dev -> Staging -> Live) depending on the number of environments that exist for the project. +* When the left-most environment is upgraded successfully, the upgrader will continue this same process for the next environment in the chain. -{% hint style="info" %} Changes for patches might appear on Development, even if they have already been applied to Live. The environments will not be synchronized during the upgrade process. This is because synchronization risks pushing other apparent changes from one environment to another. Those changes will need to be deployed. Once that has been done, the environments will be in sync again. {% endhint %} +{% hint style="info" %} Changes for patches might appear on left-most environment, even if they have already been applied to Live. The environments will not be synchronized during the upgrade process. This is because synchronization risks pushing other apparent changes from one environment to another. Those changes will need to be deployed. Once that has been done, the environments will be in sync again. {% endhint %} ## How do baseline updates work? diff --git a/umbraco-cloud/product-upgrades/major-upgrades.md b/umbraco-cloud/product-upgrades/major-upgrades.md index e2fdfd4e260..bef0fedf328 100644 --- a/umbraco-cloud/product-upgrades/major-upgrades.md +++ b/umbraco-cloud/product-upgrades/major-upgrades.md @@ -16,11 +16,11 @@ Make sure any packages you use are compatible with the latest version of Umbraco Be aware of any [Breaking changes](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/upgrading/version-specific#breaking-changes) introduced in the latest version of Umbraco CMS to avoid issues during the upgrade. {% endhint %} -## **Before you start the upgrade** +## Before you start the upgrade Before upgrading your Umbraco Cloud project to the latest major version, you must consider the version your project is already on. This will impact the upgrade flow you will be following. -### **Upgrading from a Short Term Supported (STS) version** +### Upgrading from a Short Term Supported (STS) version When upgrading from an STS version, you must start by upgrading to the closest Long-term Support (LTS) major. If the version you are upgrading to is an STS version, you can upgrade to that version, directly from the closest LTS. You can upgrade directly if there are no LTS versions between the current one and the one you are upgrading to. @@ -30,7 +30,7 @@ Refer to the [Long-term support and EOL article](https://umbraco.com/products/kn Start by upgrading to the closest LTS. In this case, that is Umbraco 13. After that, you can upgrade directly from Umbraco 13 to Umbraco 15. -### **Upgrading from a Long Term Supported (LTS) version** +### Upgrading from a Long Term Supported (LTS) version When upgrading from an LTS version, you must start by looking at the versions between yours and the one you are upgrading to. Is there another LTS version in that line, you need to upgrade to that version first. @@ -40,7 +40,7 @@ Refer to the [Long-term support and EOL article](https://umbraco.com/products/kn Skipping upgrades to STS versions, like 11 and 12, means you will not receive warnings about obsolete features. We recommend keeping the [Breaking Changes documentation](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/upgrading/version-specific#breaking-changes) handy to avoid any surprises. {% endhint %} -#### _Example: Upgrading from Umbraco 10 (LTS) to Umbraco 15 (STS)_ +#### Example: Upgrading from Umbraco 10 (LTS) to Umbraco 15 (STS) Between version 10 and 15, there is another LTS version: Umbraco 13. The first step is therefore to upgrade to Umbraco 13. After that, you can upgrade directly from Umbraco 13 to Umbraco 15. @@ -53,7 +53,7 @@ Look for the "**Upgrade from/to Umbraco xx"** boxes. These boxes contain importa * Follow the **requirements** for [local development](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/requirements#local-development). * An Umbraco Cloud project running [the latest version of your current Umbraco CMS installation](https://our.umbraco.com/download/releases) * The **latest** .[NET version](https://dotnet.microsoft.com/en-us/download/visual-studio-sdks) is installed locally. -* **At least 2 environments** on your Cloud project. +* **At least two environments** on your Cloud project. * A backup of your project database. * Directly from your environment. See the [Database backups](../databases/backups.md) article, * Or clone down, restore the project, and back up the local database. @@ -73,7 +73,7 @@ Refer to the [Choose the correct .NET version](https://docs.umbraco.com/umbraco- ## Step 2: Clone down your environment -1. Clone down the **Development** environment. +1. Clone down the **left-most mainline environment**. 2. Build and run the [project locally](../set-up/working-locally.md#running-the-site-locally). 3. Log in to the backoffice. 4. Restore content from your Cloud environment. @@ -254,7 +254,7 @@ Remove the following files and folders _manually_ from your local project: * `/umbraco/UmbracoWebsite` * `/umbraco/config/lang` -Remove the same files from the development environment. This should be done from the **Development** environment through `KUDU` -> `Debug Console` -> `CMD` -> `Site` -> from both the `repository` and `wwwroot` folders. +Remove the same files from the left-most environment. This should be done from the left-most environment through `KUDU` -> `Debug Console` -> `CMD` -> `Site` -> from both the `repository` and `wwwroot` folders. @@ -283,13 +283,13 @@ You can choose between two approaches based on your needs: The following steps involve setting a **content-freeze** period on the project. It is recommended to coordinate this with your content editors before moving forward. {% endhint %} -1. Delete any environments between your left-most (Development) and production environment. -2. Create a new environment from the production environment. +1. Delete any environments between your left-most and production environments. +2. Create a new environment from the production environment - call it Staging. 3. Initiate **content-freeze**. 4. Import content using either of the following approaches: 1. [Restore content and media](../deployment/restoring-content/) directly from the backoffice. 2. Use the [Database Backup and Restore](../databases/backups.md) functionality in the Cloud Portal. -5. Deploy the upgrade from the left-most environment (Development). +5. Deploy the upgrade from the left-most environment. 6. Verify and test all functionality on the upgraded environment. 7. [Remove your custom hostname(s)](../set-up/project-settings/manage-hostnames/) from the production environment. 8. Ensure the hostname(s) no longer point to the production environment. diff --git a/umbraco-cloud/product-upgrades/manual-upgrades/README.md b/umbraco-cloud/product-upgrades/manual-upgrades/README.md index 3039861ea08..373d689eea2 100644 --- a/umbraco-cloud/product-upgrades/manual-upgrades/README.md +++ b/umbraco-cloud/product-upgrades/manual-upgrades/README.md @@ -6,13 +6,17 @@ description: >- # Upgrade your projects manually -In some cases, you might need to upgrade your Umbraco Cloud project manually. It's very similar to how you would upgrade any other Umbraco project but includes a few extra and **very important** steps. +In some cases, you might need to upgrade your Umbraco Cloud project manually. It's similar to how you would upgrade any other Umbraco project but includes a few extra and **important** steps. Umbraco Cloud project uses Umbraco Forms and Umbraco Deploy, which means there are also some dependencies you need to consider when upgrading your Umbraco Cloud project manually. ## Why and when would you do a manual upgrade? -By default, all Umbraco Cloud projects are automatically upgraded when we release new patches (e.g. 8.8.**1**) to the Umbraco CMS as well as Umbraco Forms and Umbraco Deploy. When we release a new _minor_ version (e.g 8.**8**) the upgrade is applied to the Umbraco Cloud engine, and **not to the individual projects** - the same goes for the release of new _major_ versions (e.g. **10**.0). For these minor and major versions, there will be an option on your Umbraco Cloud Development environment to apply the upgrade. The Umbraco Cloud engine will take care of the entire process, and you only need to make sure everything works after the upgrade has been applied. +By default, all Umbraco Cloud projects are automatically upgraded when we release new patches (like 8.8.**1**) to the Umbraco CMS. This also goes for Umbraco Forms and Umbraco Deploy. + +When a new _minor_ version (like 8.**8**) is released, the upgrade is applied to the Umbraco Cloud engine, and **not to the individual projects**. The same goes for the release of new major versions (like **10**.0). + +For minor and major versions, there will be an option on your left-most mainline environment to apply the upgrade. The Umbraco Cloud engine will take care of the entire process, and you only need to ensure everything works when upgrade is complete. We always recommend using the automatic and _semi-automatic_ upgrade options provided to you as part of your Umbraco Cloud project. With that said, it's also possible to upgrade your Umbraco Cloud project manually - this can be done with both patches and minor and major versions. diff --git a/umbraco-cloud/product-upgrades/manual-upgrades/manual-cms-upgrade.md b/umbraco-cloud/product-upgrades/manual-upgrades/manual-cms-upgrade.md index 77e2aecc691..d7740d09033 100644 --- a/umbraco-cloud/product-upgrades/manual-upgrades/manual-cms-upgrade.md +++ b/umbraco-cloud/product-upgrades/manual-upgrades/manual-cms-upgrade.md @@ -14,7 +14,7 @@ This article will give you a step-by-step on how to manually upgrade your Umbrac ## Prepare for the upgrade -* When upgrading a Umbraco Cloud project manually, the very first step is to either [clone down your Cloud Development environment to your local machine](../../set-up/working-locally.md) or pull down the latest changes for your development environment. +* When upgrading a Umbraco Cloud project manually, the first step is to either [clone down left-most mainline environment to your local machine](../../set-up/working-locally.md) or pull down the latest changes for your left-most mainline environment. * Navigate to the `/src/UmbracoProject/` folder to find the `.csproj` file. * Make sure you can run your Cloud project locally and restore content and media. It's important that you check that everything works once the upgrade has been applied and for this, you need to have a clone locally that resembles the Cloud environment as much as possible. @@ -203,7 +203,7 @@ When you've upgraded everything locally, and made sure that everything runs with * Stage and commit all changes in Git * Push the changes to the Cloud environment * When everything is pushed, head on over to the Umbraco Cloud Portal -* Access the backoffice of the Cloud environment you pushed the upgrade to - Development or Live +* Access the backoffice of the Cloud environment you pushed the upgrade * You will again be prompted to log in to complete the database upgrade * You will be sent to the backoffice once the upgrade is complete diff --git a/umbraco-cloud/product-upgrades/minor-upgrades.md b/umbraco-cloud/product-upgrades/minor-upgrades.md index ffdb1ac7237..99d77b68efd 100644 --- a/umbraco-cloud/product-upgrades/minor-upgrades.md +++ b/umbraco-cloud/product-upgrades/minor-upgrades.md @@ -26,10 +26,10 @@ With automatic upgrades enabled, all products on Umbraco Cloud will automaticall If you create a new project on Umbraco Cloud automatic upgrades are enabled by default. {% hint style="info" %} -For projects where automatic minor upgrades are enabled, having a Development environment is not compulsory. However, it is highly recommended to facilitate a smoother and more controlled upgrade experience. In cases where manual upgrades are necessary, a Development environment becomes essential. +For projects where automatic minor upgrades are enabled, having a secondary mainline environment is not required. However, it is highly recommended to facilitate a smoother and more controlled upgrade experience. In cases where manual upgrades are necessary, an additional environment becomes essential. {% endhint %} -A development environment is included in all Umbraco Cloud plans, except Starter. Find pricing details for Umbraco Cloud Starter plans on our [website](https://umbraco.com/products/umbraco-cloud/pricing). +A secondary mainline environment is included in all Umbraco Cloud plans, except Starter. Find pricing details for Umbraco Cloud Starter plans on our [website](https://umbraco.com/products/umbraco-cloud/pricing). ## Manual Minor Upgrades @@ -64,6 +64,6 @@ The upgrade process left off when it needed three more steps. These three steps - To complete the installer, you should visit the site: `https://dev-YOURSITEALIAS.euwest01.umbraco.io`. This will show you the installer screen, where you should insert your backoffice credentials and follow the process. It will run through a few steps, and later Umbraco will be updated to the latest version. 2. Export the metadata files. - The second thing you need to do is to regenerate the metadata files used for transferring items like document types, data types, and media types. This is done by accessing the Power tools (Kudu) on the project, opening the cmd prompt, and browsing to the wwwroot/data folder. Once there, you need to enter `echo > deploy-export`. This will generate the required files for the upgraded site to work with Umbraco Deploy. -3. The last thing to do is to go to the `/site/locks` folder (still through Kudu) and rename the file called `upgrading` to `upgraded-minor` - rename the file by typing `ren upgrading upgraded-minor`. This will indicate to Umbraco Cloud, that the development environment is now ready to deploy all its changes to the next environment. +3. The last thing to do is to go to the `/site/locks` folder (still through Kudu) and rename the file called `upgrading` to `upgraded-minor` - rename the file by typing `ren upgrading upgraded-minor`. This will indicate to Umbraco Cloud, that the left-most environment is now ready to deploy all its changes to the next environment. -Before deploying the upgrade to the next environment, you should verify that everything looks as expected on the development environment. +Before deploying the upgrade to the next environment, you should verify that everything looks as expected on the left-most environment. diff --git a/umbraco-cloud/product-upgrades/version-specific-upgrades/migrate-from-8-to-latest.md b/umbraco-cloud/product-upgrades/version-specific-upgrades/migrate-from-8-to-latest.md index 84a300d4aa8..7718873fee7 100644 --- a/umbraco-cloud/product-upgrades/version-specific-upgrades/migrate-from-8-to-latest.md +++ b/umbraco-cloud/product-upgrades/version-specific-upgrades/migrate-from-8-to-latest.md @@ -21,15 +21,15 @@ You also need to make sure that the packages that you are using are available on ## Prerequisites * A Umbraco 8 Cloud project running **the latest version of Umbraco 8**. -* A clean Cloud project running the latest version of Umbraco with **at least 2 environments**. +* A clean Cloud project running the latest version of Umbraco with **at least two environments**. * A backup of your Umbraco 8 project database. -We strongly recommend having at least **2 environments** on the new Umbraco project. +It is recommended to have at least **two environments** on the new Umbraco project. {% hint style="info" %} If your Umbraco 8 site is using Umbraco Forms, make sure to configure it to store data in the database, before beginning this tutorial [Follow the guide for migrating Umbraco Forms data to the database.](https://docs.umbraco.com/umbraco-forms/developer/forms-in-the-database) -Should something fail during the migration, the Development environment can be removed and re-added to start over on a clean slate. +Should something fail during the migration, the left-most environment can be removed and re-added to start over on a clean slate. {% endhint %} ## Video Tutorial @@ -47,7 +47,7 @@ If you use Umbraco Forms, make sure to have [`StoreUmbracoFormsInDbset`](https:/ 1. Create a backup of the database from your Umbraco 8 project using the [database backup guide](../../databases/backups.md). * Alternatively, you can clone the environment down and take a backup of the local Database after restoring. Make sure to restore both content and media from your Cloud environment after cloning it down. 2. Import the database backup into SQL Server Management Studio. -3. Clone down the **Development** environment from the **new** Cloud project. +3. Clone down the **left-most** mainline environment from the **new** Cloud project. 4. Test the project and make sure to log in to the backoffice. {% hint style="info" %} @@ -122,15 +122,15 @@ Depending on the extent of the project and the amount of custom code and impleme ## Step 4: Deploy and Test on Umbraco Cloud -Once the new Cloud project runs without errors on the local setup, the next step is to deploy and test on the Cloud **Development** environment. +After the project runs locally without errors, deploy and test it on the Cloud's left-most mainline environment. -1. Push the migration and changes to the Umbraco Cloud **Development** environment. +1. Push the migration and changes to the Umbraco Cloud **left-most** mainline environment. {% hint style="info" %} The deployment might take a bit longer than normal as a lot of changes have been made. {% endhint %} -2. Go to the backoffice of the **Development** environment once everything has been pushed. +2. Go to the backoffice of the **left-most** mainline environment once everything has been pushed. 3. Go to **Settings** and open the **Deploy** Dashboard. 4. Click on `Export Schema to Data Files` in the **Deploy Operations** section. * The deployment will result in either of the two: @@ -138,15 +138,15 @@ The deployment might take a bit longer than normal as a lot of changes have been * Select `Clear Signatures` from the **Deploy Operations** section. * Select `Update Umbraco Schema` from the **Deploy Operations** section to clear up the error. * `Last deployment operation completed` - * Everything checks out: The Development environment has been upgraded. -5. Transfer Content and Media from the local clone to the **Development** environment. + * Everything checks out: The left-most environment has been upgraded. +5. Transfer Content and Media from the local clone to the **left-most** mainline environment. * To transfer members make sure that the following Deploy settings are configured in the `appsettings.json`: [`AllowMembersDeploymentOperations` and `TransferMemberGroupsAsContent`](https://docs.umbraco.com/umbraco-deploy/deploy-settings#allowmembersdeploymentoperations-and-transfermembergroupsascontent). -6. Test **everything** in the **Development** environment. +6. Test **everything** in the **left-most** mainline environment. 7. Deploy to the **Live** environment. ## Step 5: Going live -1. Test **everything** in the **Development** environment until it runs without any errors. +1. Test **everything** in the **left-most** mainline environment until it runs without any errors. 2. Setup rewrites on the new Cloud project if relevant. 3. Assign hostnames to the project if relevant. diff --git a/umbraco-cloud/set-up/azure-blob-storage/connect-to-azure-storage-explorer.md b/umbraco-cloud/set-up/azure-blob-storage/connect-to-azure-storage-explorer.md index 5a039187a43..4f0cb4cc4bc 100644 --- a/umbraco-cloud/set-up/azure-blob-storage/connect-to-azure-storage-explorer.md +++ b/umbraco-cloud/set-up/azure-blob-storage/connect-to-azure-storage-explorer.md @@ -10,7 +10,7 @@ description: >- This article provides the steps you need, to connect to your Azure Blob Storage containers using Azure Storage Explorer. {% hint style="warning" %} -We **strongly** recommend that you add all the media items to your Cloud environments through the backoffice. Clone your environment to your local machine to manage the files of your media library. +It is **strongly** recommend that you add all the media items to your Cloud environments through the backoffice. Clone your environment to your local machine to manage the files of your media library. **Important**: If you upload your media files manually using this method, they will not be available in the backoffice. @@ -19,7 +19,7 @@ All media needs to be added through the Umbraco backoffice. ## Getting the credentials -The first thing to sort out, if you want to connect to the Azure Blob Storage container of your environment is the credentials. +The first thing to sort out, if you want to connect to the Azure Blob Storage container of your environment is the credentials. To find the connection details for your environment's Blob Storage, follow the steps below: diff --git a/umbraco-cloud/set-up/config-transforms.md b/umbraco-cloud/set-up/config-transforms.md index 20b639096a5..6167f4266f4 100644 --- a/umbraco-cloud/set-up/config-transforms.md +++ b/umbraco-cloud/set-up/config-transforms.md @@ -26,7 +26,7 @@ If you want to do a transform on your `Web.config` file for the Live environment `Web.Production.config` -The `{environment}` part needs to be replaced with the target environment, for which there are currently 3 possibilities for each project: +The `{environment}` part needs to be replaced with the target environment, for which there are currently three possibilities for each project: 1. `Production` 2. `Staging` @@ -34,7 +34,7 @@ The `{environment}` part needs to be replaced with the target environment, for w This file needs to be created on a local clone of your project, as this will ensure that the file is added to the project repository. -When the file is deployed to the Live environment, the transforms will be applied to the `Web.config` file in the `Root` of your project. In the case that you also have a Development and/or Staging environment, the `Web.Production.config` will **only** transform the `Web.config` on the Live environment. +When the file is deployed to the Live environment, the transforms will be applied to the `Web.config` file in the `Root` of your project. In the case that you have mutliple mainline environments, the `Web.Production.config` will **only** transform the `Web.config` on the Live environment. For each deployment, the Umbraco Cloud engine searches for all of the `.{environment}.config` files in your site and apply the transforms. @@ -60,7 +60,7 @@ Using the tool will let you test whether the transform file transforms your conf ## Examples -Rewrite rules are often something you only want to apply to your Live environment. To avoid the rewrites being applied to your Development and/or Staging environments, you can create a transform file to apply the rewrite rules to your Live environment only. +Rewrite rules are often something you only want to apply to your Live environment. To avoid the rewrites being applied to other mainline environments, create a transform file to apply the rewrite rules only to the Live environment. Here is an example of how that config transform would look: diff --git a/umbraco-cloud/set-up/going-live.md b/umbraco-cloud/set-up/going-live.md index 27e8cea84aa..befd6f36ce3 100644 --- a/umbraco-cloud/set-up/going-live.md +++ b/umbraco-cloud/set-up/going-live.md @@ -20,7 +20,7 @@ Before adding a hostname, you need to update your DNS host domain registrar DNS ## [Deploy to Live](../deployment/cloud-to-cloud.md) -The last step before your website goes live and is accessible to the public is to deploy it to the Live environment. When everything has been tested in your development environment or locally, you are ready to deploy the site to your live environment and make it public. +The last step before your website goes live and is accessible to the public is to deploy it to the Live environment. When everything has been tested in the left-most mainline environment or locally, you are ready to deploy the site to your live environment and make it public. {% hint style="info" %} If you would like to keep track of what goes on with your website after it has gone live, you can set up a [Deployment Webhook](../deployment/deployment-webhook.md). This is a great way to keep an eye on your project and it works great with [Slack](https://slack.com/). diff --git a/umbraco-cloud/set-up/images/create-environment.png b/umbraco-cloud/set-up/images/create-environment.png new file mode 100644 index 00000000000..c4369d7449a Binary files /dev/null and b/umbraco-cloud/set-up/images/create-environment.png differ diff --git a/umbraco-cloud/set-up/images/delete-environment.png b/umbraco-cloud/set-up/images/delete-environment.png new file mode 100644 index 00000000000..f450818b40e Binary files /dev/null and b/umbraco-cloud/set-up/images/delete-environment.png differ diff --git a/umbraco-cloud/set-up/images/environments-overview-new.png b/umbraco-cloud/set-up/images/environments-overview-new.png new file mode 100644 index 00000000000..ffcdea80292 Binary files /dev/null and b/umbraco-cloud/set-up/images/environments-overview-new.png differ diff --git a/umbraco-cloud/set-up/manage-environments.md b/umbraco-cloud/set-up/manage-environments.md index d892f4a9bd8..125857a7c54 100644 --- a/umbraco-cloud/set-up/manage-environments.md +++ b/umbraco-cloud/set-up/manage-environments.md @@ -1,35 +1,54 @@ # Manage Environments -When working with an Umbraco Cloud project, you can add or remove extra environments depending on the plan you are in: +The number of environments available on your project is dependent on which plan you are on: -* For the Starter plan, you can add a Development environment for an additional price per month. -* For the Standard plan, you get the Development environment for free and can add a Staging environment for an additional price per month. -* For the Professional plan, you get the Development and Staging environment for free. Additionally, you can add and remove environments whenever you like without any additional cost. +
PlanEnvironmentsFlexible EnvironmentsEnvironment Combinations Examples
Starter2falseQA + Production
Standard3trueFlexible + QA + Production
Development + QA + Production
Professional4trueFlexible + Development + QA + Production
-[Learn more about the additional prices on Umbraco Cloud](https://umbraco.com/cloud-pricing/). +[Learn more about Umbraco Cloud Pricing](https://umbraco.com/cloud-pricing/). -{% embed url="https://www.youtube.com/watch?v=avzRNFR-FSY" %} -Adding an additional environment to a Cloud project -{% endembed %} +## Configuring Environments + +Clicking Configure environments from the project overview gives you access to environment management options. From here, you can: + +- Rename an existing environment. +- Create a new environment. +- Delete an environment you no longer need. + +These options help keep your deployment pipeline organized and aligned with your team's workflow. ## Adding or Removing Environments -**Important:** _Before_ adding an environment, you should consider if you have any changes locally that are not on Live yet. If you do, you should make sure to push it as adding another environment will also push it into the deployment chain. +Most Umbraco Cloud plans give you the flexibility to work with multiple environments. You can decide how many to add and how to organize them as flexible or mainline environments. For more information on environment types, see the [Environments](../getting-started/environments.md) article. + +The following sections provide guidance on managing your Cloud environments. + +### Adding an Environment + +Before adding an environment, ensure there are no local changes that haven’t been pushed to Live. Adding an environment will push all changes in the current deployment chain. + +To add an environment: + +1. Click **Configure environments**. + +![Adding an environment](images/environments-overview-new.png) + +2. Click **Create environment**. -**Important:** _After_ adding a Development environment, you need to do a fresh clone of the site. The local version you have will be set up to push directly to Live, a fresh clone will push to Development. +![Create environment](images/create-environment.png) -You can add environments from your project overview here: +3. Choose an **Environment name**. +4. Click **Confirm**. -
Adding environments

Adding environments

+After adding a new left-most mainline environment or a flexible environment, you need to clone this environment instead. The current local clone will be set up to push to Live, while the fresh clone will push to the new environment. -To remove an environment, go to the environment you want to delete click on the three dots, and click delete: +### Removing an Environment -
+To remove an environment: -{% hint style="info" %} -There is a specific order that the environments are being added. You will need to have a Development environment before you can have a Staging environment. -{% endhint %} +1. Navigate to the environment you want to delete. +2. Click on the three dots. +3. Click **Delete**. -Suppose you have both a Development and a Staging environment and need to remove the Development environment. In that case, you will first need to remove the Staging environment before you can remove the Development environment. +![Deleting an environment](images/delete-environment.png) -Once you have added or removed an environment, it will take a couple of minutes for Cloud to set it all up, and then you will be ready to use it. +It may take a few minutes for Cloud to set up the changes after adding or removing an environment. diff --git a/umbraco-cloud/set-up/media.md b/umbraco-cloud/set-up/media.md index 95594acd5fd..458b72651cb 100644 --- a/umbraco-cloud/set-up/media.md +++ b/umbraco-cloud/set-up/media.md @@ -15,7 +15,7 @@ To access the media files on your Umbraco Cloud project you can either: ## About Azure Blob Storage -Azure Blob Storage is an external storage system, that the Umbraco Cloud service uses to store all media files on Umbraco Cloud projects. To learn how you can connect to your Blob Storages, read the [Azure Blob Storage](azure-blob-storage/) article. +Azure Blob Storage is an external storage system, that the Umbraco Cloud service uses to store all media files on Umbraco Cloud projects. To learn how you can connect to your Blob Storages, read the [Azure Blob Storage](azure-blob-storage/) article. ## Working with media locally @@ -31,7 +31,7 @@ Each environment on your Umbraco Cloud project has a separate Azure Blob Storage When you deploy between two environments on your Umbraco Cloud project the media files will be copied from one storage to the other, depending on which environment is being transferred to and from. -As an example, imagine that you are transferring new content changes from your Development environment to your Live environment. When you initiate the transfer, all media files from the Azure Blog Storage container connected to your Development environment will be copied and pasted into the container connected to your Live environment. Once all content changes have also been transferred, and the transfer is complete, your Media libraries on the two environments will now be in sync. +As an example, imagine that you are transferring new content changes from your left-most mainline environment to your Live environment. When you initiate the transfer, all media files from the Azure Blob Storage container connected to your left-most mainline environment will be copied and pasted into the container connected to your Live environment. Once all content changes have also been transferred, and the transfer is complete, your Media libraries on the two environments will now be in sync. ## Media Folder diff --git a/umbraco-cloud/set-up/project-settings/README.md b/umbraco-cloud/set-up/project-settings/README.md index 771c1627f7e..5787e193b1d 100644 --- a/umbraco-cloud/set-up/project-settings/README.md +++ b/umbraco-cloud/set-up/project-settings/README.md @@ -14,7 +14,7 @@ The Environments section provides an overview of your project’s environments. * Open Kudu, and * Clone down the environment locally. -![Environments Overview](../images/environments-new.png) +![Environments Overview](../../.gitbook/assets/environments-overview-new.png) #### Environment error log diff --git a/umbraco-cloud/set-up/project-settings/project-history.md b/umbraco-cloud/set-up/project-settings/project-history.md index 0a83fcb3e38..81f96f40c2f 100644 --- a/umbraco-cloud/set-up/project-settings/project-history.md +++ b/umbraco-cloud/set-up/project-settings/project-history.md @@ -27,12 +27,12 @@ For each activity you can see the following information: * When the activity ended * The status of the activity -To get a detailed view of each history type on your project, click the info icon on the far right of the history activity. +To get a detailed view of each history type on your project, click the info icon on the far right of the history activity. If you click on the info icon for an automatic update, you will be redirected to an Upgrade Details page. On this page, you can see details about how the upgrade went.

Upgrade Details

-For activities like adding and removing environments, clicking on the info icon will show details of how the process went when adding/ removing the environment. +For activities like adding and removing environments, clicking on the info icon will show details of how the process went when adding/removing the environment.

Adding environment details

diff --git a/umbraco-cloud/set-up/project-settings/secrets-management.md b/umbraco-cloud/set-up/project-settings/secrets-management.md index 43dd4308ed8..e4b0121c499 100644 --- a/umbraco-cloud/set-up/project-settings/secrets-management.md +++ b/umbraco-cloud/set-up/project-settings/secrets-management.md @@ -7,11 +7,11 @@ description: >- # Secrets Management -There are two ways to add secrets to your Cloud project, as an **Environment Secrets** or as a **Shared Secrets**. +There are two ways to add secrets to your Cloud project, as an Environment Secrets or as a Shared Secrets. - **Environment Secrets** are intended to be utilized exclusively within a particular environment during the runtime of your Umbraco solution. +Environment Secrets are intended to be utilized exclusively within a particular environment during the runtime of your Umbraco solution. -**Shared Secrets** are utilized across all environments and will be seamlessly integrated into any new environment you create. Shared Secrets are particularly well-suited for safeguarding credentials necessary for project development, such as access to private NuGet feeds. +Shared Secrets are utilized across all environments and will be seamlessly integrated into any new environment you create. Shared Secrets are particularly well-suited for safeguarding credentials necessary for project development, such as access to private NuGet feeds. {% hint style="warning" %} Utilizing environment-specific secrets for private NuGet feeds will result in the unsuccessful creation of new environments due to the unknown status of the secret. In such instances, **Shared Secrets** should be used. @@ -38,7 +38,7 @@ When adding a secret to your environment it will restart. To add a secret to your environment follow these steps: 1. Go to your Umbraco Cloud project -2. Go to the settings section and go to Secret Management +2. Go to the Settings section and go to Secret Management 3. Choose either shared or environment secrets 4. Choose the environment to add the secret and click Add secret 5. Add the Key and the Value in the fields and click Add secret @@ -139,7 +139,7 @@ The list consists of: * `SERVICEBUSCONNSTR_` * `EVENTHUBCONNSTR_` * `DOCDBCONNSTR_` -* `REDISCACHECONNSTR_` +* `REDISCACHECONNSTR_` * `FILESHARESTORAGE_` {% hint style="info" %} @@ -159,7 +159,6 @@ The following prefixes are allowed for Secrets on Umbraco Cloud: * `UMBRACO__AUTHORIZEDSERVICES__` * `UMBRACO__COMMERCE__` - It is also possible to use Secrets to save API keys, Passwords, and ReChaptcha for all our Umbraco products on Umbraco Cloud. Do you have an existing or new secret that you want to add to a key vault that conflicts with the name restrictions? diff --git a/umbraco-cloud/set-up/project-settings/team-members/README.md b/umbraco-cloud/set-up/project-settings/team-members/README.md index 1dad41dd649..88fbdd66d31 100644 --- a/umbraco-cloud/set-up/project-settings/team-members/README.md +++ b/umbraco-cloud/set-up/project-settings/team-members/README.md @@ -12,7 +12,7 @@ When adding a user, the default permission is _Read_ for each environment. You c ## Team Member User Permissions -User Permissions for each environment can be set in the **Edit Team** page available from the **Settings** dropdown. User Permissions can be set per environment. For example, a user can have Write access on the Development environment and Read access on the Live environment. +User Permissions for each environment can be set in the **Edit Team** page available from the **Settings** dropdown. User Permissions can be set per environment. For example, a user can have Write access on the left-most mainline environment and Read access on the Live environment.
diff --git a/umbraco-cloud/set-up/project-settings/umbraco-cicd/KnownLimitationsAndConsiderations.md b/umbraco-cloud/set-up/project-settings/umbraco-cicd/KnownLimitationsAndConsiderations.md index 1a274e7b2fd..e452701d7ee 100644 --- a/umbraco-cloud/set-up/project-settings/umbraco-cicd/KnownLimitationsAndConsiderations.md +++ b/umbraco-cloud/set-up/project-settings/umbraco-cicd/KnownLimitationsAndConsiderations.md @@ -10,7 +10,7 @@ As we continue to gather insights from our users, there are some known limitatio **Workflow considerations** -* To ensure smooth execution of the CI/CD Flow, it is recommended to make schema changes in the [leftmost environment](../../../deployment/README.md). Ideally, this means the local development environment. Schema changes include changes made to Document Types, Data Types, Templates, and the like. The intention behind this principle is to prevent conflicts that could potentially arise due to simultaneous modifications made in different environments. +* To ensure smooth execution of the CI/CD Flow, it is recommended to make schema changes in the [left-most mainline environment](../../../deployment/). For example, the local development environment. Schema changes include changes made to Document Types, Data Types, Templates, and the like. The intention behind this principle is to prevent conflicts that could potentially arise due to simultaneous modifications made in different environments. **Additional Build Step** @@ -33,4 +33,3 @@ As we continue to gather insights from our users, there are some known limitatio * **Casing Conflicts**: Be cautious of casing issues, such as having a README.md file created by Azure DevOps and a `Readme.md` file from the default Umbraco Cloud, as this can cause conflicts in the cloud Git repository. * **Documentation Alignment**: We are in the process of updating our documentation to align with standard Umbraco guidelines. * **Developer Experience**: Plans are underway to create Umbraco-specific Azure DevOps tasks and GitHub Actions to enhance the developer experience. - diff --git a/umbraco-cloud/set-up/project-settings/umbraco-cicd/README.md b/umbraco-cloud/set-up/project-settings/umbraco-cicd/README.md index 65134f86700..3c0865072a0 100644 --- a/umbraco-cloud/set-up/project-settings/umbraco-cicd/README.md +++ b/umbraco-cloud/set-up/project-settings/umbraco-cicd/README.md @@ -34,7 +34,7 @@ The CI/CD process for Umbraco projects involves some key steps, from code develo 2. **Customer code repository**: Changes are committed and pushed to a version control system like Git in the customer's own repository. 3. **Customer pipeline**: The code is compiled and built. Tests can be run automatically in the associated pipeline to ensure code quality. Finally, the code is packaged into a zip file and prepared for deployment. 4. **Umbraco Cloud API**: The customer pipeline uploads the source packed as a zip file to Umbraco Cloud API. -5. **Umbraco cloud repository**: The deployments start which triggers the queueing of the build in Umbraco services. It then pushed the Umbraco Cloud repository to the left-most environment. And if a live environment, the website has been updated. +5. **Umbraco cloud repository**: The deployments start which triggers the queueing of the build in Umbraco services. It then pushed the Umbraco Cloud repository to the left-most mainline environment. And if a live environment, the website has been updated. ![Basic overview](../../images/NewBasicFlow.png) @@ -44,7 +44,7 @@ In a bit more detail the flow will look like this from a pipeline perspective. ## Next Steps: Dive into the Documentation -To ensure you make the most of Umbraco CI/CD Flow, we suggest exploring the documentation further. Familiarizing yourself with the fundamentals is a good starting point, but delving deeper will enable you to fully harness its capabilities. +To ensure you make the most of Umbraco CI/CD Flow, we suggest exploring the documentation further. Familiarizing yourself with the fundamentals is a good starting point, but delving deeper will enable you to fully harness its capabilities. Here are three essential pages to get you started: diff --git a/umbraco-cloud/set-up/project-settings/umbraco-cicd/Troubleshooting.md b/umbraco-cloud/set-up/project-settings/umbraco-cicd/Troubleshooting.md index 30bfc34288c..788792b4459 100644 --- a/umbraco-cloud/set-up/project-settings/umbraco-cicd/Troubleshooting.md +++ b/umbraco-cloud/set-up/project-settings/umbraco-cicd/Troubleshooting.md @@ -12,9 +12,9 @@ To resolve this issue, remove the `RestorePackagesWithLockFile` to allow the dep ## cloud-sync -### The projects left-most environment has changed +### The projects left-most mainline environment has changed -The mechanism to determine changes since the last deployment is not able to do so when the left-most environment has changed. This happens when you either add or remove the development environment. The [get diff endpoint](UmbracoCloudApi.md#get-deployment-diff) responds with status 409 and the following json payload: +The mechanism to determine changes since the last deployment is not able to do so when the left-most mainline environment has changed. This happens when you either add or remove a mainline environment. The [get diff endpoint](UmbracoCloudApi.md#get-deployment-diff) responds with status 409 and the following json payload: ```json { @@ -26,14 +26,14 @@ The mechanism to determine changes since the last deployment is not able to do s } ``` -You will need to _manually_ make sure that all latest changes on your left-most environment in cloud is also present in your local copy. +You will need to _manually_ make sure that all latest changes on your left-most mainline environment in cloud is also present in your local copy. Once this is done you can run a new deployment, where you skip the cloud-sync step. * [Skip cloud-sync in GitHub](Troubleshooting.md#skip-cloud-sync-in-github) * [Skip cloud-sync in Azure DevOps](Troubleshooting.md#skip-cloud-sync-in-azure-devops) -If you experience problems with your development environment not properly booting up after deployment, [read the Unable to determine environment by its {environment-id} guide](Troubleshooting.md#unable-to-determine-environment-by-its-environment-id). +If you experience problems with your environment not properly booting up after deployment, [read the Unable to determine environment by its {environment-id} guide](Troubleshooting.md#unable-to-determine-environment-by-its-environment-id). ### “Apply Remote Changes” step is failing @@ -159,7 +159,7 @@ In order to fix this issue, you need to use [KUDU](../../power-tools/) to remove 1. Access KUDU on the "left-most" environment * If you only have one environment you want the live environment -* If you have more than one environment, you want the development environment +* If you have more than one environment, you want the left-most mainline environment 3. Navigate to `site` > `locks` folder In there, there should be a file named `updating` 4. Remove the `updating` file. @@ -170,13 +170,13 @@ Once the marker file is removed, run your pipeline again. ### Unable to determine environment by its {environment-id} -This happens when you use the CI/CD feature of Umbraco Cloud to deploy changes to your live environment, and later add a development environment. Your development environment will fail to boot up and will show the following error message: +This happens when you use the CI/CD feature of Umbraco Cloud to deploy changes to your live environment, and later add a new Cloud environment. Your environment will fail to boot up and will show the following error message: ``` “System.InvalidOperationException: Unable to determine environment by its {environment-id}” ``` -This issue arises because the development environment is missing in the local umbraco-cloud.json file. To resolve this issue, follow these steps: +This issue arises because the environment is missing in the local umbraco-cloud.json file. To resolve this issue, follow these steps: 1. Navigate to Kudu in your Live environment 2. Select “Debug console” and choose “CMD”. @@ -184,4 +184,4 @@ This issue arises because the development environment is missing in the local um 4. Click ‘edit’ on the file and copy all its content. This content is consistent across environments, so it’s safe to do so. 5. Paste the copied content into the umbraco-cloud.json file in your local project and push the changes. -After completing these steps, your development environment should be correctly registered across all environments, allowing you to continue your work without any issues. +After completing these steps, your left-most mainline environment should be correctly registered across all environments, allowing you to continue your work without any issues. diff --git a/umbraco-cloud/set-up/project-settings/umbraco-cicd/UmbracoCloudApi.md b/umbraco-cloud/set-up/project-settings/umbraco-cicd/UmbracoCloudApi.md index e769ab855ed..e26ba5f70a5 100644 --- a/umbraco-cloud/set-up/project-settings/umbraco-cicd/UmbracoCloudApi.md +++ b/umbraco-cloud/set-up/project-settings/umbraco-cicd/UmbracoCloudApi.md @@ -337,10 +337,6 @@ fi The API response will vary based on whether or not there are changes to report. If no changes are detected, you'll receive an HTTP 204 No Content status. On the other hand, if there are changes, the API will return an HTTP 200 OK status along with a git-patch file as the content. This git-patch file can then be applied to your local repository to sync it with the changes. -### Promote Deployment - -Currently, the feature to transition from a development environment to staging or live, and from staging to live, is pending implementation. In the meantime, you can manage these transitions manually through the [Umbraco Cloud Portal](https://www.s1.umbraco.io/projects) \[link to relevant page in docs.umbraco.com, e.g. the section “Utilizing the Pipeline” of the new page “How To Configure A Sample CI|CD Pipeline”].. - ### Possible errors When interacting with the Umbraco Cloud API, you may encounter various HTTP status codes that indicate the success or failure of your API request. Below is a table summarizing the possible status codes, their corresponding errors, and basic root causes to guide your troubleshooting: diff --git a/umbraco-cloud/set-up/ready-to-set-up-your-project.md b/umbraco-cloud/set-up/ready-to-set-up-your-project.md index 990ce2539ff..54a16ac44be 100644 --- a/umbraco-cloud/set-up/ready-to-set-up-your-project.md +++ b/umbraco-cloud/set-up/ready-to-set-up-your-project.md @@ -6,7 +6,7 @@ description: Follow these guides to get your project configured the way you need This section will walk you through everything you need to configure your project, from cloning it locally to going live. Whether you're setting up environments, configuring security, or managing integrations, you'll find all the essential guides here. -
Working with a Local CloneExplore how to clone your project, make changes locally, and then push the updates to Umbraco Cloudworking-locally.mdDocumentations Icons_Umbraco_CMS_Tutorials_MultiSite_Setup.png
Manage EnvironmentsLearn how to create, manage, and deploy changes across Development, Staging, and Production environments.manage-environments.mdDocumentations Icons_Umbraco_CMS_Tutorials_Multilingual_Website.png
Project SettingsFine-tune your project settings, including hostnames, database configurations, and general project management options.project-settingsDocumentations Icons_Umbraco_CMS_Implementation_Routing.png
Going LiveWhen your project is ready, follow these steps to ensure a smooth launch.going-live.mdDocumentations Icons_Umbraco_CMS_Fundamentals_Backoffice.png
Azure Blob StorageNeed scalable media storage? Learn how to integrate Azure Blob Storage with your Umbraco Cloud project for better performance and scalability.azure-blob-storageDocumentations Icons_Umbraco_CMS_Fundamentals_Data.png
+
Working with a Local CloneExplore how to clone your project, make changes locally, and then push the updates to Umbraco Cloudworking-locally.mdDocumentations Icons_Umbraco_CMS_Tutorials_MultiSite_Setup.png
Manage EnvironmentsLearn how to create and manage environments.manage-environments.mdDocumentations Icons_Umbraco_CMS_Tutorials_Multilingual_Website.png
Project SettingsFine-tune your project settings, including hostnames, database configurations, and general project management options.project-settingsDocumentations Icons_Umbraco_CMS_Implementation_Routing.png
Going LiveWhen your project is ready, follow these steps to ensure a smooth launch.going-live.mdDocumentations Icons_Umbraco_CMS_Fundamentals_Backoffice.png
Azure Blob StorageNeed scalable media storage? Learn how to integrate Azure Blob Storage with your Umbraco Cloud project for better performance and scalability.azure-blob-storageDocumentations Icons_Umbraco_CMS_Fundamentals_Data.png
## Also in this section diff --git a/umbraco-cloud/troubleshooting/deployments/README.md b/umbraco-cloud/troubleshooting/deployments/README.md index 7c6fcaf2d56..6eff88d96df 100644 --- a/umbraco-cloud/troubleshooting/deployments/README.md +++ b/umbraco-cloud/troubleshooting/deployments/README.md @@ -1,26 +1,26 @@ # Troubleshooting deployments -Issues with deployments on Umbraco Cloud often come down to a misunderstanding on how to work with Umbraco Cloud. It is important to always work left to right as mentioned in the [Deployment section](../../deployment/README.md). +Issues with deployments on Umbraco Cloud often come down to a misunderstanding of how to work with Umbraco Cloud. It is important to always work left to right, as mentioned in the [Deployment section](../../deployment/). There are two ways to deploy on Umbraco Cloud, a deployment that transfers content and media: -1. A Content [Transfer](../../deployment/content-transfer.md) / [Restore](../../deployment/restoring-content/) -2. A [Deployment](../../deployment/cloud-to-cloud.md) that transfers structure files (doc types, data types, templates, dll's, etc.) +1. A Content [Transfer](../../deployment/content-transfer.md) / [Restore](../../deployment/restoring-content/). +2. A [Deployment](../../deployment/cloud-to-cloud.md) that transfers structure files (doc types, data types, templates, dll's, etc.). -There are some common errors associated with both of these. Most of the time it is caused by conflicting [UDA files](../../set-up/power-tools/generating-uda-files.md#what-are-uda-files) between the two environments you are deploying between. +There are some common errors associated with both of these. Most of the time, it is caused by conflicting [UDA files](../../set-up/power-tools/generating-uda-files.md#what-are-uda-files) between the two environments you are deploying between. The most common [Deployment](../../deployment/cloud-to-cloud.md) issues are listed below with guides on how to fix them: -* [Collision Errors](structure-error.md) -* [Dependency Exception](dependency-exceptions.md) -* [Colliding Data Types](colliding-datatypes.md) -* [Language Mismatch](language-mismatch.md) -* [Deployment Failed (with no error message)](deployment-failed.md) -* [Changes not being applied](changes-not-being-applied.md) +* [Collision Errors](structure-error.md). +* [Dependency Exception](dependency-exceptions.md). +* [Colliding Data Types](colliding-datatypes.md). +* [Language Mismatch](language-mismatch.md). +* [Deployment Failed (with no error message)](deployment-failed.md). +* [Changes not being applied](changes-not-being-applied.md). -The most common Content [Transfer](../../deployment/content-transfer.md) / [Restore](../../deployment/restoring-content/) issues are listed below: +The most common Content [Transfer](../../deployment/content-transfer.md)/[Restore](../../deployment/restoring-content/) issues are listed below: -* [Schema mismatch](schema-mismatches.md) -* [SQL Timeouts](https://docs.umbraco.com/umbraco-deploy/deploy-settings#timeout-settings) -* [Dependency Exception](dependency-exceptions.md) -* [Media path too long](path-too-long-exception.md) +* [Schema mismatch](schema-mismatches.md). +* [SQL Timeouts](https://docs.umbraco.com/umbraco-deploy/deploy-settings#timeout-settings). +* [Dependency Exception](dependency-exceptions.md). +* [Media path too long](path-too-long-exception.md). diff --git a/umbraco-cloud/troubleshooting/deployments/colliding-datatypes.md b/umbraco-cloud/troubleshooting/deployments/colliding-datatypes.md index 90028797b1b..86359fb315a 100644 --- a/umbraco-cloud/troubleshooting/deployments/colliding-datatypes.md +++ b/umbraco-cloud/troubleshooting/deployments/colliding-datatypes.md @@ -8,11 +8,11 @@ When creating a new environment on your Umbraco Cloud project, you might encount * Multiple Media Picker (using Media Picker) * Related Links -Since these 5 data types are part of the Umbraco CMS, these will be created by default on each new environment on Umbraco Cloud. If metadata files/structure files for these data types have been generated on your Live environment, you might run into extraction errors on your newly created Development or Staging environment. New environments will be exact clones of the Live environment, thus containing all structure and metadata files from that environment. +Since these 5 data types are part of the Umbraco CMS, these will be created by default on each new environment on Umbraco Cloud. If metadata files/structure files for these data types have been generated on your Live environment, you might run into extraction errors on your newly created left-most environment. New environments will be exact clones of the Live environment, thus containing all structure and metadata files from that environment. ## How do I know I have this issue? -The issue will present itself as an extraction error on your Development or Staging environment once you've created them. +The issue will present itself as an extraction error on your mainline environment once you've created them.
@@ -22,20 +22,20 @@ Open the error message by clicking **More info**. In the case illustrated above, there are four data types and each has two `UDA files`. -What this means is that a file has been generated for each data type on both the Live and the Development environment. The Umbraco Deploy engine needs to create one instance of each data type but is currently not able to do so, since it doesn't know which files to build the data types based on. +What this means is that a file has been generated for each data type on both the Live and the left-most environment. The Umbraco Deploy engine needs to create one instance of each data type but is currently not able to do so, since it doesn't know which files to build the data types based on. See the steps below on how to resolve the issue. ## How to resolve the issue -1. Access the backoffice of the affected environment (Development or Staging) -2. Find the **Data Types** folder in the Developer section -3. Delete **only** the data types mentioned in the error message +1. Access the backoffice of the affected left-most environment. +2. Find the **Data Types** folder in the Developer section. +3. Delete **only** the data types mentioned in the error message. * In the case above, I would need to delete _Member Picker_, _Multiple Media Picker_, _Related Links_, and _Content Picker_ -4. [Access Kudu](../../set-up/power-tools/) for the affected environment -5. Follow the [Kudu Documentation](../../set-up/power-tools/manual-extractions.md) to run an extraction on the environment -6. When you get a `deploy-complete` marker, the issue has been resolved! +4. [Access Kudu](../../set-up/power-tools/) for the affected environment. +5. Follow the [Kudu Documentation](../../set-up/power-tools/manual-extractions.md) to run an extraction on the environment. +6. When you get a `deploy-complete` marker, the issue has been resolved. -When you've followed these steps, go through your Development / Staging environment and make sure everything has been created as expected. +When you've followed these steps, go through your left-most environment and make sure everything has been created as expected. -The final step you need to take before your Development / Staging environment is completely in sync with your Live environment is to [restore the content](../../deployment/restoring-content/). +The final step you need to take before your left-most environment is completely in sync with your Live environment is to [restore the content](../../deployment/restoring-content/). diff --git a/umbraco-cloud/troubleshooting/deployments/images/pulling-failed.png b/umbraco-cloud/troubleshooting/deployments/images/pulling-failed.png new file mode 100644 index 00000000000..7d6316214c1 Binary files /dev/null and b/umbraco-cloud/troubleshooting/deployments/images/pulling-failed.png differ diff --git a/umbraco-cloud/troubleshooting/deployments/merge-conflicts-on-flexible-environments.md b/umbraco-cloud/troubleshooting/deployments/merge-conflicts-on-flexible-environments.md new file mode 100644 index 00000000000..4137ebaed54 --- /dev/null +++ b/umbraco-cloud/troubleshooting/deployments/merge-conflicts-on-flexible-environments.md @@ -0,0 +1,72 @@ +--- +description: Merge conflicts can happen when the same schema has been modified in both the flexible environment and the mainline environment it's connected to. +--- + +# Merge Conflicts on Flexible Environments + +A merge conflict happens when a file or item contains conflicting changes in more than one environment during deployment. + +This guide explains how to resolve these merge conflicts and how to avoid them. + +## Resolving a Merge Conflict in a Flexible Environment + +The image below shows a merge conflict when pulling from the mainline environment to a flexible environment. + +![Pulling changes from the mainline environment failed](images/pulling-failed.png) + +To start debugging the merge conflict, a log file containing a list of conflicting files is provided. It's a `.txt` file that can be downloaded and viewed. + +### Preparations + +Before you start resolving the merge conflict, ensure you have the following things ready: + +* The log file containing a list of the conflicting files. +* The clone link for the flexible (source) environment. +* The clone link for the mainline (target) environment that flexible environment is connected to. +* An editor that provides Git tools for handling merge conflicts (like Visual Studio Code). + +### Steps + +1. Download the log file provided from the failed pull (see image above). +2. Clone the flexible environment [to your local machine](../../set-up/working-locally.md). +3. Use the mainline environment clone link to add a new `git remote`: + +```git +git remote add [mainline environment name] [mainline environment clone link] +``` + +4. Fetch the `master` from the added remote: + +```git +git fetch [mainline environment name] master +``` + +5. Merge the `master` into the local clone. + +``` +git merge [mainline environment name]/master +``` + +6. Open the cloned files in your favorite editor that also provide Git tools. +7. Go through the conflicting files one by one. +8. Stage and commit the resolved conflicts. +9. Push the change back to the flexible environment. + +Once the push to the flexible environment is complete, verify that the merge was successful. + +The final thing needed to be done is to complete the deployment to the mainline environment. + +{% hint style="info" %} +In case you do not see your changes reflected on the flexible environment, [update the schema manually](../../deployment/deploy-dashboard.md#update-umbraco-schema-from-data-files) from the Umbraco backoffice. This will give you an idea of what is wrong enabling you to resolve it. +{% endhint %} + +## Avoiding Merge Conflicts in a Flexible Environment + +A flexible environment is attached to a single mainline environment. Changes cannot be deployed from the flexible to the mainline environment, before changes from the mainline are pulled into the flexible environment. + +Learn more about how flexible environments work in the [Flexible Environments](../../getting-started/flexible-environments.md) article. + +Merge conflicts can be avoided by following these guidelines on the flexible environment: + +* Only work on schema specific to a single feature. +* Do not make changes to schema regularly changed in the mainline environment. diff --git a/umbraco-cloud/troubleshooting/deployments/schema-mismatches.md b/umbraco-cloud/troubleshooting/deployments/schema-mismatches.md index dd1efffae86..9ef73fa24d2 100644 --- a/umbraco-cloud/troubleshooting/deployments/schema-mismatches.md +++ b/umbraco-cloud/troubleshooting/deployments/schema-mismatches.md @@ -1,6 +1,6 @@ # Schema Mismatches -When transferring or restoring content between two Umbraco Cloud environments, you might run into **Schema mismatch** errors. These usually occur when the schema isn't in sync between the *source environment* and the *target environment*. Schema refers to Document Types, Media Types, Data Types, Templates, and Dictionary items) +When transferring or restoring content between two Umbraco Cloud environments, you might run into Schema mismatch errors. These usually occur when the schema isn't in sync between the source environment and the target environment. Schema refers to Document Types, Media Types, Data Types, Templates, and Dictionary items. In this article, you can learn how to resolve schema mismatch issues and how you can avoid them in the future. @@ -22,8 +22,8 @@ To resolve this error, check for pending deployments on the source environments. If there are no pending deployments in your source environment, there are two ways to go about resolving the schema mismatch: -1. Make a minor change to the schema with mismatches in the source environment (in the example above it would be the **Contact Us** document type). -2. Deploy the change to the next environment - * This will update your schema in the target environment and ensure it is in sync with the source environment +1. Make a minor change to the schema with mismatches in the source environment (in the example above, it would be the **Contact Us** document type). +2. Deploy the change to the next environment. + * This will update your schema in the target environment and ensure it is in sync with the source environment. If the mismatches involve differences in the `aliases` or `names`, changing these manually on the target environment will enable you to transfer your content. diff --git a/umbraco-cloud/troubleshooting/deployments/structure-error.md b/umbraco-cloud/troubleshooting/deployments/structure-error.md index 4f77237355c..24b6b7dfbfc 100644 --- a/umbraco-cloud/troubleshooting/deployments/structure-error.md +++ b/umbraco-cloud/troubleshooting/deployments/structure-error.md @@ -14,15 +14,19 @@ Collisions for unique identifier "home": UdaFile: ~/deploy/revision/document-type__f848c577f02b4ee5aea84f87458072a4.uda ``` -The error means that two (or more) `.uda` files have been created for the same entity. The `.uda` files contain schema data for each of your entities e.g Document Types, Templates, Macros, Dictionary Items, Data types, etc (for a full list of these entities see [What are UDA files?](../../set-up/power-tools/generating-uda-files.md#what-are-uda-files)). +The error means that two (or more) `.uda` files have been created for the same entity. The `.uda` files contain schema data for each of your entities. For example, Document Types, Templates, Macros, Dictionary Items, Data types, and so on. For a full list of these entities, see [What are UDA files?](../../set-up/power-tools/generating-uda-files.md#what-are-uda-files). In this example, there are two `.uda` files that share the same alias which leads to a conflict: it is impossible for Deploy to know which of the files to use, so it gives up and sends an error back. {% hint style="info" %} -Does the collision error involve **Dictionary items**? Use this guide instead: [Troubleshooting duplicate dictionary items](duplicate-dictionary-items.md) +If the collision error involves Dictionary Items, use this guide instead: [Troubleshooting duplicate dictionary items](duplicate-dictionary-items.md) {% endhint %} -You can run into an error like this on all of your Cloud environments. Sometimes you might also run into it, on a local clone of your project. This guide will use an example, where two files are colliding on a Development and a Live environment. +You can run into an error like this on all of your Cloud environments. Sometimes you might also run into it on a local clone of your project. + +This guide uses an example where two files are colliding across two environments: a left-most environment and the Live environment. + +For clarity, the left-most environment will be referred to as the Development environment throughout the guide. ## Table of content @@ -32,7 +36,7 @@ You can run into an error like this on all of your Cloud environments. Sometimes * [Getting your environments in sync](structure-error.md#getting-your-environments-in-sync) {% hint style="info" %} -When you have two or more Cloud environments, we recommend that you never create or make schema changes directly on the Live or Staging environments. You should work with schema only in your Development environment or even better, your local clone of the project. +When you have two or more Cloud environments, it is recommended that you only work with schema on local, Development, or flexible environments. {% endhint %} ## Video tutorial @@ -43,7 +47,7 @@ Fixing collision errors tutorial ## Using the error message -In the example above the entity involved is a Document Type with "home" as the alias. There are two colliding files both located in the `/deploy/revision` folder. The files are colliding because they share the same alias but have different GUIDs (also the name of the files). +In the example above, the entity involved is a Document Type with _home_ as the alias. There are two colliding files both located in the `/deploy/revision` folder. The files are colliding because they share the same alias but have different GUIDs (also the name of the files). ## Deciding which file you want to use @@ -67,7 +71,7 @@ For this example, it’s decided that the Document Type currently used on the Li In order to figure out which of the two colliding `.uda` files are the one for the Document Type being used on the Live environment follow these steps: -1. Connect to the database of the Live environment using the [connect to your cloud database locally tutorial](../../databases/cloud-database/#connecting-to-your-cloud-database-locally) +1. Connect to the database of the Live environment using the [connect to your cloud database locally tutorial](../../databases/cloud-database/#connecting-to-your-cloud-database-locally). 2. Run one of the following queries on the database, depending on the type you see the error with * Run the following query, if the error states that the error is a `Collisions for entity type "document-type"`: @@ -111,13 +115,13 @@ You now know which `.uda` file you want. We strongly recommend that you resolve this locally since this will ensure that the changes you make are added to your Git repositories. Otherwise, you may end up having the same problem next time you deploy. {% endhint %} -1. Clone down the Development environment to your local machine -2. Run the project locally and verify that you get the same extraction error as on your Cloud environments (_HINT: look for a `deploy-failed` marker in your local `/deploy` folder_) - * When you run the project, you should see an error message in the browser once the site starts to build +1. Clone down the Development environment to your local machine. +2. Run the project locally and verify that you get the same extraction error as on your Cloud environments (_HINT: look for a `deploy-failed` marker in your local `/deploy` folder_). + * When you run the project, you should see an error message in the browser once the site starts to build. 3. Remove the wrong `.uda` file (It's the one we did not find in the live environment just before) from the `/deploy/revision` folder - you will not be able to see the Document Type in the backoffice because of the failed extraction. 4. Open the Umbraco Backoffice and go to Settings -> Deploy to see the Deploy dashboard. 5. Select `Schema deployment from data files` in the dropdown. -6. You will now see a `deploy-complete` marker in your local `/deploy` folder +6. You will now see a `deploy-complete` marker in your local `/deploy` folder. {% hint style="info" %} **Does the error mention Templates?** You might experience that `.uda` files for a template are colliding. When this is the case, we recommend that you copy the content of the `cshtml` file associated with the template you want to keep on your project - this way you'll have a backup of the code you want to use. @@ -127,12 +131,12 @@ We strongly recommend that you resolve this locally since this will ensure that Before pushing the changes to the Development environment, you need to access the backoffice of the Development environment and remove the Document Type from there. -**Commit** and **push** the changes from your local clone to the Development environment, using your local Git client. +Commit and push the changes from your local clone to the Development environment, using your local Git client. When the push from local to the Development environment has been completed, refresh the Umbraco Cloud portal and you will see that the Development environment is now green, which means that the extraction error has been resolved. -### Does your Development still have the red indicator? +### Does your Development Environment still have the red indicator? -Sometimes you might need to run another schema deployment on your Cloud environment after deploying to turn your environment _green_. To do this, follow the steps described in the [schema deployment guide](../../deployment/deploy-dashboard.md). +Sometimes you might need to run another schema deployment on your Cloud environment after deploying to turn your environment green. To do this, follow the steps described in the [schema deployment guide](../../deployment/deploy-dashboard.md). The final step is to deploy the pending changes from Development to your Live environment, to ensure everything is completely in sync. diff --git a/umbraco-cloud/troubleshooting/log-files.md b/umbraco-cloud/troubleshooting/log-files.md index 656af88879b..fad52247e3f 100644 --- a/umbraco-cloud/troubleshooting/log-files.md +++ b/umbraco-cloud/troubleshooting/log-files.md @@ -22,7 +22,7 @@ Video example. ### On Umbraco Cloud Portal -1. Go to your project and click on the arrow next to the environment name. +1. Go to your project and click on the arrow next to the environment name.
2. Click **Logs** to view the log details. @@ -43,13 +43,13 @@ It is possible that a deployment failed so it is not the active deployment at th ## Environment logs -Whenever you push from local to staging or when you deploy using the Umbraco Cloud portal, you're deploying your site using Git. This works as follows: you commit changes to Git and push them to development, these changes is then stored in the `site > repository` folder. Then the state of the newest commit gets copied into the `wwwroot` folder, which is where your website lives. +Whenever you push between environments or when you deploy using the Umbraco Cloud portal, you're deploying your site using Git. This works as follows: you commit changes to Git and push them to development, these changes is then stored in the `site > repository` folder. Then the state of the newest commit gets copied into the `wwwroot` folder, which is where your website lives. When you're in Kudu, you can go up to the `site` folder and then the `deployments` folder. The `active` file has the identifier of the currently active deployment in it. If you go into the folder that has the same name as that identifier you can see a few files: `log.log`, `manifest` and `status.xml`. * `status.xml` shows you detailed information of which commit was deployed to the `wwwroot` folder * `manifest` is used to track which files are in the currently active deployment so that additions, renames and deletions, can be detected for the next deploy (this is an internal file which you should not touch) -* `log.log` shows you the same output you will have seen when pushing your changes using Git, it will show you what happened during the push and if any errors occurred. This file is especially useful when trying to find errors for deploys using the portal (so from dev > live or from dev > staging > live). Even though the last line may end with "Deployment successful" it is possible that there were errors or suspicious messages before that so make sure to give them a read. +* `log.log` shows you the same output you will have seen when pushing your changes using Git, it will show you what happened during the push and if any errors occurred. This file is especially useful when trying to find errors for deploys using the portal (for example, from dev > live or from dev > staging > live). Even though the last line may end with "Deployment successful" it is possible that there were errors or suspicious messages before that so make sure to give them a read. ## Cleaning up the environment logs viewer