Fixes #619 - Added Elasticsearch index rebuild and a note about the consequences

Author: ralf401

admin/console.rst

@@ -31,13 +31,25 @@ a shell (e.g. for automation).
    (e.g. like ``rails r 'p Delayed::Job.count'``),
    you'll actually receive a printed output (without you won't!).
 
-.. code-block:: sh
+.. tabs::
 
-   # package installation
-   $ zammad run rails r '{COMMAND}'
+   .. tab:: Docker Installation
 
-   # source installation
-   $ rails r '{COMMAND}'
+      .. code-block:: sh
+
+         $ docker compose run --rm zammad-railsserver rails r '{COMMAND}'
+
+   .. tab:: Package Installation
+
+      .. code-block:: sh
+
+         $ zammad run rails r '{COMMAND}'
+
+   .. tab:: Source/Development Installation
+
+      .. code-block:: sh
+
+         $ rails r '{COMMAND}'
 
 .. _rails_shell:
 
@@ -47,9 +59,29 @@ Running Several Commands in a Shell
 The following command will provide you a rails console.
 It allows you to run several commands inside it.
 
-This reduces loading times greatly.
+.. tabs::
+
+   .. tab:: Docker Installation
+
+      .. code-block:: sh
+
+         $ docker compose run --rm zammad-railsserver rails c
+
+      .. tip:: If you use Portainer to manage your Docker containers,
+         you can even use a
+         :ref:`console via Portainer's GUI <docker-run-commands>`.
+
+   .. tab:: Package Installation
+
+      .. code-block:: sh
+
+         $ $ zammad run rails c
+
+   .. tab:: Source/Development Installation
+
+      .. code-block:: sh
 
-.. include:: /admin/console-rails-shell.include.rst
+         $ rails c
 
 .. hint:: **Starting Rails Console in Safe Mode**
 

install/docker-compose.rst

@@ -134,6 +134,8 @@ To adjust the stack and settings, use
    /install/docker-compose/docker-compose-scenarios
 
 
+.. _docker-run-commands:
+
 How to Run Commands in the Stack
 --------------------------------
 

install/elasticsearch.rst

@@ -220,7 +220,18 @@ Add certificate to Zammad (only for Elasticsearch >= 8)
       :alt: Screenshot shows certificate management in Zammad's admin panel
       :align: center
 
+.. _es-rebuild-searchindex:
+
 Build/rebuild the searchindex
+   .. hint::
+      - The rebuild may take many hours or even days, if a lot of data is
+        already present in a productive environment. However, you can safely
+        run this during operating times without the risk of loosing data. As a
+        downside, it could lead to reduced performance and that some data may
+        not be shown in search results.
+      - Consider specifying a number of CPU cores to be used for the rebuild
+        (see example below).
+
    .. code-block:: sh
 
       $ sudo zammad run rake zammad:searchindex:rebuild

install/update.rst

@@ -100,9 +100,22 @@ using `Zammad hosting`_ for your and your customers' safety.
             ingest-attachment is no longer a plugin, it's now included in
             Elasticsearch).
 
-      Step 6: Log into Zammad
+      Step 6: Rebuild Elasticsearch index (optional)
+         Only needed if the release note tells you to rebuild the Elasticsearch
+         index.
+
+         .. code-block:: sh
+
+            $ zammad run rake zammad:searchindex:rebuild
+
+            # Optionally, you can specify a number of CPU cores which are used for
+            # rebuilding the searchindex, as in the following example with 8 cores:
+            $ zammad run rake zammad:searchindex:rebuild[8]
+
+      Step 7: Log into Zammad
          Yes, that's it!
 
+
    .. tab:: Source
 
       Step 1: Ensure dependencies
@@ -186,9 +199,22 @@ using `Zammad hosting`_ for your and your customers' safety.
       Step 9: Start Zammad services
          Start the application server, web socket server and scheduler.
 
-      Step 10: Log into Zammad
+      Step 10: Rebuild Elasticsearch index (optional)
+         Only needed if the release note tells you to rebuild the Elasticsearch
+         index.
+
+         .. code-block:: sh
+
+            $ rake zammad:searchindex:rebuild
+
+            # Optionally, you can specify a number of CPU cores which are used for
+            # rebuilding the searchindex, as in the following example with 8 cores:
+            $ rake zammad:searchindex:rebuild[8]
+
+      Step 11: Log into Zammad
          Yes, that's it!
 
+
    .. tab:: Docker
 
       .. hint::
@@ -212,3 +238,30 @@ using `Zammad hosting`_ for your and your customers' safety.
             $ docker-compose pull
             $ docker-compose up -d
 
+      Rebuild Elasticsearch index (optional)
+         Only needed if the release note tells you to rebuild the Elasticsearch
+         index.
+
+         **Docker compose:**
+
+         .. code-block:: sh
+
+            $ docker compose run --rm zammad-railsserver rails r rake zammad:searchindex:rebuild
+
+            # Optionally, you can specify a number of CPU cores which are used for
+            # rebuilding the searchindex, as in the following example with 8 cores:
+            $ docker compose run --rm zammad-railsserver rails r rake zammad:searchindex:rebuild[8]
+
+         **Portainer:**
+
+         Open the :ref:`console via Portainer's GUI <docker-run-commands>`
+         (but use the entrypoint ``bash-via-entrypoint: /docker-entrypoint.sh /bin/bash``
+         instead) and run:
+
+         .. code-block:: sh
+
+            $ rake zammad:searchindex:rebuild
+
+            # Optionally, you can specify a number of CPU cores which are used for
+            # rebuilding the searchindex, as in the following example with 8 cores:
+            $ rake zammad:searchindex:rebuild[8]