Merge branch 'main' into uc-payment-links

Author: sofietoft

10/umbraco-cms/SUMMARY.md

@@ -34,6 +34,7 @@
     * [Hosting Umbraco in IIS](fundamentals/setup/server-setup/iis.md)
     * [File And Folder Permissions](fundamentals/setup/server-setup/permissions.md)
     * [Runtime Modes](fundamentals/setup/server-setup/runtime-modes.md)
+    * [Running Umbraco in Docker](fundamentals/setup/server-setup/running-umbraco-in-docker.md)
     * [Umbraco in Load Balanced Environments](fundamentals/setup/server-setup/load-balancing/README.md)
       * [Load Balancing Azure Web Apps](fundamentals/setup/server-setup/load-balancing/azure-web-apps.md)
       * [Standalone File System](fundamentals/setup/server-setup/load-balancing/file-system-replication.md)

10/umbraco-cms/extending/language-files.md

@@ -194,4 +194,4 @@ In the above example of a missing translation for "assignDomain", locate this st
 </language>
 ```
 
-If you modify core language files or introduce a new language, you can assist the community by sharing your updates. This can be done by [submitting a pull request](https://github.com/umbraco/Umbraco-CMS/blob/contrib/.github/CONTRIBUTING.md) so that your changes are merged into the core.
+If you modify core language files or introduce a new language, you can assist the community by sharing your updates. This can be done by [submitting a pull request](https://github.com/umbraco/Umbraco-CMS/blob/main/.github/CONTRIBUTING.md) so that your changes are merged into the core.

10/umbraco-cms/extending/packages/language-files-for-packages.md

@@ -22,7 +22,7 @@ The `App_Plugins` version of the `Lang` directory is case sensitive on Linux sys
 
 Each language file can include one or more area. Each area contains a collection of language keys with the translation.
 
-For reference on the language file format see the core [language files on GitHub](https://github.com/umbraco/Umbraco-CMS/tree/contrib/src/Umbraco.Core/EmbeddedResources/Lang)
+For reference on the language file format see the core [language files on GitHub](https://github.com/umbraco/Umbraco-CMS/tree/main/src/Umbraco.Core/EmbeddedResources/Lang)
 
 ### Sample structure
 

10/umbraco-cms/fundamentals/setup/server-setup/README.md

@@ -30,3 +30,7 @@ Best practices for running Umbraco on Azure Web Apps.
 ## [Runtime modes](runtime-modes.md)
 
 The runtime mode setting optimizes Umbraco for the best development experience or optimal production environment.
+
+## [Running Umbraco in Docker](running-umbraco-in-docker.md)
+
+Overview of topics to consider when running Umbraco in Docker.

10/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md

@@ -0,0 +1,100 @@
+# Running Umbraco in Docker
+
+Exactly how you choose to compose your Dockerfile will depend on your project specific needs. This section is not intended as a comprehensive guide, rather as an overview of topics to be aware of when hosting in Docker.
+
+## What is Docker
+
+Docker is a platform for developing, shipping, and running applications in containers. Multiple services exist for hosting these containers.  For more information, refer to the [official Docker Documentation](https://docs.docker.com/)
+
+## The Docker file system
+
+By default, files created inside a container are written to an ephemeral, writable container layer. 
+This means that the files don't persist when the container is removed, and it's challenging to get files out of the container. Additionally, this writable layer is not suitable for performance-critical data processing.
+
+This has implications when running Umbraco in Docker.
+
+For more information, refer to the [Docker documentation on storage](https://docs.docker.com/engine/storage/).
+
+### General file system consideration 
+
+In general, when working with files and Docker you work in a "push" fashion with read-only layers. When you build, you take all your files and "push" them into this read-only layer.
+
+This means that you should avoid making files on the fly, and instead rely on building your image.
+
+In an Umbraco context, this means you should not create or edit template, script or stylesheet files via the backoffice. These should be deployed as part of your web application and not managed via Umbraco. 
+
+Similarly, you shouldn't use InMemory modelsbuilder, since that also relies on creating files on the disk. While this is not a hard requirement, it doesn't provide any value unless you are live editing your site.
+
+Instead, configure models builder to use "source code" mode in development, and "none" in production, as [described when using runtime modes](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes).
+
+
+### Logs
+
+Umbraco writes logs to the `/umbraco/Logs/` directory. Due to the performance implications of writing to a writable layer, 
+and the limited size, it is recommended to mount a volume to this directory.
+
+### Data
+
+The `/umbraco/Data/` directory is used to store temporary files, such as file uploads. Considering the limitations of the writable layer, you should also mount a volume to this directory.
+
+### Media
+
+It's recommended to not store media in the writable layer. This is for similar performance reasons as logs, 
+but also for practical hosting reasons. You likely want to persist media files between containers. 
+
+One solution is to use bind mounts. The ideal setup, though, is to store the media and ImageSharp cache externally. For more information, refer to the [Azure Blob Storage documentation](https://docs.umbraco.com/umbraco-cms/extending/filesystemproviders/azure-blob-storage).
+
+### Required files
+
+Your solution may require some specific files to run, such as license files. You will need to pass these files into the container at build time, or mount them externally. 
+
+## HTTPS
+
+When running websites in Docker, it's common to do so behind a reverse proxy or load balancer.
+In these scenarios you will likely handle SSL termination at the reverse proxy. This means that Umbraco will not be aware of the SSL termination, and will complain about not using HTTPS.
+
+Umbraco checks for HTTPS in two locations:
+
+1. The `HstsCheck` health check - This will result in a failed healthcheck.
+2. The `UseHttpsValidator` - This will result in a build error, if Production runtime mode is used.
+
+To avoid these checks failing, you can remove them in your project.
+
+### Health Check
+
+The health check must be removed via configuration, through the `appsettings.json` file, environment variables, or similar. For more information see the [Health Check documentation](../../../reference/configuration/healthchecks.md).
+
+The `HstsCheck` key is `E2048C48-21C5-4BE1-A80B-8062162DF124` so the appsettings will look something like:
+
+```json
+  "Umbraco": {
+    "CMS": {
+      "HealthChecks" : {
+        "DisabledChecks": [
+          {
+            "Id": "E2048C48-21C5-4BE1-A80B-8062162DF124"
+          }
+        ]
+      },
+      {...}
+```
+
+### Runtime mode validator
+
+The `UseHttpsValidator` must be removed through code For more information see the [Runtime mode documentation](runtime-modes.md).
+
+The code to remove the validator can look something like:
+
+```C#
+using Umbraco.Cms.Core.Composing;
+using Umbraco.Cms.Infrastructure.Runtime.RuntimeModeValidators;
+
+namespace MySite;
+
+public class DockerChecksRemover : IComposer
+{
+    public void Compose(IUmbracoBuilder builder)
+        => builder.RuntimeModeValidators().Remove<UseHttpsValidator>();
+}
+
+```

10/umbraco-cms/implementation/custom-routing/signalR.md

@@ -34,53 +34,9 @@ public class TestHub : Hub<ITestHubEvents>
 }
 ```
 
-## Define a custom route
-
-Next up, is defining a custom route. For this, we are going to use a `IAreaRoutes` and the base umbrace backend path so we dont have to reserve another path in the settings.
-
-```csharp
-using Microsoft.AspNetCore.Builder;
-using Microsoft.Extensions.DependencyInjection;
-using Umbraco.Cms.Core.Composing;
-using Umbraco.Cms.Core.DependencyInjection;
-using Umbraco.Cms.Web.Common.ApplicationBuilder;
-using Umbraco.Extensions;
-
-public class TestHubRoutes : IAreaRoutes
-{
-    private readonly IRuntimeState _runtimeState;
-    private readonly string _umbracoPathSegment;
-
-    public TestHubRoutes(
-        IOptions<GlobalSettings> globalSettings,
-        IHostingEnvironment hostingEnvironment,
-        IRuntimeState runtimeState)
-    {
-        _runtimeState = runtimeState;
-        _umbracoPathSegment = globalSettings.Value.GetUmbracoMvcArea(hostingEnvironment);
-    }
-
-    public void CreateRoutes(IEndpointRouteBuilder endpoints)
-    {
-        switch (_runtimeState.Level)
-        {
-            case Umbraco.Cms.Core.RuntimeLevel.Run:
-                endpoints.MapHub<TestHub>(GetTestHubRoute());
-                break;
-        }
-
-    }
-
-    public string GetTestHubRoute()
-    {
-        return $"/{_umbracoPathSegment}/{nameof(TestHub)}";
-    }
-}
-```
-
 ### Add the routing to the Umbraco Composer
 
-Last step in the setup is registering our custom route:
+The next step in the setup is registering our custom route:
 
 ```csharp
 using Microsoft.AspNetCore.Builder;
@@ -101,18 +57,17 @@ public class TestHubComposer : IComposer
             builder.Services.AddSignalR();
         }
 
-        // next is adding the routes we defined earlier
-        builder.Services.AddUnique<TestHubRoutes>();
         builder.Services.Configure<UmbracoPipelineOptions>(options =>
         {
             options.AddFilter(new UmbracoPipelineFilter(
-                "test",
-                 endpoints: applicationBuilder =>
+                "Signalr",
+                endpoints: applicationBuilder =>
                 {
                     applicationBuilder.UseEndpoints(e =>
                     {
-                        var hubRoutes = applicationBuilder.ApplicationServices.GetRequiredService<TestHubRoutes>();
-                        hubRoutes.CreateRoutes(e);
+                        e.MapHub<TestHub>($"/umbraco/{nameof(TestHub)}");
+
+                        // Register more SignalR hubs or routes here...
                     });
                 }
             ));

10/umbraco-cms/implementation/integration-testing.md

@@ -5,7 +5,7 @@ description: A guide to getting started with integration testing in Umbraco
 
 # Integration Testing
 
-These examples are for Umbraco 10. They use [NUnit](https://nunit.org/) as the testing framework. Leveraging [Umbraco.Cms.Tests.Integration](https://github.com/umbraco/Umbraco-CMS/tree/contrib/tests/Umbraco.Tests.Integration) providing base classes. Beware that the Nuget package has an issue fixed in v10.3.1. So it is recommended to use this version.
+These examples are for Umbraco 10. They use [NUnit](https://nunit.org/) as the testing framework. Leveraging [Umbraco.Cms.Tests.Integration](https://github.com/umbraco/Umbraco-CMS/tree/main/tests/Umbraco.Tests.Integration) providing base classes. Beware that the Nuget package has an issue fixed in v10.3.1. So it is recommended to use this version.
 
 ## Getting started
 

10/umbraco-cms/reference/angular/directives/umbproperty.md

@@ -30,4 +30,4 @@ var property = {
 
 The `view` property specifies the URL to the property editor that should be used for this property. To use one of the built-in property editors in Umbraco, you can specify the alias (eg. `textbox`) rather than the full URL to the view (eg. `/umbraco/Views/propertyeditors/textbox/textbox.html`).
 
-You can see a list of all the built-in property editors in the [propertyeditors folder on GitHub](https://github.com/umbraco/Umbraco-CMS/tree/v11/contrib/src/Umbraco.Web.UI.Client/src/views/propertyeditors).
+You can see a list of all the built-in property editors in the [propertyeditors folder on GitHub](https://github.com/umbraco/Umbraco-CMS/tree/83107bb31a7fe98f6c5b0a601c0e8ee898cd274b/src/Umbraco.Web.UI.Client/src/views/propertyeditors).

10/umbraco-cms/reference/cache/README.md

@@ -13,7 +13,7 @@ Although caching is a pretty standard concept it is very important to make sure
 
 In normal environments caching seems to be a pretty standard concept. If you are a package developer or developer who is going to publish a codebase to a load balanced environment then you need to be aware of how to invalidate your cache properly, so that it works in load balanced environments. If it is not done correctly then your package and/or codebase will not work the way that you would expect in a load balanced scenario.
 
-**If you are caching business logic data that changes based on a user's action in the backoffice and you are not using an **_**ICacheRefresher**_** then you will need to review your code and update it based on the below documentation.** 
+**If you're caching business logic based on backoffice user actions without using an _ICacheRefresher_, review and update your code using the documentation below.**
 {% endhint %}
 
 ## Retrieving and Adding items in the cache
@@ -48,10 +48,10 @@ There are 2 other base types of `ICacheRefresher` which are:
 * `ICacheRefresher<T>` - this inherits from `ICacheRefresher` and provides a set of strongly typed methods for cache invalidation. This is useful when executing the method to invoke the cache refresher, when you have the instance of the object already since this avoids the overhead of retrieving the object again.
   * `void Refresh(T instance);` - this would invalidate/refresh a single cache for the specified object.
   * `void Remove(T instance);` - this would invalidate a single cache for the specified object.
-* `IJsonCacheRefresher` - this inherits from `ICacheRefresher` but provides more flexibility if you need to invalidate cache based on more complex scenarios (e.g. the [MemberGroupCacheRefresher](https://github.com/umbraco/Umbraco-CMS/blob/v11/contrib/src/Umbraco.Core/Cache/MemberGroupCacheRefresher.cs)).
+* `IJsonCacheRefresher` - this inherits from `ICacheRefresher` but provides more flexibility if you need to invalidate cache based on more complex scenarios (for example, the [MemberGroupCacheRefresher](https://github.com/umbraco/Umbraco-CMS/blob/9f912aea0e4759a1fcea43d7469d3d4756b6fbe1/src/Umbraco.Core/Cache/MemberGroupCacheRefresher.cs)).
   * `void Refresh(string jsonPayload)` - Invalidates/refreshes any cache based on the information provided in the JSON. The JSON value is any value that is used when executing the method to invoke the cache refresher.
 
-There are several examples of `ICacheRefresher`'s in the core: https://github.com/umbraco/Umbraco-CMS/tree/v11/contrib/src/Umbraco.Core/Cache
+There are a couple of examples of `ICacheRefresher's` in the [core](https://github.com/umbraco/Umbraco-CMS/tree/9f912aea0e4759a1fcea43d7469d3d4756b6fbe1/src/Umbraco.Core/Cache).
 
 ### Executing an ICacheRefresher
 

10/umbraco-cms/reference/searching/examine/indexing.md

@@ -329,7 +329,7 @@ The index will only update its content when you manually trigger an index rebuil
 To update your index when content changes, you can use notification handlers.
 
 {% hint style="info" %}
-The following handler class does not automatically update the descendant items of the modified content nodes, such as removing descendants of deleted content. If changes to the parent content item can affect its children or descendant items in your setup, please refer to the [UmbracoContentIndex.PerformDeleteFromIndex() in Umbraco](https://github.com/umbraco/Umbraco-CMS/blob/contrib/src/Umbraco.Examine.Lucene/UmbracoContentIndex.cs#L124-L153). Such logic should be applied when both removing and reindexing content items of type _product_.
+The following handler class does not automatically update the descendant items of the modified content nodes, such as removing descendants of deleted content. If changes to the parent content item can affect its children or descendant items in your setup, please refer to the [UmbracoContentIndex.PerformDeleteFromIndex() in Umbraco](https://github.com/umbraco/Umbraco-CMS/blob/main/src/Umbraco.Examine.Lucene/UmbracoContentIndex.cs#L124-L153). Such logic should be applied when both removing and reindexing content items of type _product_.
 {% endhint %}
 
 ```csharp