Fixes #897 - Add jemalloc memory allocator to docs

appendix/environment-variables.rst

@@ -56,6 +56,25 @@ S3_URL |package|
    Example for value:
    ``https://key:secret@s3.eu-central-1.amazonaws.com/zammad-storage-bucket?region=eu-central-1&force_path_style=true``
 
+LD_PRELOAD |package|
+   Default: unset (package installations set it to ``libjemalloc.so.2``
+   automatically if the jemalloc library is present on your system)
+
+   Preloads a shared library for all Zammad processes. Package installations
+   use it to enable jemalloc as memory allocator (see
+   :doc:`Memory Allocator </appendix/memory-allocator>`). This variable is
+   managed by the package install script and may be overwritten during
+   updates.
+
+ZAMMAD_USE_JEMALLOC |package|
+   Default: unset
+
+   Set to ``no`` to opt out of jemalloc as memory allocator. Takes
+   effect on the next package installation or upgrade (see
+   :doc:`Memory Allocator </appendix/memory-allocator>`). Unset it to opt
+   back in; any value other than ``no`` re-enables jemalloc on the next
+   package installation or upgrade.
+
 Zammad
 ------
 
@@ -362,6 +381,10 @@ will begin to emerge.
 Below settings may consume all available database connections. Please consider
 the :doc:`configure-database-server` for more information.
 
+jemalloc as memory allocator is active by default on package
+installations and reduces memory usage. See :doc:`Memory Allocator
+</appendix/memory-allocator>` for details.
+
 ZAMMAD_WEB_CONCURRENCY
    Default: unset
 

appendix/memory-allocator.rst

@@ -0,0 +1,58 @@
+Memory Allocator
+================
+
+Package installations use `jemalloc <https://jemalloc.net/>`_ as memory
+allocator for all Zammad Ruby processes, as recommended by Rails. This
+reduces memory usage and fragmentation. The package postinstall script
+preloads the jemalloc library automatically if it's present on your system.
+This happens on every package installation and upgrade.
+
+Docker installations have jemalloc always active (baked into the image).
+To opt out, override the environment variable with an empty value (e.g.
+``LD_PRELOAD=""`` in your compose or env file).
+
+Availability
+------------
+
+- Debian / Ubuntu: libjemalloc2 is installed automatically as package
+  dependency.
+- CentOS / RHEL: jemalloc is installed automatically from the EPEL
+  repository (already a Zammad dependency).
+- SLES: jemalloc is **not** installed automatically (only available via
+  SUSE Package Hub). If you install it manually with
+  ``zypper install jemalloc``, Zammad activates it automatically on the
+  next package installation or upgrade.
+
+Opt-Out and Opt-In
+------------------
+
+To opt out of using jemalloc:
+
+.. code-block:: console
+
+   $ zammad config:set ZAMMAD_USE_JEMALLOC=no
+
+This takes effect on the next package installation or upgrade. The
+postinstall script then removes the ``LD_PRELOAD`` variable entirely, so a
+pre-existing system value is respected. For immediate effect:
+
+.. code-block:: console
+
+   $ zammad config:unset LD_PRELOAD
+
+.. code-block:: console
+
+   $ sudo systemctl restart zammad
+
+To opt back in, unset the variable again (any value other than ``no``
+re-enables jemalloc on the next package installation or upgrade):
+
+.. code-block:: console
+
+   $ zammad config:unset ZAMMAD_USE_JEMALLOC
+
+To verify whether jemalloc is active, run:
+
+.. code-block:: console
+
+   $ zammad run ruby -e 'puts File.read("/proc/self/maps").match?(/jemalloc/) ? "jemalloc active" : "jemalloc NOT active"'

index.rst

@@ -103,5 +103,6 @@ Zammad System Documentation
    /appendix/single-sign-on
    /appendix/reporting-tools-thirdparty
    /appendix/redis
+   /appendix/memory-allocator
    /appendix/custom-kb-url
    /appendix/custom-kb-css

install/package.rst

@@ -50,6 +50,10 @@ some operating systems may require additional packages if not already installed.
 
          $ sudo dnf install curl epel-release
 
+Zammad uses `jemalloc <https://jemalloc.net/>`_ as memory allocator out of
+the box on Debian, Ubuntu, CentOS and RHEL. For SLES, opt-out and
+verification details, see :doc:`Memory Allocator </appendix/memory-allocator>`.
+
 2. Install Elasticsearch
 ^^^^^^^^^^^^^^^^^^^^^^^^
 

prerequisites/software.rst

@@ -145,6 +145,11 @@ automatically be installed with the Zammad-Package.
    | *However:* If you have to use ``bundle install`` for e.g. custom gems or
      development, you'll need to install it!
 
+On Debian/Ubuntu and CentOS/RHEL, the jemalloc memory allocator is
+installed automatically as dependency and preloaded by all Zammad Ruby
+processes. On SLES it's not installed automatically; see
+:doc:`Memory Allocator </appendix/memory-allocator>` for details.
+
 2.3 Database Server
 ^^^^^^^^^^^^^^^^^^^