docs: Clarify use of `loadbalancer.ips` when using a reverse proxy.

When Zulip is run behind one or more reverse proxies, you must
configure `loadbalancer.ips` so that Zulip respects the client IP
addresses found in the `X-Forwarded-For` header. This is not
immediately clear from the documentation, so this commit makes it more
clear and augments the existing examples to showcase this need.

Fixes: #19073

docs/production/deployment.md

@@ -306,6 +306,33 @@ HTTP as follows:
 1. Finally, restart the Zulip server, using
    `/home/zulip/deployments/current/scripts/restart-server`.
 
+#### Configuring Zulip to trust proxies
+
+Before placing Zulip behind a reverse proxy, it needs to be configured to trust
+the client IP addresses that the proxy reports. This is important to have
+accurate IP addresses in server logs, as well as in notification emails which
+are sent to end users.
+
+1. Determine the IP addresses of all reverse proxies you are setting up, as seen
+   from the Zulip host. Depending on your network setup, these may not be the
+   same as the public IP addresses of the reverse proxies.
+
+1. Add the following block to `/etc/zulip/zulip.conf`.
+
+   ```ini
+   [loadbalancer]
+   # Use the IP addresses you determined above, separated by commas.
+   ips = 192.168.0.100
+   ```
+
+1. Reconfigure Zulip with these settings. As root, run
+   `/home/zulip/deployments/current/scripts/zulip-puppet-apply`. This will
+   adjust Zulip's `nginx` configuration file to accept the `X-Forwarded-For`
+   header when it is sent from one of the reverse proxy IPs.
+
+1. Finally, restart the Zulip server, using
+   `/home/zulip/deployments/current/scripts/restart-server`.
+
 ### nginx configuration
 
 For `nginx` configuration, there's two things you need to set up:
@@ -342,6 +369,10 @@ Don't forget to update `server_name`, `ssl_certificate`,
 `ssl_certificate_key` and `proxy_pass` with the appropriate values for
 your installation.
 
+On the Zulip side, you will need to add the `nginx` server IP as a trusted
+reverse proxy. Follow the instructions to [configure Zulip to trust
+proxies](#configuring-zulip-to-trust-proxies).
+
 [nginx-proxy-longpolling-config]: https://github.com/zulip/zulip/blob/main/puppet/zulip/files/nginx/zulip-include-common/proxy_longpolling
 [standalone.pp]: https://github.com/zulip/zulip/blob/main/puppet/zulip/manifests/profile/standalone.pp
 [zulipchat-puppet]: https://github.com/zulip/zulip/tree/main/puppet/zulip_ops/manifests
@@ -364,7 +395,11 @@ make the following changes in two configuration files.
 
 3. Restart your Zulip server with `/home/zulip/deployments/current/scripts/restart-server`.
 
-4. Create an Apache2 virtual host configuration file, similar to the
+4. Follow the instructions to [configure Zulip to trust
+   proxies](#configuring-zulip-to-trust-proxies). For this example, the reverse
+   proxy IP would be `127.0.0.1`.
+
+5. Create an Apache2 virtual host configuration file, similar to the
    following. Place it the appropriate path for your Apache2
    installation and enable it (E.g. if you use Debian or Ubuntu, then
    place it in `/etc/apache2/sites-available/zulip.example.com.conf`
@@ -422,7 +457,9 @@ backend zulip
 
 Since this configuration uses the `http` mode, you will also need to
 [configure Zulip to allow HTTP](#configuring-zulip-to-allow-http) as
-described above.
+described above. Additionally, you will need to [add the the HAProxy server IP
+address as a trusted load balancer](#configuring-zulip-to-trust-proxies)
+to have Zulip respect the addresses in `X-Forwarded-For` headers.
 
 ### Other proxies
 
@@ -431,7 +468,9 @@ things you need to be careful about when configuring it:
 
 1. Configure your reverse proxy (or proxies) to correctly maintain the
    `X-Forwarded-For` HTTP header, which is supposed to contain the series
-   of IP addresses the request was forwarded through. You can verify
+   of IP addresses the request was forwarded through. Additionally,
+   [configure Zulip to respect the addresses sent by your reverse
+   proxies](#configuring-zulip-to-trust-proxies). You can verify
    your work by looking at `/var/log/zulip/server.log` and checking it
    has the actual IP addresses of clients, not the IP address of the
    proxy server.