16 prep: deploy

16/umbraco-deploy/.gitbook.yaml

@@ -0,0 +1,8 @@
+root: ./
+
+​structure:
+    readme: README.md
+    summary: SUMMARY.md
+
+redirects:
+

16/umbraco-deploy/README.md

@@ -0,0 +1,29 @@
+---
+description: Documentation on how to work with Umbraco Deploy.
+---
+
+# Umbraco Deploy Documentation
+
+Umbraco Deploy is a deployment tool that helps you with the process of transferring code and data between multiple environments. Deploy can be configured for many different setups and is great for both small setups as well as large and more complex infrastructures.
+
+<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Set up Umbraco Deploy</strong></td><td>Learn how you can set up Umbraco Deploy on new and existing Umbraco projects.</td><td><a href=".gitbook/assets/Documentations Icons_Umbraco_Deploy_Setup.png">Documentations Icons_Umbraco_Deploy_Setup.png</a></td><td><a href="installation/install-configure.md">install-configure.md</a></td></tr><tr><td><strong>Deployment workflow in</strong></td><td>Learn about how the Deployment workflow in Umbraco Deploy work.</td><td><a href=".gitbook/assets/Documentations Icons_Umbraco_Deploy_Deployment_Workflow.png">Documentations Icons_Umbraco_Deploy_Deployment_Workflow.png</a></td><td><a href="deployment-workflow/">deployment-workflow</a></td></tr><tr><td><strong>Upgrading</strong></td><td>Learn how you can upgrade Umbraco Deploy.</td><td><a href=".gitbook/assets/Documentations Icons_Umbraco_Deploy_Upgrading.png">Documentations Icons_Umbraco_Deploy_Upgrading.png</a></td><td><a href="upgrades/">upgrades</a></td></tr></tbody></table>
+
+{% content-ref url="getting-started/deploy-settings.md" %}
+[deploy-settings.md](getting-started/deploy-settings.md)
+{% endcontent-ref %}
+
+{% content-ref url="extending/extending.md" %}
+[extending.md](extending/extending.md)
+{% endcontent-ref %}
+
+{% content-ref url="troubleshooting.md" %}
+[troubleshooting.md](troubleshooting.md)
+{% endcontent-ref %}
+
+Umbraco Deploy is also the engine that runs behind the scenes on [Umbraco Cloud](https://docs.umbraco.com/umbraco-cloud/). Here it takes care of all the deployment processes of both code, schema and content on projects.
+
+With Umbraco Deploy you get to use the Umbraco Cloud Deployment technology outside of Umbraco Cloud to ease deployment between multiple Umbraco environments. This is done by connecting external hosted Umbraco projects with a local instance of your Umbraco website.
+
+In the Umbraco Deploy documentation can read all about how to set up and work with Umbraco Deploy.
+
+You can find articles about how to set up Umbraco Deploy on a new or an existing website, and articles about the deployment workflow.

16/umbraco-deploy/SUMMARY.md

@@ -0,0 +1,44 @@
+# Table of contents
+
+* [Umbraco Deploy Documentation](README.md)
+* [Legacy Documentation](legacy-documentation.md)
+* [Release notes](release-notes.md)
+* [Troubleshooting](troubleshooting.md)
+
+## Installation
+
+* [Installing Umbraco Deploy](installation/install-configure.md)
+* [Licensing](installation/the-licensing-model.md)
+
+## Upgrading
+
+* [Upgrading Umbraco Deploy](upgrades/README.md)
+* [Version Specific Upgrade Details](upgrades/version-specific.md)
+
+## Getting Started
+
+* [Getting started](getting-started/get-started-with-deploy.md)
+* [CI/CD Build and Deployment Pipeline](getting-started/cicd-pipeline/README.md)
+  * [Azure DevOps](getting-started/cicd-pipeline/ci-cd-azure-dev-ops.md)
+  * [GitHub Actions](getting-started/cicd-pipeline/ci-cd-github-actions.md)
+* [Streamlining Local Development](getting-started/streamlining-local-development.md)
+* [Configuration](getting-started/deploy-settings.md)
+
+## Deployment Workflow
+
+* [Deployment](deployment-workflow/README.md)
+* [Transferring Content, Media and Forms](deployment-workflow/content-transfer.md)
+* [Import and Export](deployment-workflow/import-export.md)
+  * [Import and Export with Migrations](deployment-workflow/import-with-migrations.md)
+  * [Import and Export from version 7](deployment-workflow/import-export-v7.md)
+  * [Import on start-up](deployment-workflow/import-on-startup.md)
+* [Deploying Changes](deployment-workflow/deploying-changes.md)
+* [Deploying deletions](deployment-workflow/deploying-deletions.md)
+* [Restoring content](deployment-workflow/restoring-content/README.md)
+  * [Partial Restores](deployment-workflow/restoring-content/partial-restore.md)
+* [Deploy Dashboard](deployment-workflow/deploy-dashboard.md)
+
+## Extending
+
+* [Extend Deploy](extending/extending.md)
+* [Handling Cache Refresher Notifications](extending/handling-cache-refresher-notifications.md)

16/umbraco-deploy/deployment-workflow/README.md

@@ -0,0 +1,76 @@
+---
+description: A description of the proper workflow when working with Umbraco Deploy
+---
+
+# Deployment
+
+Umbraco Deploy uses a deployment model that relies on Git and Umbraco Deploy core technology to move your changes from one environment to another. Umbraco Deploy uses a classic "left to right" deployment model, meaning that changes are first made in the Development or local environment and then deployed to the production environment.
+
+{% hint style="info" %}
+If your project contains a Staging environment, deployments will be made from Development to Staging and then from Staging to Live.
+{% endhint %}
+
+![Left to right model](images/left-to-right.png)
+
+## Deployment Approach
+
+Umbraco Deploy uses a two-part deployment approach where we keep meta data (Document types, templates, etc) and content (Content nodes and Media) as separate parts of a deployment. In order to be able to distinguish between the two types of deployments we use the term _transfer_ for content and media deployments and the term _deploy_ for meta data deployments.
+
+In summary:
+
+1. Meta data such as Document Types, Templates, Forms, Views and config files are stored in a repository and are **deployed** between environments. This can be achieved using a CI/CD deployment pipeline with something like GitHub Actions or Azure DevOps.
+2. Content and Media items are **not** stored in the repository. These need to be **transferred** directly from the Umbraco backoffice using the _"Queue for Transfer"_ option. Once a content editor has all the items needed for a transfer they will use the Deployment Dashboard in the Content section to transfer the items in the queue.
+
+### Deploying meta data
+
+In order to be able to transfer content and media, the source environment and the target environment needs to have the same setup - meaning they need to be completely in sync and have the same file structure. To achieve this you need to deploy your meta data changes to the target environment.
+
+* [Deploying from your local machine to your environments](deploying-changes.md)
+
+### Transfer Content and Media
+
+Moving your content and media between your environments is done through the Umbraco backoffice. You can transfer content from one environment to another, e.g. from local to your development environment. You also have the option to restore content and media to your local or development environment from your production or staging environment.
+
+* [Transfer Content and Media](content-transfer.md)
+* [Restore Content and/or Media](restoring-content/)
+
+{% hint style="info" %}
+Transferring and restoring content and media is the same whether you are working locally and transferring between two environments.
+{% endhint %}
+
+{% embed url="https://www.youtube.com/embed/poRzuBB11pc?rel=0" %}
+Umbraco Deploy - Content transfer and deploy
+{% endembed %}
+
+### Import and Export
+
+Another approach for transferring content and schema between environments is to use import and export. In one environment, you can export selected content, a tree, or the whole workspace to a .zip file. There are options to include related media files, schema and code files such as templates and stylesheets.
+
+That .zip file can then be uploaded into a new environment, where it will be validated and then processed to update Umbraco.
+
+As part of the import process, we provide hooks to allow for migrations of the imported artifacts (like data types) and property data. This should allow you to migrate your Umbraco data from one Umbraco major version to a newer one.
+
+We recommend using the content and media backoffice transfer options for day-to-day editorial activities. Import and export is intended more for larger transfer options, project upgrades, or one-off tasks when setting up new environments.
+
+Read more about the [import and export](import-export.md) feature.
+
+## Deploy Dashboard
+
+In Umbraco Deploy we have included a Deploy Dashboard in the Settings section of the Umbraco backoffice to make it easier to run operations like schema deployment from data files and extract schema to data files.
+
+When running the `extract schema to data files` operation, Umbraco Deploy will run an `echo > deploy-export` in the data folder of your project which is used to generate UDA files based on the schema in your database.
+
+Running the `schema deployment from data files` operation will initiate an extraction on the environment
+
+The extraction will end in one of two possible outcomes:
+
+1. `deploy-complete`: The extraction succeeded and your environment is in good shape!
+2. `deploy-failed`: The extraction failed - open the deploy-failed file, to see the error message.
+
+It is also possible to see which version of Umbraco Deploy you are running, when the last operation was started and the status of the deployment operation.
+
+<figure><img src="../.gitbook/assets/image (15).png" alt="Deploy Dashboard"><figcaption><p>Deploy Dashboard</p></figcaption></figure>
+
+{% embed url="https://www.youtube.com/embed/l5qdTsIddKM?rel=0" %}
+Umbraco Deploy - Content transfer and deploy
+{% endembed %}

16/umbraco-deploy/deployment-workflow/content-transfer.md

@@ -0,0 +1,73 @@
+---
+description: How to restore content in Umbraco Deploy using the deployment dashboard
+---
+
+# Transferring Content, Media and Forms
+
+Once all code and meta data is in sync between your environments, it's time to transfer your content and media. This is done from the Umbraco Backoffice.
+
+Content and media transfers are flexible which means you have complete control over which content nodes and/or media items you want to transfer. You can transfer it all in one go, a few at a time or transfer only a single node.
+
+Transferring content will overwrite any existing nodes on the target environment - content transfers will transfer the items that you select in the "source" environment to the "target" environment exactly the same as it was in the "source". This means that if you have some content on the target environment already, this will be replaced by the new content from the source environment.
+
+**Important**: Content and Media transfers will only work if you've deployed all changes to your meta data before hand. Please refer to our documentation on how to deploy meta data from [Deploying Content](deploying-changes.md).
+
+## Step-by-step
+
+Let’s go through a content transfer step by step. Imagine you’ve finished working on new content for your project locally and you are ready to transfer the changes to your development site.
+
+You want to transfer the whole site. You start from the `Home` node and choose to transfer everything under it:
+
+1. Click on the ellipsis next to the `Home` node in the Content tree.
+2. Choose "Do something else".
+3. There you get the choice of **Queue for transfer**.
+   * If you’re currently editing the Home page you could also use the Actions dropdown to find **Queue for transfer**.
+4. Choose if you want to include all pages under the chosen page or only transfer the chosen node.
+   * If you wish to transfer all your content at once, click **...** next to the Content tree where you will also find **Queue for transfer** - this will queue all your content for transfer.
+5. Select the language versions that you want to queue for transfer. Only languages for which you have permission to access will be selectable.
+6.  Set the publish date and time if you want to change when the transferred content should be published.
+
+    {% hint style="info" %}
+    By default, the content will be transferred in its current published state. So if the content is published in the current environment, the changes will be deployed and the item immediately be published in the destination. If you prefer to schedule the publishing of the changes, you can do so by selecting a publish date.
+    {% endhint %}
+7. Click **Queue** to add the content item to the transfer queue.
+
+<figure><img src="../.gitbook/assets/image.png" alt="Queue for transfer window"><figcaption><p>Queue for transfer window</p></figcaption></figure>
+
+1. Go to the Deployment dashboard by clicking on the Content section header.
+   * You will be able to see which items are currently ready to be transferred - this will include both content and media that you've _queued for transfer_.
+2. Confirm by clicking **Transfer toDevelopment** and monitor the progress of the transfer.
+
+<figure><img src="../.gitbook/assets/image (1).png" alt="Transfer queue"><figcaption><p>Transfer queue</p></figcaption></figure>
+
+If everything went well, you will see the confirmation screen saying that the transfer has succeeded.
+
+### Media items
+
+Media items are transferred the same way as content:
+
+1. In the Media section, Click **...** next to the items you want to transfer and choose **Queue for transfer**.
+   * Or click **...** next to the Media section to transfer all you media at once.
+2. Go to the Deployment dashboard in the Content section to see the items you've queued for transfer and to transfer your items.
+
+### Umbraco Forms
+
+In order for Deploy to handle Forms data as content, you will need to ensure that the `transferFormsAsContent` setting in configuration is set to `true`. See details in the [Deploy Settings for Umbraco 9+](../getting-started/deploy-settings.md) article.
+
+Once the setting have been added to the source and target environment forms can be transferred the same way as content and media:
+
+1. In the Forms section, click **...** next to the items you want to transfer and choose **Queue for transfer**.
+   * Or click **...** next to the Forms section to transfer all your Forms at once.
+2. Go to the Deployment dashboard in the Content section to see the items you've queued for transfer and to transfer your items.
+
+{% hint style="info" %}
+This does not include entries submitted via the forms.
+{% endhint %}
+
+## Schema Mismatches
+
+Sometimes a content transfer might not be possible. For example if you add a new property to the HomePage Document type and you don’t have that property in both environments, you’ll get an error with a hint on how to fix this.
+
+![Schema mismatch](../deployment-workflow/images/schema-mismatch.png)
+
+If you are seeing this type of issue when trying to transfer content, head over to our article about [Schema Mismatch errors](../troubleshooting.md), where you can read about how to resolve the issues.

16/umbraco-deploy/deployment-workflow/deploy-dashboard.md

@@ -0,0 +1,83 @@
+---
+description: >-
+  With the Deploy Dashboard, we have made it possible to get an overview of your
+  Umbraco Deploy installation and perform Deploy operations.
+---
+
+# Deploy Dashboard
+
+In this article, we will show the different sections on the Deploy dashboard and how they can be used.
+
+## Deploy Status
+
+Here, you can check whether the latest deployment was successful or failed. You can also see the version of Umbraco Deploy in use and the timestamp of the last operation.
+
+![Umbraco Deploy status](images/deploy-dashboard.png)
+
+## Deploy Operations
+
+With the Deploy operations, you can run different operations in Umbraco Deploy.
+
+![Deploy operations](images/deploy-operations.png)
+
+Below you can read what each operation will do when run through the dashboard.
+
+### Update Umbraco Schema From Data Files
+
+Running this operation will update the Umbraco Schema based on the information in the `.uda` files on disk.
+
+### Verify and Clean Schema
+
+This operation deletes schema from your current environment if it does not have a matching UDA file. It manually deletes each item in the Schema Comparison overview with an exclamation mark in the 'File Exists' column.
+
+### Export Schema To Data Files
+
+Running this operation will extract the schema from Umbraco and output it to the `.uda` files on disk.
+
+### Clear Cached Signatures
+
+Running this operation will clear the cached artifact signatures from the Umbraco environment. This should not be necessary, however, it may resolve reports of schema mismatches when transferring content that has been aligned.
+
+### Set Cached Signatures
+
+This operation will set the cached artifact signatures for all entities within the Umbraco environment. Use this when signatures have been cleared and you want to ensure they are pre-generated before attempting a potentially longer restore or transfer operation.
+
+## Download Deploy Artifacts
+
+Running this operation will download a zip file with all the Deploy artifacts representing the Umbraco schema in the form of `.uda` files.
+
+This operation is useful if you want to move to another Umbraco instance and migrate the data with you.
+
+<div align="left">
+
+<figure><img src="../.gitbook/assets/image (9).png" alt="Donwload the Deploy artifacts"><figcaption><p>Donwload the Deploy artifacts</p></figcaption></figure>
+
+</div>
+
+## Configuration Details
+
+In the Configuration details, you can see how Umbraco Deploy has been [configured](../getting-started/deploy-settings.md) on your environment. You get an overview of the Setting options, the current value(s), and notes help you understand each of the settings. Updates to the need to be applied in the `appsettings.json` file.
+
+<figure><img src="../.gitbook/assets/image (2) (1).png" alt=""><figcaption><p>Example of Umbraco Deploy configuration.</p></figcaption></figure>
+
+## Schema Comparison
+
+The Schema Comparison table shows the schema information managed by Umbraco Deploy.
+
+You can see a comparison between the information that is held in Umbraco and the information in the `.uda` files on disk.
+
+The table shows:
+
+* The name of the schema
+* The file name
+* Whether the file exists in Umbraco
+* Whether the file exists
+* Whether the file is up-to-date
+
+<figure><img src="../.gitbook/assets/image (5) (1).png" alt=""><figcaption><p>Document type schema comparison</p></figcaption></figure>
+
+You can also view details about a certain element by selecting "View Details".
+
+This will show the difference between entities stored in Umbraco and the `.uda` file stored on disk.
+
+<figure><img src="../.gitbook/assets/image (7) (1).png" alt=""><figcaption><p>Showing how you can compare schema in the deploy dashboard</p></figcaption></figure>