Reverse proxy in DDEV cluster

docs/infrastructure_and_maintenance/clustering/clustering_with_ddev.md

@@ -27,6 +27,125 @@
 
 To run an [[= product_name_cloud =]] project locally, you may refer to [DDEV and Ibexa Cloud](ddev_and_ibexa_cloud.md) instead.
 
+## Install reverse proxy
+
+### Varnish
+
+The following sequence of commands:
+
+1. Sets a variable with the desired Varnish version, here Varnish 7.1
+2. Copies and customizes `parameters.vcl` file in `.ddev/varnish/` (which is mounted as `/etc/varnish/` into the container)
+    - set `web` container has the backend host and an invalidator (so back office can purge cache)
+    - add "all IPs" CIDR notation to `debuggers` list to allow debugging info from any IP
+    - on Varnish 7, enable logging of access control list matching for both `invalidators` and `debuggers` lists
+      (new Varnish 7 syntax, it was enabled by default on previous versions)
+3. Sets main `varnish*.vcl` file to use and "path to VCL directory" argument name depending on Varnish version
+4. Copies the main VCL file to `.ddev/varnish/`
+5. Sets the Varnish version to use and its demon starting parameters to use the files
+6. Adds the Varnish container
+7. Sets Varnish as the HTTP cache server
+8. Restarts the DDEV cluster and clear the Ibexa DXP cache
+
+```bash
+VARNISH_VERSION=7.1
+mkdir -p .ddev/varnish
+sed 's/.host = "127.0.0.1";/.host = "web";/' vendor/ibexa/http-cache/docs/varnish/vcl/parameters.vcl > .ddev/varnish/parameters.vcl
+sed -i '/^acl invalidators {$/a \\    "web";' .ddev/varnish/parameters.vcl
+sed -i '/^acl debuggers {$/a \\    "0.0.0.0"/0; \/\/ debug from any IP' .ddev/varnish/parameters.vcl
+if [[ $VARNISH_VERSION == 7.* ]]; then
+  sed -i 's/acl invalidators {/acl invalidators +log {/' .ddev/varnish/parameters.vcl
+  sed -i 's/acl debuggers {/acl debuggers +log {/' .ddev/varnish/parameters.vcl
+  vcl_path=vcl_path
+  vcl_file=varnish7.vcl
+elif [[ $VARNISH_VERSION == 6.* ]]
+  vcl_path=vcl_dir
+  vcl_file=varnish6.vcl
+elif [[ $VARNISH_VERSION == 5.* ]]
+  vcl_path=vcl_dir
+  vcl_file=varnish5.vcl
+fi
+cp vendor/ibexa/http-cache/docs/varnish/vcl/$vcl_file .ddev/varnish/
+ddev dotenv set .ddev/.env.varnish --varnish-docker-image=varnish:$VARNISH_VERSION --varnish-varnishd-params " -p $vcl_path=/etc/varnish -f /etc/varnish/$vcl_file"
+
+ddev get ddev/ddev-varnish
+
+ddev config --web-environment-add HTTPCACHE_PURGE_SERVER=http://varnish
+ddev config --web-environment-add HTTPCACHE_PURGE_TYPE=varnish
+ddev config --web-environment-add TRUSTED_PROXIES=varnish
+
+ddev restart
+ddev php bin/console cache:clear
+```
+
+To use Varnish 6.0LTS, set the following variable instead:
+
+```bash
+VARNISH_VERSION=6.0
+
+If you're using [Apache as web server](install_with_ddev.md#switch-to-apache-and-its-virtual-host),
+you must set `varnish` as a trusted proxy in `.ddev/apache/apache-site.conf` before restarting DDEV:
+
+```bash
+sed -i 's/#SetEnv TRUSTED_PROXIES ""/SetEnv TRUSTED_PROXIES "varnish"/' .ddev/apache/apache-site.conf
+
+ddev restart
+```
+
+The Varnish server replace the web server in some places.
+If you run `ddev describe`, you can see that Varnish is now the one responding to DDEV domain `.ddev.site`
+while the web server still replies to `127.0.0.1` with its own ports.
+
+You can see Varnish headers in HTTP responses, for example:
+
+```console
+% curl -s -c cookies.txt -b cookies.txt -I https://<your-project>.ddev.site:<https-port>/
+HTTP/2 200 
+server: Apache/2.4.65 (Debian)
+vary: Origin,X-Editorial-Mode
+via: 1.1 varnish (Varnish/7.1)
+x-cache: HIT
+x-cache-debug: 1
+x-cache-hits: 5
+x-cache-ttl: 87654.321
+x-debug-token: 012345
+x-debug-token-link: https://ddev-ibexa-tmp2.ddev.site:8443/_profiler/012345
+x-powered-by: Ibexa Commerce v5
+x-robots-tag: noindex
+x-varnish: 12345 67890
+xkey: ez-all c52 ct42 l2 pl1 p1 p2
+content-length: 45678
+```
+
+You can see how the `web` server is responding to `varnish`:
+
+```console
+% curl -s -H "Surrogate-Capability: abc=ESI/1.0" http://127.0.0.1:<http-web-port>/product-catalog | grep 'esi:include'
+            <esi:include src="/_fragment?_hash=…
+```
+
+You can use `ddev varnishlog` command to monitor Varnish logs in real time.
+Due to how parameters are passed to the container, you may have to wrap some parameters in quotes twice, for example, the purge request monitoring:
+
+```bash
+ddev varnishlog -q "'ReqMethod ~ PURGE.*'";
+```
+
+For more information on topics such as available configurations, command lines, or monitoring, see [ddev/ddev-varnish README](https://github.com/ddev/ddev-varnish).
+
+### Fastly
+
+For Fastly (as for [[[= product_name_connect =]]](https://doc.ibexa.co/projects/connect/en/latest/)), the instance must be visible from Internet.
+
+To use [ngrok](https://ngrok.com/) alongside [`ddev share`](https://docs.ddev.com/en/stable/users/topics/sharing/#using-ddev-share-easiest) is probably the easiest way to achieve this.
+
+Be careful when making a local development instance visible from Interne.
+For example,
+
+- close ngrok tunnels when not needed anymore,
+- don't communicate your ngrok URL to unintended people,
+- don't use it for live demo on shared screen,
+- don't store it on a Fastly or [[= product_name_connect =]] account used by external people…
+
 ## Install search engine
 
 A [search engine](search_engines.md) can be added to the cluster.