Merge branch 'main' into v9/common-pitfalls

Author: Nikolaj

Add-ons/The-Licensing-model/index-v7.md

@@ -0,0 +1,121 @@
+---
+versionFrom: 7.0.0
+---
+
+# The Licensing Model
+
+Umbraco Forms, Umbraco Deploy and Umbraco Courier are commercial products.
+
+For Umbraco Forms you will have a 14-day free trial to try out the product. After your trial expires, you'll need to have a **valid license** in order to keep using the product on your site.
+
+Umbraco Courier and Umbraco Deploy don't come with a 14-day free trial, which means you will need a **valid license** in order to use the products. You will be able to test both Deploy and Courier on a local setup without a license.
+
+## How does it work?
+
+Licenses for our products are sold per domain and will also work on all subdomains. With every license you will also be able to configure two development / testing domains.
+
+### Example
+
+Let's say that you have a license configured for your domain, `mysite.com`, and you've configured two development domains, `devdomain.com` and `devdomain2.com`.
+
+The license will cover the following domains:
+
+- `localhost`
+- `*.mysite.com`
+- `www.mysite.com`
+- `mysite.com.local`
+- `devdomain.com`
+- `www.devdomain.com`
+- `devdomain2.com`
+- `www.devdomain2.com`
+
+:::note
+That you can have only 1 license per Umbraco installation.
+:::
+
+## What does a license cover?
+
+Even though we use the same licensing model for Umbraco Forms and Umbraco Courier, there are a few differences as to what the licenses cover.
+
+### Umbraco Forms
+
+- A single license covers the installation of Umbraco Forms in 1 production domain, as well as in 2 development domains
+- The production domain includes **all subdomains** (e.g. `*.mysite.com`), as well as the `.local` extension (e.g. `mysite.com.local`)
+- The development domains works with or without the `www` subdomain
+- The license allows for an unlimited number of forms
+- The license also includes `localhost` as a valid domain
+
+In the case you run multiple sites within one Umbraco installation, e.g. you have multiple domains pointing at the same installation, you have the option to purchase and add **additional domains** to your license.
+
+Additional domains can be purchased from your account on [Umbraco.com](https://umbraco.com) for 129 €. Each additional domain includes 1 live domain and 2 development / testing domains.
+
+:::note
+That this is an add-on domain for existing licenses. Refunds will not be given for this product.
+:::
+
+### Umbraco Deploy
+
+Deploy license:
+
+A single licence covers one Umbraco solution, including all domains hosted by the solution,
+all production environments (if load-balancing) and all non-production environments.
+
+To clarify on the above:
+
+- You only need one license when you have a solution covering multiple domains- e.g. www.mysite.com and www.mysite.dk - load balanced in production over multiple servers running from the same database, managed from the same back-office instance, and with any number of non-production environments (staging, qa, etc.)
+
+- You need two licences If you have a web presence that consists of two separate websites hosted on different domains or sub-domains - e.g. www.mysite.com and shop.mysite.com - with each of these managed as a separate Umbraco installation using their own database and back-office in production.
+
+:::note
+The license for Umbraco Deploy comes with a recurring yearly fee. Learn more about this and pricing on [Umbraco.com](https://umbraco.com/products/umbraco-deploy/).
+:::
+
+### Umbraco Courier
+
+- A single license covers the installation and use of Umbraco Courier in 1 production domain, as well as 2 development domains
+- The production domain includes all subdomains (e.g. `*.domain.tld`), as well as the `.local` extension (e.g. `domain.tld.local`)
+- The development domains works with or without the `www` subdomain
+- The license also includes `localhost` as a valid domain
+
+For the Umbraco Courier license you do not need to purchase additional domains if you are running multiple sites within the same Umbraco installation.
+
+## Configuring and installing your license
+
+You can purchase licenses for our products on our website:
+
+- [Umbraco Forms licenses](https://umbraco.com/apps/umbraco-forms/)
+- [Umbraco Courier licenses](https://umbraco.com/apps/umbraco-courier/)
+
+When you've bought a license you need to configure it with your domains.
+
+You can either configure your license right away, or you can do it later by vising your account on Umbraco.com.
+
+![Configuring Umbraco Forms license](images/configure-forms-license.gif)
+
+## Installing your license
+
+Once you've configured your license with the correct domains, you are ready to install the license on your Umbraco installation.
+
+1. Download your license from your Umbraco.com account - this will give you a `.lic` file
+2. Place the file in the `/bin` directory in your Umbraco installation
+
+The `.lic` file must be placed in the `/bin` directory in order to be registered by Umbraco Deploy, Umbraco Courier or Umbraco Forms. If the file isn't placed correctly, the application will automatically switch to trial mode.
+
+![Installing Umbraco Forms license](images/install-forms-license.gif)
+
+## Alternative license location
+
+If you can't include the license file in the `/bin` directory for any reason it is possible to configure an alternative location for the file.
+
+It can be configured in the Umbraco installation's `Web.config` file by adding the following AppSetting, where `value="~/Licenses/"` contains the path of your custom license directory, relative to the root of your Umbraco Installation.
+
+:::warning
+This will also change the location for other Umbraco related licenses in this project.
+:::
+
+```xml
+<appSettings>
+    <add key="UmbracoLicensesDirectory" value="~/Licenses/" />
+    ...
+</appSettings>
+```

Add-ons/The-Licensing-model/index.md

@@ -1,22 +1,22 @@
 ---
-versionFrom: 7.0.0
+versionFrom: 9.0.0
 ---
 
 # The Licensing Model
 
-Umbraco Forms, Umbraco Deploy and Umbraco Courier are commercial products.
+Umbraco Forms and Umbraco Deploy are commercial products.
 
 For Umbraco Forms you will have a 14-day free trial to try out the product. After your trial expires, you'll need to have a **valid license** in order to keep using the product on your site.
 
-Umbraco Courier and Umbraco Deploy don't come with a 14-day free trial, which means you will need a **valid license** in order to use the products. You will be able to test both Deploy and Courier on a local setup without a license.
+Umbraco Deploy doesn't come with a 14-day free trial, which means you will need a **valid license** in order to use the products.
 
 ## How does it work?
 
 Licenses for our products are sold per domain and will also work on all subdomains. With every license you will also be able to configure two development / testing domains.
 
 ### Example
 
-let's say that you have a license configured for your domain, `mysite.com`, and you've configured two development domains, `devdomain.com` and `devdomain2.com`.
+Let's say that you have a license configured for your domain, `mysite.com`, and you've configured two development domains, `devdomain.com` and `devdomain2.com`.
 
 The license will cover the following domains:
 
@@ -35,7 +35,7 @@ That you can have only 1 license per Umbraco installation.
 
 ## What does a license cover?
 
-Even though we use the same licensing model for Umbraco Forms and Umbraco Courier, there are a few differences as to what the licenses cover.
+Even though we use the same licensing model for Umbraco Forms and Umbraco Deploy, there are a few differences as to what the licenses cover.
 
 ### Umbraco Forms
 
@@ -70,21 +70,12 @@ To clarify on the above:
 The license for Umbraco Deploy comes with a recurring yearly fee. Learn more about this and pricing on [Umbraco.com](https://umbraco.com/products/umbraco-deploy/).
 :::
 
-### Umbraco Courier
-
-- A single license covers the installation and use of Umbraco Courier in 1 production domain, as well as 2 development domains
-- The production domain includes all subdomains (e.g. `*.domain.tld`), as well as the `.local` extension (e.g. `domain.tld.local`)
-- The development domains works with or without the `www` subdomain
-- The license also includes `localhost` as a valid domain
-
-For the Umbraco Courier license you do not need to purchase additional domains if you are running multiple sites within the same Umbraco installation.
-
 ## Configuring and installing your license
 
 You can purchase licenses for our products on our website:
 
 - [Umbraco Forms licenses](https://umbraco.com/apps/umbraco-forms/)
-- [Umbraco Courier licenses](https://umbraco.com/apps/umbraco-courier/)
+- [Umbraco Deploy licenses](https://umbraco.com/products/umbraco-deploy/)
 
 When you've bought a license you need to configure it with your domains.
 
@@ -97,25 +88,28 @@ You can either configure your license right away, or you can do it later by visi
 Once you've configured your license with the correct domains, you are ready to install the license on your Umbraco installation.
 
 1. Download your license from your Umbraco.com account - this will give you a `.lic` file
-2. Place the file in the `/bin` directory in your Umbraco installation
+2. Place the file in the `/umbraco/Licenses` directory in your Umbraco installation
 
-The `.lic` file must be placed in the `/bin` directory in order to be registered by Umbraco Deploy, Umbraco Courier or Umbraco Forms. If the file isn't placed correctly, the application will automatically switch to trial mode.
+The `.lic` file must be placed in the `/umbraco/Licenses` directory in order to be registered by Umbraco Deploy or Umbraco Forms. If the file isn't placed correctly, the application will automatically switch to trial mode.
 
 ![Installing Umbraco Forms license](images/install-forms-license.gif)
 
 ## Alternative license location
 
-If you can't include the license file in the `/bin` directory for any reason it is possible to configure an alternative location for the file.
+If you can't include the license file in the `/umbraco/Licenses` directory for any reason it is possible to configure an alternative location for the file.
 
-It can be configured in the Umbraco installation's `Web.config` file by adding the following AppSetting, where `value="~/Licenses/"` contains the path of your custom license directory, relative to the root of your Umbraco Installation. 
+It can be configured in the Umbraco installation's `appSettings.json` file by adding the following AppSetting, where the value contains the path of your custom license directory, relative to the root of your Umbraco Installation.
 
 :::warning
 This will also change the location for other Umbraco related licenses in this project.
 :::
 
-```xml
-<appSettings>
-    <add key="UmbracoLicensesDirectory" value="~/Licenses/" />
-    ...
-</appSettings>
+```json
+{
+  "Umbraco": {
+    "Licensing": {
+        "Directory": "~/custom-licenses-folder/"
+    }
+  }
+}
 ```

Add-ons/Umbraco-Deploy/Deploy-Settings/index-v8.md

@@ -0,0 +1,137 @@
+---
+versionFrom: 8.0.0
+meta.Title: "Umbraco Deploy settings"
+meta.Description: "Various settings for Umbraco Deploy"
+---
+
+# Configurations for Deployments
+
+The UmbracoDeploy.Settings.config file is empty by default, but there are some optional settings you can set in the file to ignore certain types of file, increase timeout limits, etc.
+
+## ExcludedEntityTypes
+
+This setting allows you to exclude a certain type of entity from being deployed. This is **not** recommended to set, but sometimes there may be issues with the way a custom media fileprovider works with your site and you will need to set it for media files. Here is an example:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<settings xmlns="urn:umbracodeploy-settings">
+  <excludedEntityTypes>
+    <add type="media-file" />
+  </excludedEntityTypes>
+</settings>
+```
+
+## RelationTypes
+
+This setting allows you to manage how relations are deployed between environments. You will need to specify an alias and a mode for each relationtype. The mode can be either:
+
+- `Exclude` - This causes the relation to be excluded and not transferred on deployments.
+- `Weak` - This causes the relation to be deployed if both content items are found on the target environment.
+- `Strong` - This requires the content item that is related is set as a dependency, so if anything is added as a relation it would also add it as a dependency.
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<settings xmlns="urn:umbracodeploy-settings">
+    <relationTypes>
+        <relationType alias="relateParentDocumentOnDelete" mode="Weak" />
+        <relationType alias="relateShopItemOnCreate" mode="Exclude" />
+    </relationTypes>
+</settings>
+```
+
+## ValueConnectors
+
+This setting is used by package creators who wants their custom editors to work with Deploy. The packages should be creating this setting automatically. There is a community driven package that has value connectors for Deploy called [Deploy Contrib](https://github.com/umbraco/Umbraco.Deploy.Contrib).
+
+Here is an example of how the setting can look:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<settings xmlns="urn:umbracodeploy-settings">
+    <valueConnectors>
+        <valueConnector alias="nuPickers.DotNetCheckBoxPicker"
+                        type="Umbraco.Deploy.Contrib.Connectors.ValueConnectors.NuPickersValueConnector,Umbraco.Deploy.Contrib.Connectors" />
+        <valueConnector alias="nuPickers.DotNetDropDownPicker"
+                        type="Umbraco.Deploy.Contrib.Connectors.ValueConnectors.NuPickersValueConnector,Umbraco.Deploy.Contrib.Connectors" />
+        <valueConnector alias="nuPickers.DotNetPrefetchListPicker"
+                        type="Umbraco.Deploy.Contrib.Connectors.ValueConnectors.NuPickersValueConnector,Umbraco.Deploy.Contrib.Connectors" />
+        <valueConnector alias="nuPickers.DotNetTypeaheadListPicker"
+                        type="Umbraco.Deploy.Contrib.Connectors.ValueConnectors.NuPickersValueConnector,Umbraco.Deploy.Contrib.Connectors" />
+    </valueConnectors>
+</settings>
+```
+
+## Timeout settings
+
+Umbraco Deploy have a few built-in timeouts, which on larger sites might need to be modified. You will usually see these timeouts in the backoffice with an exception mentioning a timeout. It will be as part of a full restore or a full deploy of an entire site. In the normal workflow you should never hit these timeouts.
+
+The defaults will cover most though. Changing the defaults by updating the `/Config/UmbracoDeploy.settings.config`. There are four settings available:
+
+- `sessionTimeout`
+- `sourceDeployTimeout`
+- `httpClientTimeout`
+- `databaseCommandTimeout`
+
+These timeout settings default to 20 minutes, but if you are transferring a lot of data you may need to increase it. All of these times are in *seconds*:
+
+:::note
+It's important that these settings are added to both the source and target environments in order to work.
+:::
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<settings xmlns="urn:umbracodeploy-settings">
+    <deploy sessionTimeout="1800" sourceDeployTimeout="1800" httpClientTimeout="1800" databaseCommandTimeout="1800" />
+</settings>
+```
+
+## Transfer Forms data as content
+
+In order for Deploy to handle Forms data as content, you'll need to add the following setting to `UmbracoDeploy.Settings.config`:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<settings xmlns="urn:umbracodeploy-settings">
+    <forms transferFormsAsContent="true" />
+</settings>
+```
+
+## Transfer dictionary items as content
+
+In a similar way, Deploy can be configured to allow for backoffice transfers of dictionary items instead of using files serialized to disk, by adding the following setting to `UmbracoDeploy.Settings.config`:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<settings xmlns="urn:umbracodeploy-settings">
+    <dictionary transferDictionaryAsContent="true" />
+</settings>
+```
+
+## Exporting member groups
+
+This setting is to be defined and set to false only if you are using an external membership provider for your members. You will not want to export Member Groups that would no longer be managed by Umbraco but by an external membership provider.
+
+Setting the `exportMemberGroups` to false will no longer export Member Groups to UDA entities on disk. By default if this setting is not present, its value will automatically be set to true as most sites use Umbraco's built-in membership provider and thus will want the membership groups exported.
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<settings xmlns="urn:umbracodeploy-settings">
+    <deploy exportMemberGroups="false" />
+</settings>
+```
+
+## Ignore broken dependencies
+
+When restoring or transferring content, Umbraco Deploy will make checks to ensure that any dependent content, media or other items are either present in the target environment, or can be deployed from the source environment.
+
+For example, if you have a media picker on a content item, that references a media item that's been deleted or is in the recycle bin, you'll get an error and the deploy won't complete until the issue is resolved (by removing the reference to the deleted media item).
+
+You can configure deploy to ignore these issues and proceed with the transfer operation without warning, with the following setting:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<settings xmlns="urn:umbracodeploy-settings">
+    <deploy ignoreBrokenDependencies="true" />
+</settings>
+```
+