Add documentation about configuration inheritance

Author: JonasAlfredsson

docs/nginx_tips.md

@@ -12,7 +12,7 @@ a look on the main `nginx.conf` file from the parent image. It has a couple of
 standard settings included, but on the last line we can se that it opens the
 `/etc/nginx/conf.d/` folder and loads any file that ends with `.conf`.
 
-```conf
+```bash
 user  nginx;
 worker_processes  auto;
 
@@ -62,6 +62,106 @@ and change any of the files within it, the changes will be visible inside the
 container.
 
 
+## Configuration Inheritance
+To keep this explanation simple, yet useful, we begin by stating that the Nginx
+configuration is split into four blocks. Variables and settings declared in an
+outer block (e.g. the Global block) will be inherited by an inner block (e.g.
+the Server block) unless you change it inside this inner block.
+
+So in the example below I have added comments with the current value of the
+[`keepalive_timeout`][9] setting in each block:
+
+```bash
+# -- Global/main block --
+# keepalive_timeout = 60 (The default value)
+http {
+    # -- HTTP block --
+    keepalive_timeout = 30 # The value has now changed to 30
+    server {
+        # -- Server block --
+        # keepalive_timeout = 30 (value inherited from http block)
+        location /abc/ {
+            # -- Location block nbr 1 --
+            keepalive_timeout = 50 # The value has now changed to 50
+        }
+        location /xyz/ {
+            # -- Location block nbr 2 --
+            # keepalive_timeout = 30 (value inherited from server block)
+        }
+    }
+}
+```
+
+This is pretty straight forward for the settings that are only one value, but
+the commonly used [`proxy_set_header`][10] setting can be declared multiple
+times in order to add multiple values to it, and [its inheritance][11] works a
+bit differently. The following is true of all of the settings that can be
+declared multiple times.
+
+In the example below we want to add two headers to all requests, so we
+declare them in the `http` block. This builds a map/dictionary with the
+key-value pairs we want, and this will be inherited to all the location blocks.
+However, in the first location block we want to **add** another header, but
+doing it in this way will instead overwrite the current one with just this new
+header.
+
+```bash
+http {
+    proxy_set_header key1 value1;
+    proxy_set_header key2 value2;
+    server {
+        # proxy_headers: {
+        #     "key1": "value1"
+        #     "key2": "value2"
+        # }
+        location /abc/ {
+            proxy_set_header key3 value3;
+            # proxy_headers: {
+            #     "key3": "value3"
+            # }
+        }
+        location /xyz/ {
+            # proxy_headers: {
+            #     "key1": "value1"
+            #     "key2": "value2"
+            # }
+        }
+    }
+}
+```
+
+The suggested solution to this problem is to create a separate file with the
+"common" headers, and then `include` this file where needed. So in our case we
+create the file `/etc/nginx/common_headers` with the following content:
+
+```
+proxy_set_header key1 value1;
+proxy_set_header key2 value2;
+```
+
+and then change the config to the following which would make the special
+location block have all the desired headers:
+
+```bash
+http {
+    include common_headers;
+    server {
+        location /abc/ {
+            include common_headers;
+            proxy_set_header key3 value3;
+            # proxy_headers: {
+            #     "key1": "value1"
+            #     "key2": "value2"
+            #     "key3": "value3"
+            # }
+        }
+        location /xyz/ {
+        }
+    }
+}
+```
+
+
 ## Reject Unknown Server Name
 When setting up server blocks there exist a setting called `default_server`,
 which means that Nginx will use this server block in case it cannot match
@@ -139,3 +239,6 @@ minimal changes to the original.
 [6]: https://github.com/AxisCommunications/docker-nginx-ldap
 [7]: https://github.com/nginxinc/docker-nginx/tree/master/entrypoint
 [8]: hhttps://medium.com/@jonsbun/why-need-to-be-careful-when-mounting-single-files-into-a-docker-container-4f929340834
+[9]: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_timeout
+[10]: https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header
+[11]: https://stackoverflow.com/a/32126596