docs: deployment documentation rework (#398)

- move and adapt nginx configuration
- move angular specific deployment scenario document
- skeleton for building blocks
- test production deployment instructions
- concept for multi-site

docs/README.md

@@ -23,6 +23,7 @@ kb_sync_latest_only
 - [Concept - Localization](./concepts/localization.md)
 - [Concept - SEO](./concepts/search-engine-optimization.md)
 - [Guide - Forms](./guides/forms.md)
+- [Concept - Deployment Scenarios for Angular Applications](./concepts/deployment-angular.md)
 
 ### Developing
 
@@ -55,8 +56,10 @@ kb_sync_latest_only
 
 ### Setup
 
-- [Concept - Deployment Scenarios](./concepts/deployment-scenarios.md)
-  - [Guide - SSR Parameters](./guides/ssr-startup.md)
+- [Concept - Building Blocks of the Intershop PWA](./concepts/pwa-building-blocks.md)
+  - [Guide - Building and Running Server-Side Rendering](./guides/ssr-startup.md)
+  - [Guide - Building and Running nginx Docker Image](./guides/nginx-startup.md)
+- [Concept - Multi-Site Handling](./concepts/multi-site-handling.md)
 - [Concept - Hybrid Approach](./concepts/hybrid-approach.md)
   - [Guide - Hybrid Approach and ICM URL Rewriting](./guides/hybrid-approach-icm-url-rewriting.md)
 - [Concept - Logging](./concepts/logging.md)

docs/concepts/configuration.md

@@ -80,7 +80,7 @@ Deployment settings do not influence the build process and therefore can be set
 The main criteria of this category is the fact that deployment settings do not change during runtime.
 The most common way of supplying them can be implemented by using Angular CLI environment files and `InjectionToken`s for distribution throughout the application's code.
 
-An example for this kind of settings are breakpoint settings for the different device classes of the application touchpoints.
+An example for this kind of settings are breakpoint settings for the different device classes of the application touch points.
 
 ### Runtime Settings
 
@@ -91,45 +91,23 @@ Therefore only NgRx means should be used to supply them.
 Nevertheless, default values can be provided by environment files and can later be overridden by system environment variables.
 
 Everything managed in the NgRx state is accumulated on the server side and sent to the client side with the initial HTML response.
-The reason for this is that this is the most common deployment scenario of PWAs (see [Concept - Deployment Scenarios](./deployment-scenarios.md)).
 
-## Multi-Site Handling
-
-Since version 0.9 of the PWA there are means to dynamically configure ICM channel and application to determine the correct REST endpoint for each incoming top level request.
-Nevertheless, you can still configure it in a static way for each PWA deployment via Angluar CLI environments.
+## ICM Endpoint Configuration
 
 ### Setting the Base URL
 
 At first, the PWA has to be connected with the corresponding ICM.
 This can be done by modifying environment files or by setting the environment variable `ICM_BASE_URL` for the process running the _Node.js_ server.
 The latter is the preferred way.
+See also [Guide - Building and Running Server-Side Rendering](../guides/ssr-startup.md)
 
 Independent of where and how you deploy the Angular Universal application, be it in a docker container or plain, running on Azure, with or without service orchestrator, setting the base URL provides the most flexible way of configuring the PWA.
 Refer to the documentation for mechanisms of your environment on how to set and pass environment variables.
 
-### Static Setting for Channels
+### Setting for Channels and Applications
 
 Use the properties `icmChannel` and `icmApplication` in the Angular CLI environment or the environment variables `ICM_CHANNEL` and `ICM_APPLICATION` to statically direct one deployment to a specific REST endpoint of the ICM.
 
-### Dynamic Setting of Channels
-
-To set ICM channels and applications dynamically, you have to use URL rewriting in a reverse proxy running in front of the PWA instances.
-The values have to be provided as URL parameters (not to be confused with query parameters).
-
-**nginx URL rewrite snippet**
-
-```text
-rewrite ^(.*)$ "$1;channel=inSPIRED-inTRONICS_Business-Site;application=-" break;
-```
-
-The above example configuration snippet shows a [Nginx](https://en.wikipedia.org/wiki/Nginx) rewrite rule on how to map an incoming top level request URL to an internal worker process, e.g., _Node.js_.
-It shows both the PWA parameters `channel`, `application` and their fixed example values.
-The parameters of each incoming request are then read and transferred to the NgRx store to be used for the composition of the initial HTML response on the server side.
-Afterwards they are propagated to the client side and re-used for subsequent REST requests.
-
-In the source code of the project we provide an extended [Nginx](https://en.wikipedia.org/wiki/Nginx) docker image for easy configuration of multiple channels via sub-domains.
-Refer to our Gitlab CI configuration (file _.gitlab-ci.yml)_ for a usage example.
-
 ## Feature Toggles
 
 To activate additional functionality, we use the concept of feature toggles throughout the application.
@@ -140,7 +118,7 @@ Of course, the ICM server must supply appropriate REST resources to leverage fun
 ### Configuring Features
 
 The configuration of features can be done statically by the Angular CLI environment property `features` (string array) or the environment parameter `FEATURES` (comma-separated string list).
-To configure it dynamically, use the PWA URL parameter `features` (comma-separated string list) during URL rewriting in the reverse proxy.
+To configure it dynamically, use the PWA URL parameter `features` (comma-separated string list) during URL rewriting in the reverse proxy. (see [Concept - Multi-Site Handling][concept-multi-site])
 
 ### Programmatically Switching Features
 
@@ -193,7 +171,7 @@ Switching features in tests can be triggered by calling [`FeatureToggleModule.sw
 
 You can set the default locale statically by modifying the order of the provided locales in the Angular CLI environment files.
 The first locale is always chosen as the default one.
-To dynamically set the default locale, use the URL parameter `lang` when rewriting the URL in the reverse proxy (see Dynamic Setting of Channels).
+To dynamically set the default locale, use the URL parameter `lang` when rewriting the URL in the reverse proxy (see [Concept - Multi-Site Handling][concept-multi-site]).
 
 ## Extend Locales
 
@@ -215,4 +193,12 @@ export class ConfigurationModule {
 
 > ### Configuration REST Resource
 >
-> We are currently planning to implement a Configuration REST resource in the ICM so that all necessary runtime configuration can be defined in the ICM Backoffice and consumed by each PWA deployment.
+> We are currently planning to implement a Configuration REST resource in the ICM so that all necessary runtime configuration can be defined in the ICM Back Office and consumed by each PWA deployment.
+
+# Further References
+
+- [Concept - Multi-Site Handling][concept-multi-site]
+- [Guide - Building and Running Server-Side Rendering](../guides/ssr-startup.md)
+- [Guide - Building and Running nginx Docker Image](../guides/nginx-startup.md)
+
+[concept-multi-site]: ./multi-site-handling.md

docs/concepts/deployment-angular.md

@@ -0,0 +1,57 @@
+<!--
+kb_concepts
+kb_pwa
+kb_everyone
+kb_sync_latest_only
+-->
+
+# Deployment Scenarios for Angular Applications
+
+## Simple Browser-Side Rendering
+
+Angular Applications are by default built for a [static deployment][angular-deployment].
+When running `ng build` in any shape or form, the build output is aggregated in the `dist` folder and the resulting files can be statically served using any HTTP server that is capable of doing that (only a [fallback](https://angular.io/guide/deployment#routed-apps-must-fallback-to-indexhtml) for `index.html` has to be configured).
+
+When the application is served this way, the initial page response for the browser is minimal (`index.html` with scripts inserted) and the application gets composed and rendered on the client side.
+
+![Angular-BrowserSideApp-Sequence](deployment-angular-browsersideapp-sequence.jpg 'Angular-BrowserSideApp-Sequence')
+
+Of course, this can have a significant impact on the client side if no efficient rendering power is available.
+Search engine crawlers might also not be able to execute JavaScript and therefor might only see the initial minimal response.
+
+This method of deployment is suitable for demo servers supplying a fast build chain.
+However, we do not recommend this setup for production use.
+
+> This setup is also used for the Angular CLI built-in webpack-dev-server and should not be confused with a standard production setup.
+
+## Browser-Side Rendering with On-Demand Server-Side Pre-Rendering (Angular Universal)
+
+To tackle sophisticated SEO requirements, the [Angular Universal][angular-universal] package was introduced.
+In a second step in the build process, a server-side application can be built by the Angular CLI after building the client-side application.
+The resulting distribution has to be executed in a node environment.
+The _server.js_ executable handles client requests on the server and pre-renders the content of the page, basically executing everything in a Node.js environment.
+The resulting initial page response to the browser is mainly prepared and can be displayed quickly on the client side while the client-side application is booting up.
+
+![Angular-ServerSideRendering-Sequence](deployment-angular-serversiderendering-sequence.jpg 'Angular-ServerSideRendering-Sequence')
+
+This method is the default setup for the Intershop PWA.
+We provide a `Dockerfile` for building the [SSR Image][concept-building-blocks].
+
+## Impact of Service Workers
+
+If the Intershop PWA is run with an enabled [Service Worker][concept-progressive-web-app], the SSR process is only triggered for the first visit to the web page.
+After that, the Service Worker makes the Application behave like a simple browser-side application, where certain additional caching can lead to an improved client experience.
+
+Browsers and Crawlers that don't support JavaScript execution will however continue to get fully pre-rendered page responses from the SSR process.
+
+# Further References
+
+- [Concept - Building Blocks][concept-building-blocks]
+- [Concept - Progressive Web App][concept-progressive-web-app]
+- [Angular - Deployment][angular-deployment]
+- [Angular - Universal][angular-universal]
+
+[angular-deployment]: https://angular.io/guide/deployment
+[angular-universal]: https://angular.io/guide/universal
+[concept-building-blocks]: ./pwa-building-blocks.md
+[concept-progressive-web-app]: ./progressive-web-app.md#service-worker

docs/concepts/logging.md

@@ -29,3 +29,8 @@ Information logged to the console contains the following:
 - Further the redirect actions of the [Hybrid Approach](./hybrid-approach.md) are logged with `RED <url>`.
 
 - Uncaught `Error` objects thrown in the SSR process, including `HttpErrorResponse` and runtime errors are printed as well.
+
+# Further References
+
+- [Guide - Building and Running Server-Side Rendering](../guides/ssr-startup.md)
+- [Guide - Building and Running nginx Docker Image](../guides/nginx-startup.md)

docs/concepts/multi-site-handling.md

@@ -0,0 +1,58 @@
+<!--
+kb_concepts
+kb_pwa
+kb_everyone
+kb_sync_latest_only
+-->
+
+# Multi-Site Handling
+
+## Motivation
+
+Imagine running an Europe-wide shop with Intershop, where the website is available in 16 different countries with different languages and a varying selection of products, but only little modification of the website appearance over all.
+This would be set up by having 16 channels with one headless application each on the ICM side.
+
+In a setup before the PWA 0.9 release this would have lead to a deployment with 16 PWA instances combined with one nginx for caching each.
+Of course, a fail-over setup would increase the number of required deployment containers even more.
+
+That is why, since version 0.9 of the PWA there are means to dynamically configure ICM channel and application to determine the correct REST endpoint for each incoming top level request.
+
+The aforementioned scenario can now be run with just one PWA instance and a reverse proxy running in front, implementing this dynamic configuration.
+
+## Configuration
+
+To set ICM channels and applications dynamically, you have to use URL rewriting in a reverse proxy running in front of the PWA instances.
+The values have to be provided as URL parameters (not to be confused with query parameters).
+
+**nginx URL rewrite snippet**
+
+```text
+rewrite ^(.*)$ "$1;channel=inSPIRED-inTRONICS_Business-Site;application=-" break;
+```
+
+The above example configuration snippet shows an [nginx](https://en.wikipedia.org/wiki/Nginx) rewrite rule on how to map an incoming top level request URL to a dynamically configured URL for the downstream PWA instance.
+It shows both the PWA parameters `channel`, `application` and their fixed example values.
+The parameters of each incoming request are then read by the PWA upon initialization and used for the composition of the initial HTML response on the server side.
+Afterwards they are propagated to the client side and re-used for subsequent REST requests.
+
+In the source code of the project we provide an [extended nginx](./pwa-building-blocks.md#pwa---nginx) docker image for easy configuration of multiple channels via sub-domains.
+
+## Multi-Site Production Deployment
+
+These steps should give an overview of the internal workings:
+
+![Current Deployment](pwa-building-blocks-production-deployment.svg)
+
+1. The Browser requests the page by URL from the reverse proxy. Nginx appends URL parameters to the incoming request URL for channel, application, ... depending on the incoming domain.
+
+2. The node express.js server runs Angular Universal pre-rendering for the requested URL. Angular Universal dynamically configures itself with the incoming parameters.
+
+3. The requested page is filled with content retrieved via ICM REST API for this dynamically configured channel.
+
+4. The configuration parameters are persisted for the client application via state transfer. Afterwards, the response is delivered to nginx.
+
+5. The response is delivered to the browser.
+
+6. The initial page response is displayed to the user and the Angular Client Application is booting up in the browser, configuring itself with the transferred parameters for channel, application, ...
+
+7. Once booted up, additional REST Calls are directed to the matching ICM endpoint for the configured channel.

docs/concepts/progressive-web-app.md

@@ -18,7 +18,7 @@ The manifest in the PWA is theme specific and can be customized in the file `src
 
 ## Service Worker
 
-Service workers are automatically installed into client device browsers and take over the handling of the application on the client side.
+[Service Workers](https://angular.io/guide/service-worker-intro) are automatically installed into client device browsers after the first visit to the shop and take over the all handling of the application on the client side.
 Possible advanced features supplied are offline-capabilities and push notifications.
 After installation, the service worker effectively disables server-side rendering for clients and invokes all rendering on the client himself.