docs: extend logging documentation for logging to an external device (#…

…1417)

* added comments regarding logging to an external device
* logging documentation improvement/restructuring
* additional docker-compose.yml cleanup

Co-authored-by: Stefan Hauke <s.hauke@intershop.de>

docker-compose.yml

@@ -6,17 +6,16 @@ services:
   pwa:
     build:
       context: .
-      # dockerfile: Dockerfile_noSSR
       args:
         serviceWorker: 'false'
         # activeThemes: b2b
         # activeThemes: b2c
     environment:
+      # ICM_BASE_URL:
       LOGGING: 'true'
       SOURCE_MAPS: 'true'
-      ICM_BASE_URL:
-      # PROXY_ICM: 'true'
       TRUST_ICM: 'true'
+      # PROXY_ICM: 'true'
       # PROMETHEUS: 'true'
       # MULTI_SITE_LOCALE_MAP: |
       #   en_US: /en
@@ -34,15 +33,18 @@ services:
       #   Punchout:
       #     type: PUNCHOUT
 
+    # Logging to an External Device (see logging.md)
+    # volumes:
+    #   - d:/pwa/logs:/.pm2/logs/
+
   # <CDN-Example>
   # add 127.0.0.1 mypwa.net to your hosts file and
   # uncomment the following lines
   #
-  #     - DEPLOY_URL=http://mypwa.net:4222
+  #     DEPLOY_URL: 'http://mypwa.net:4222'
   # cdn:
   #   build:
   #     context: .
-  #     dockerfile: Dockerfile_noSSR
   #     args:
   #       configuration: production
   #       serviceWorker: 'false'
@@ -60,25 +62,13 @@ services:
       - '4200:80'
       # - '4200:443'
       # - '9113:9113'
-    #
-    # Uncomment this if you want the containers CA to be available on your local machine
-    # 1.) provide below adjusted volume mapping
-    # 2.) download and install mkcert -> https://github.com/FiloSottile/mkcert
-    # 3.) `export CAROOT=/home/your-user/ca-dir`
-    # 4.) `mkcert -install`
-    #
-    # For more details have a look at https://github.com/FiloSottile/mkcert#installing-the-ca-on-other-systems
-    #
-    # hostname: 'your-local-host-name-with-fqdn'
-    # volumes:
-    #  - /home/your-user/ca-dir:/root/.local/share/mkcert
     environment:
       UPSTREAM_PWA: 'http://pwa:4200'
-      # DEBUG: 1
       NGINX_ENTRYPOINT_QUIET_LOGS: ANYVALUE
       CACHE: 0
-      SSR: 1
-      SSL: 0
+      # SSL: 1
+      # SSR: 0
+      # DEBUG: 1
       # PROMETHEUS: 1
       # COMPRESSION: 0
       # DEVICE_DETECTION: 0
@@ -87,7 +77,6 @@ services:
       # MULTI_CHANNEL_SOURCE: env:///ASDF?type=application/yaml
       # BASIC_AUTH: 'developer:!InterShop00!'
       # BASIC_AUTH_IP_WHITELIST: |
-      #   # - 172.22.0.1
       #   - 1.2.3.4
       # OVERRIDE_IDENTITY_PROVIDERS: |
       #   .+:
@@ -107,3 +96,19 @@ services:
           - baseHref: /b2c
             channel: default
             theme: b2c
+
+    # Logging to an External Device (see logging.md)
+    # volumes:
+    #   - d:/pwa/logs:/var/log/
+
+    # Uncomment this if you want the containers CA to be available on your local machine
+    # 1.) provide below adjusted volume mapping
+    # 2.) download and install mkcert -> https://github.com/FiloSottile/mkcert
+    # 3.) `export CAROOT=/home/your-user/ca-dir`
+    # 4.) `mkcert -install`
+    #
+    # For more details have a look at https://github.com/FiloSottile/mkcert#installing-the-ca-on-other-systems
+    #
+    # hostname: 'your-local-host-name-with-fqdn'
+    # volumes:
+    #  - /home/your-user/ca-dir:/root/.local/share/mkcert

docs/concepts/logging.md

@@ -7,20 +7,11 @@ kb_sync_latest_only
 
 # Logging
 
-## nginx
-
-The nginx image providing multi-channel configuration uses the default logging capabilities of [nginx](https://www.nginx.com/).
-You can enable `json` formatted logging by passing environment variable `LOGFORMAT=json` to the container.
-When no `LOGFORMAT` variable is passed the container uses `main` as its default format.
-
-- [Configure Logging](https://docs.nginx.com/nginx/admin-guide/monitoring/logging/)
-- [Debugging Nginx Configuration](https://easyengine.io/tutorials/nginx/debugging/)
-
-## Server-Side Rendering
+## Server-Side Rendering (SSR)
 
 The _express.js_ image serving the Angular Universal Server-Side Rendering can be provisioned to log extended information to the console by supplying the environment variable `LOGGING=true`.
 
-Information logged to the console contains the following:
+Information logged to the console includes the following:
 
 - Requests to the SSR process are logged with [morgan](https://github.com/expressjs/morgan) (see configuration in _server.ts_) in the form of:
 
@@ -30,9 +21,47 @@ 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.
+- Uncaught `Error` objects thrown in the SSR process, including `HttpErrorResponse` and runtime errors, are printed as well.
+
+## NGINX
+
+The NGINX image providing multi-channel configuration uses the default logging capabilities of [nginx](https://www.nginx.com/).
+You can enable `json` formatted logging by passing the environment variable `LOGFORMAT=json` to the container.
+If no `LOGFORMAT` variable is passed, the container uses `main` as its default format.
+
+Additionally, the environment variable `DEBUG=true` provides even more debugging output in the NGINX logs.
+
+- [Configure Logging](https://docs.nginx.com/nginx/admin-guide/monitoring/logging/)
+- [Debugging Nginx Configuration](https://easyengine.io/tutorials/nginx/debugging/)
+
+## Logging to an External Device
+
+Within PWA development systems, information from the SSR and NGINX containers can be stored in external log files for analysis purposes.
+When launching your PWA as a Docker image/container, you can copy the log information from the containers which can be stored in the local file system using Docker volumes.
+Enabled volumes allow you to write SSR and NGINX logs in local Unix/Windows directories.
+
+The path is composed as follows:
+
+- `d:/pwa/logs` - The local Windows/Unix directory of the development machine where the logs should be stored.
+- `/var/log/` - The log location in the SSR/NGINX container.
+
+To enable logging to volumes, copy the examples below to the according `docker-compose.yml` sections.
+
+### PWA (SSR with PM2)
+
+```yaml
+volumes:
+  - d:/pwa/logs:/.pm2/logs/
+```
+
+### NGINX
+
+```yaml
+volumes:
+  - d:/pwa/logs:/var/log/
+```
 
-# Further References
+## Further References
 
 - [Guide - Building and Running Server-Side Rendering](../guides/ssr-startup.md)
 - [Guide - Building and Running nginx Docker Image](../guides/nginx-startup.md)