fixing grepinclude references for docs.wire.com and adjusting nix build context; updating TLS documentation

changelog.d/4-docs/WPB-4554

@@ -0,0 +1 @@
+Fix missing code sections on docs.wire.com, notably on "configuring TLS" page.

docs/README.md

@@ -101,6 +101,21 @@ Run `make pdf` and look at files in `./build/pdf/`.
 
 You can use the `make dev-pdf` target to get auto-refreshing PDF files as you save source files. This is also acessible at `http://localhost:3000/wire_federation.pdf`.
 
+### Testing CI build locally
+
+In order to test changes to the deployment process (eg. nix changes, new grepinclude defaults), the build process can be invoked locally with
+
+```
+nix-build --no-out-link ./nix -A docs
+```
+
+If the command succeeds, the static content can be viewed in the browser directly from the nix build dir (adjust the build path)
+
+```
+firefox /nix/store/isjbzhmm34kr1i1xdgwfrrn98s4hgj43-wire-docs/html/index.html
+```
+
+
 ### Upload to S3
 
 CI is set up to do this automatically on a push to master. If for some reason you wish to upload manually to S3:

docs/src/how-to/install/tls.md

@@ -17,23 +17,36 @@ The following table lists recommended ciphers for TLS server setups, which shoul
 | TLS_CHACHA20_POLY1305_SHA256  | TLSv1.3 | no           | no               | **modern**              |
 
 ```{note}
-If you enable TLSv1.3, openssl does always enable the three default cipher suites for TLSv1.3.
-Therefore it is not necessary to add them to openssl based configurations.
+If you enable TLSv1.3, OpenSSL does always enable the three default cipher suites for TLSv1.3.
+Therefore it is not necessary to add them to OpenSSL based configurations.
 ```
 
 (ingress-traffic)=
 
 ## Ingress Traffic (wire-server)
 
-The list of TLS ciphers for incoming requests is limited by default to the [following](https://github.com/wireapp/wire-server/blob/master/charts/ingress-nginx-controller/values.yaml#L41-45) (for general server-certificates, both for federation and client API), and can be overridden on your installation if needed.
+TLS ciphers for incoming requests is by default configured as a [limted set of ciphers](https://github.com/wireapp/wire-server/blob/master/charts/ingress-nginx-controller/values.yaml) (for general server-certificates, both for federation and client API), and can be overridden on your installation if needed.
+```{grepinclude} ../charts/ingress-nginx-controller/values.yaml ssl-protocols:
+---
+lines-before: 0
+lines-after: 4
+language: yaml
+---
+```
 
 ## Egress Traffic (wire-server/federation)
 
-The list of TLS ciphers for outgoing federation requests is currently hardcoded, the list is [here](https://github.com/wireapp/wire-server/blob/master/services/federator/src/Federator/Remote.hs#L164-L180).
+The list of ciphers for outgoing federation requests is currently restricted to a subset of "Wire default" [TLSv1.2 ciphers](https://github.com/wireapp/wire-server/blob/develop/services/federator/src/Federator/Monitor/Internal.hs#L397) in accordance with BSI recommendations. TLSv1.3 is not supported as of yet.
+```{grepinclude} ../services/federator/src/Federator/Monitor/Internal.hs blessedTLS12Ciphers =
+---
+lines-before: 0
+lines-after: 6
+---
+```
 
 ## SFTD (ansible)
 
-The list of TLS ciphers for incoming SFT requests (and metrics) are defined in ansible templates [sftd.vhost.conf.j2](https://github.com/wireapp/ansible-sft/blob/develop/roles/sft-server/templates/sftd.vhost.conf.j2#L19) and [metrics.vhost.conf.j2](https://github.com/wireapp/ansible-sft/blob/develop/roles/sft-server/templates/metrics.vhost.conf.j2#L13).
+The list of TLS ciphers for incoming SFT requests (and metrics) are defined in ansible templates [sftd.vhost.conf.j2](https://github.com/wireapp/ansible-sft/blob/develop/roles/sft-server/templates/sftd.vhost.conf.j2#L23) and [metrics.vhost.conf.j2](https://github.com/wireapp/ansible-sft/blob/develop/roles/sft-server/templates/metrics.vhost.conf.j2#L17).
 
 ## SFTD (kubernetes)
 
@@ -42,7 +55,7 @@ Kubernetes based deployments make use of the settings from {ref}`ingress-traffic
 
 ## Coturn (kubernetes)
 
-The list of TLS ciphers for "TLS over TCP" TURN are defined in the [coturn helm chart](https://github.com/wireapp/wire-server/blob/master/charts/coturn/)
+The list of TLS ciphers for "TLS over TCP" TURN are defined in the [coturn helm chart](https://github.com/wireapp/wire-server/blob/master/charts/coturn/values.yaml#L32)
 
 ```{grepinclude} ../charts/coturn/values.yaml ciphers:
 ---

nix/default.nix

@@ -52,9 +52,17 @@ let
         nativeBuildInputs = docsPkgs ++ [ pkgs.gnumake ];
       }
       ''
-        cp -rH ${pkgs.nix-gitignore.gitignoreSource [] ../docs}/* .
-        chmod -R +w ./src
-        cp ${../CHANGELOG.md} ./src/changelog/changelog.md
+        mkdir docs charts services
+        cp -rH ${pkgs.nix-gitignore.gitignoreSource [] ../docs}/* docs/
+        # GrepInclude snippets in the docs refer to files under ../charts/ and ../services/, 
+        # so we need to copy these too before building.
+        # FUTUREWORK: perhaps there is a nicer way to copy everything that does not need 3 separate lines,
+        # however the statement `../` inside `cp -rH $#{pkgs.nix-gitignore.gitignoreSource [] ../}* .` is not valid.
+        cp -rH ${pkgs.nix-gitignore.gitignoreSource [] ../charts}/* charts/
+        cp -rH ${../services}/* services/
+        chmod -R +w ./docs/src
+        cp ${../CHANGELOG.md} ./docs/src/changelog/changelog.md
+        cd docs
         make docs-all
         mkdir $out
         cp -r build/* $out/