Fixes #665 - Extended variable RAILS_TRUSTED_PROXIES

---------

Co-authored-by: Martin Gruner <[email protected]>

Author: ralf401

appendix/configure-env-vars.rst

@@ -1,16 +1,19 @@
 Configuration via Environment Variables
 =======================================
 
-Use these environment variables to configure Zammad's behavior at runtime.
+Use environment variables to configure Zammad's settings and configuration.
+If you installed Zammad via docker, there is an additional page describing
+:doc:`/install/docker-compose/environment`.
 
-.. note:: 🙋 **What's an environment variable, and how do I “use” it?**
+.. note:: **How to set an environment variable?**
 
-   Unfortunately, that question has a very long answer
-   that goes beyond the scope of this article.
-   How you set environment variables will depend on how you installed Zammad
-   (*e.g.,* source, package, or Docker).
+   It depends on how you installed Zammad (source, package, docker).
+   Either set it via ``zammad config`` command as you can see below, use your
+   system's way of setting variables via command line
+   (e.g. ``export VARIABLE=value)``, place an ``.env`` file in the directory or
+   even use a GUI like Portainer to define them for a docker installation.
 
-   But for package installations, here's a short answer:
+   Example for package installations:
 
    .. code-block:: sh
 
@@ -25,9 +28,6 @@ Use these environment variables to configure Zammad's behavior at runtime.
       $ zammad config:unset OPTION
       $ systemctl restart zammad
 
-   To learn more, do some googling on environment variables
-   and the shell environment (or execution environment) in Unix.
-
 .. important::
 
    While below options and remarks affect all installation types of Zammad,
@@ -112,6 +112,17 @@ ZAMMAD_WEBSOCKET_PORT
 
    Default: ``6042``
 
+RAILS_TRUSTED_PROXIES
+   This setting is important for the correct detection of client IP addresses
+   and features based on it, like rate limiting.
+
+   By default, Zammad trusts localhost proxies only. Any additional proxy servers
+   will have to be added here, by IP address (if static) or by host name.
+   Host names are resolved during the start of Zammad, so that a restart is required
+   whenever the IP address of a proxy server changes.
+
+   Default: ``127.0.0.1,::1``
+
 .. _performance_tuning:
 
 Performance Tuning
@@ -167,14 +178,6 @@ ZAMMAD_PROCESS_SCHEDULED_JOBS_WORKERS
    | Default: **unset**
    | Maximum number of workers: ``1``
 
-   .. danger::
-
-      Disable processing of scheduled jobs by setting
-      ``ZAMMAD_PROCESS_SCHEDULED_JOBS_DISABLE``.
-
-      Doing so on productive instances will draw important parts of your
-      instance not working. **WE STRONGLY** encourage against using this flag.
-
 ZAMMAD_PROCESS_DELAYED_JOBS_WORKERS
    How many processes should work on delayed jobs?
 
@@ -187,14 +190,6 @@ ZAMMAD_PROCESS_DELAYED_JOBS_WORKERS
 
    .. warning:: 🥵 **This option can be very CPU-intensive.**
 
-   .. danger::
-
-      Disable processing of delayed jobs by setting
-      ``ZAMMAD_PROCESS_DELAYED_JOBS_DISABLE``.
-
-      Doing so on productive instances will draw important parts of your
-      instance not working. **WE STRONGLY** encourage against using this flag.
-
 
 ZAMMAD_PROCESS_DELAYED_AI_JOBS_WORKERS
    How many instances of AI workers should run simultaneously. AI workers handle

install/docker-compose/environment.rst

@@ -38,6 +38,18 @@ Zammad
    * - ZAMMAD_FQDN
      - ``(unset)``
      - Set the :admin-docs:`FQDN </settings/system/base.html>` for your instance.
+   * - RAILS_TRUSTED_PROXIES
+     - ``127.0.0.1,::1``
+     - This setting is important for the correct detection of client IP addresses
+       and features based on it, like rate limiting.
+
+       By default, Zammad trusts localhost proxies only. Any additional proxy servers
+       will have to be added here, by IP address (if static) or by host name.
+       Host names are resolved during the start of Zammad, so that a restart is required
+       whenever the IP address of a proxy server changes.
+
+       Note that in docker context, Zammad may see the network gateway IP address instead of the
+       actual proxy server IP address, if it is placed in another network.
    * - ZAMMAD_WEB_CONCURRENCY
      - ``(unset)``
      - Allows spawning ``n`` workers to allow more simultaneous connections for
@@ -72,9 +84,6 @@ Zammad
 
        In case you applied :doc:`docker hardware resource limits </install/docker-compose/docker-compose-scenarios>`,
        the zammad-scheduler CPU setting should match the sum of all worker settings variables.
-   * - RAILS_TRUSTED_PROXIES
-     - ``['127.0.0.1', '::1']``
-     - By default Zammad trusts localhost proxies only.
    * - MEMCACHE_SERVERS
      - ``zammad-memcached:11211``
      - Provide your own Memcached instance to Zammad if you already have one.