From 2496c688355a26ea9d6a13c20ccfe4d96a65736b Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Fri, 10 Oct 2025 12:54:45 +0000 Subject: [PATCH 1/4] Changed structure, added ES9 instructions --- install/elasticsearch.rst | 381 +----------------- .../connect-configure-elasticsearch.rst | 172 ++++++++ .../elasticsearch/install-elasticsearch-7.rst | 198 +++++++++ .../elasticsearch/install-elasticsearch-9.rst | 154 +++++++ 4 files changed, 532 insertions(+), 373 deletions(-) create mode 100644 install/elasticsearch/connect-configure-elasticsearch.rst create mode 100644 install/elasticsearch/install-elasticsearch-7.rst create mode 100644 install/elasticsearch/install-elasticsearch-9.rst diff --git a/install/elasticsearch.rst b/install/elasticsearch.rst index caac1019..2d84dc59 100644 --- a/install/elasticsearch.rst +++ b/install/elasticsearch.rst @@ -1,381 +1,16 @@ -Set Up Elasticsearch -==================== - -Zammad's search function can be powered by Elasticsearch (which is **highly -recommended**). +Elasticsearch +============= .. include:: /install/includes/hosted-services.rst -.. note:: Some steps may be required depending on your Elasticsearch version and - configuration. See remarks in the configuration steps below. - -Step 1: Installation --------------------- - -Elasticsearch offers different versions. Currently, the versions 7, 8 and 9 -are supported by Zammad. For installation instructions, you should first and -foremost follow -`Elastic's installation documentation `_. -Use the dropdown in the top right corner to choose which version you want to -install. - -However, if you want go with Elasticsearch 7 (which is slightly easier to -install), you can find the consolidated installation steps below. -Be aware that the maintenance of version 7 might be stopped earlier than for -later versions, which also come with some additional security features. - -.. hint:: If you are installing Elasticsearch 8 or newer and want to follow our - standard configuration in step 2, make sure to copy/save the password which - is shown while installing Elasticsearch. - -.. tabs:: - - .. tab:: Ubuntu/Debian - - .. code-block:: console - - $ sudo apt install apt-transport-https sudo wget curl gnupg - - .. code-block:: console - - $ curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | \ - gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/elasticsearch.gpg> /dev/null - - .. tabs:: - - .. tab:: Deb822 format - - In this tab, the repository is added by using the - `deb822 format `_. - If you run a distribution which doesn't support it, use the legacy - format instead. - - .. code-block:: console - - $ printf "Types: deb - URIs: https://artifacts.elastic.co/packages/7.x/apt - Suites: stable - Components: main - Signed-By: /etc/apt/trusted.gpg.d/elasticsearch.gpg" | \ - sudo tee /etc/apt/sources.list.d/elastic-7.x.sources > /dev/null - - .. tab:: Legacy format - - .. code-block:: console - - $ echo "deb [signed-by=/etc/apt/trusted.gpg.d/elasticsearch.gpg] https://artifacts.elastic.co/packages/7.x/apt stable main"| \ - sudo tee -a /etc/apt/sources.list.d/elastic-7.x.list > /dev/null - - .. code-block:: console - - $ sudo apt update - - .. code-block:: console - - $ sudo apt install elasticsearch - - .. code-block:: console - - $ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment - - .. tab:: CentOS - - .. code-block:: console - - $ sudo rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch - - .. code-block:: console - - $ echo "[elasticsearch-7.x] - name=Elasticsearch repository for 7.x packages - baseurl=https://artifacts.elastic.co/packages/7.x/yum - gpgcheck=1 - gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch - enabled=1 - autorefresh=1 - type=rpm-md"| sudo tee /etc/yum.repos.d/elasticsearch-7.x.repo - - .. code-block:: console - - $ sudo yum install -y elasticsearch - - .. code-block:: console - - $ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment - - .. tab:: OpenSUSE - - .. code-block:: console - - $ sudo rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch - - .. code-block:: console - - $ echo "[elasticsearch-7.x] - name=Elasticsearch repository for 7.x packages - baseurl=https://artifacts.elastic.co/packages/7.x/yum - gpgcheck=1 - gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch - enabled=1 - autorefresh=1 - type=rpm-md"| sudo tee /etc/zypp/repos.d/elasticsearch-7.x.repo - - .. code-block:: console - - $ sudo zypper install elasticsearch - - .. code-block:: console - - $ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment - - .. tab:: Direct Download - - Find the latest release on the - `downloads page `_, - or see the - `installation guide `_ - for in-depth instructions. Ensure to also install the fitting - (and mandatory!) attachment plugin for Elasticsearch, if installing - version 7. - - Install the attachment plugin: - - .. code-block:: console - - $ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment - - Increase the virtual memory map limit: - - .. code-block:: console - - $ sudo sysctl -w vm.max_map_count=262144 - -After you installed Elasticsearch and its attachment plugin, -ensure to enable it by default and start it. - -.. code-block:: console - - $ sudo systemctl start elasticsearch - -.. code-block:: console - - $ sudo systemctl enable elasticsearch - -Step 2: Configuration ---------------------- - -Install ingest-plugin (only for Elasticsearch <= 7) - .. code-block:: console - - $ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment - -Increase virtual memory map limit - .. code-block:: console - - $ sudo sysctl -w vm.max_map_count=262144 - -Adjust ``/etc/elasticsearch/elasticsearch.yml`` - We use the following settings to optimize the performance of our Elasticsearch - servers. You may want to append that to your ``elasticsearch.yml`` as a useful - basic configuration. - - .. code-block:: text - - # /etc/elasticsearch/elasticsearch.yml - - # Tickets above this size (articles + attachments + metadata) - # may fail to be properly indexed (Default: 100mb). - # - # When Zammad sends tickets to Elasticsearch for indexing, - # it bundles together all the data on each individual ticket - # and issues a single HTTP request for it. - # Payloads exceeding this threshold will be truncated. - # - # Performance may suffer if it is set too high. - http.max_content_length: 400mb - - # Allows the engine to generate larger (more complex) search queries. - # Elasticsearch will raise an error or deprecation notice if this value is too low, - # but setting it too high can overload system resources (Default: 1024). - # - # Available in version 6.6+ only. - indices.query.bool.max_clause_count: 2000 - -Enable and start Elasticsearch - .. code-block:: console - - $ sudo systemctl start elasticsearch - - .. code-block:: console - - $ sudo systemctl enable elasticsearch - -.. _configure_zammad_with_elasticsearch: - -Step 3: Connecting Zammad with Elasticsearch --------------------------------------------- - -Before proceeding here, make sure to install Zammad before running below -commands, as this will fail otherwise. - -* Install from :doc:`package ` -* Install with :doc:`Docker ` (the default stack already includes Elasticsearch) - -.. note:: - This guide uses the ``zammad run`` command prefix in command line examples. - This prefix is only applicable to package installations. - Check the :doc:`console guide ` for more information. - -Elasticsearch URL - Set the Elasticsearch server address; adapt it to your scenario. - - Elasticsearch 7: - - .. code-block:: console - - $ zammad run rails r "Setting.set('es_url', 'http://localhost:9200')" - - Elasticsearch 8+: - - .. code-block:: console - - $ zammad run rails r "Setting.set('es_url', 'https://localhost:9200')" - - -Elasticsearch user and password (only for Elasticsearch >= 8) - Now you need your password which was shown during the installation. - - Set Elasticsearch user: - - .. code-block:: console - - $ zammad run rails r "Setting.set('es_user', 'elastic')" - - Set Elasticsearch password: - - .. code-block:: console - - $ zammad run rails r "Setting.set('es_password', '')" - -Add certificate to Zammad (only for Elasticsearch >= 8) - Show and copy the auto-generated certificate from Elasticsearch and add it - to Zammad. Make sure to copy/paste the delimiters - (e.g. ``-----BEGIN CERTIFICATE-----``) too. - - .. code-block:: console - - $ sudo cat /etc/elasticsearch/certs/http_ca.crt - - Go to the admin panel of Zammad and add your copied certificate under - :admin-docs:`SSL Certificates `. - - .. figure:: /images/install/elasticsearch/admin-certificate-management.png - :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). - - Without specifying CPU cores: - - .. code-block:: console - - $ zammad run rake zammad:searchindex:rebuild - - Example with specifying 8 CPU cores: - - .. code-block:: console - - $ zammad run rake zammad:searchindex:rebuild[8] - - -Optional settings ------------------ - -We collected some useful settings you may want to apply. For further -information please have a look at -`Elastic's documentation `_. - -.. tabs:: - - .. tab:: Index namespacing - - Useful when connecting multiple services or Zammad instances - to a single Elasticsearch server (to prevent name collisions during indexing). - - .. code-block:: console - - $ zammad run rails r "Setting.set('es_index', Socket.gethostname.downcase + '_zammad')" - - .. tab:: File-attachment indexing rules - - Zammad supports searching by the contents of file attachments, which means - Elasticsearch has to index those, too. Limiting such indexing can help - conserve system resources. - - Files with these extensions will not be indexed: - - .. code-block:: console - - $ zammad run rails r "Setting.set('es_attachment_ignore',\ - [ '.png', '.jpg', '.jpeg', '.mpeg', '.mpg', '.mov', '.bin', '.exe', '.box', '.mbox' ] )" - - Files larger than this size (in MB) will not be indexed: - - .. code-block:: console - - $ zammad run rails r "Setting.set('es_attachment_max_size_in_mb', 50)" - - .. tab:: Remote host - - Change your Elasticsearch URL if you have a separate Elasticsearch server. - Default is ``localhost``. - - .. code-block:: console - - $ zammad run rails r "Setting.set('es_url', 'https://example.com')" - - .. tab:: SSL Verification - - You can disable SSL verification, which is not recommended. Default is - ``true``. - - .. code-block:: console - - $ zammad run rails r "Setting.set('es_ssl_verify', false)" - - If you want to use custom certificates, you can find information about - how to use them in Zammad - :admin-docs:`here `. - - .. tab:: Asciifold - - By default, the - `Asciifold `_ - feature of Elasticsearch is enabled. This can be useful if you deal with - text which includes diacritics and/or umlauts. - - In case you need a more exact search, you can turn it off: - - .. code-block:: console +Zammad's search function can be powered by Elasticsearch (which is **highly +recommended**). - $ zammad run rails r "Setting.set('es_asciifolding', false)" -Appendix --------- .. toctree:: - :maxdepth: 0 - :titlesonly: + :maxdepth: 1 - elasticsearch/indexed-attributes - elasticsearch/troubleshooting + elasticsearch/install-elasticsearch-7 + elasticsearch/install-elasticsearch-9 + elasticsearch/connect-configure-elasticsearch diff --git a/install/elasticsearch/connect-configure-elasticsearch.rst b/install/elasticsearch/connect-configure-elasticsearch.rst new file mode 100644 index 00000000..44667094 --- /dev/null +++ b/install/elasticsearch/connect-configure-elasticsearch.rst @@ -0,0 +1,172 @@ +Connect and Configure Elasticsearch +=================================== + +.. _configure_zammad_with_elasticsearch: + +Connect Zammad with Elasticsearch +--------------------------------- + +Before proceeding here, make sure to install Zammad before running below +commands, as this will fail otherwise. + +* Install from :doc:`package <../package>` +* Install with :doc:`Docker <../docker-compose>` (the default stack already includes Elasticsearch) + +.. note:: + This guide uses the ``zammad run`` command prefix in command line examples. + This prefix is only applicable to package installations. + Check the :doc:`console guide ` for more information. + +Elasticsearch URL + Set the Elasticsearch server address; adapt it to your scenario. + + Elasticsearch 7: + + .. code-block:: console + + $ zammad run rails r "Setting.set('es_url', 'http://localhost:9200')" + + Elasticsearch 8+: + + .. code-block:: console + + $ zammad run rails r "Setting.set('es_url', 'https://localhost:9200')" + + +Elasticsearch user and password (only for Elasticsearch >= 8) + Now you need your password which was shown during the installation. + + Set Elasticsearch user: + + .. code-block:: console + + $ zammad run rails r "Setting.set('es_user', 'elastic')" + + Set Elasticsearch password: + + .. code-block:: console + + $ zammad run rails r "Setting.set('es_password', '')" + +Add certificate to Zammad (only for Elasticsearch >= 8) + Show and copy the auto-generated certificate from Elasticsearch and add it + to Zammad. Make sure to copy/paste the delimiters + (e.g. ``-----BEGIN CERTIFICATE-----``) too. + + .. code-block:: console + + $ sudo cat /etc/elasticsearch/certs/http_ca.crt + + Go to the admin panel of Zammad and add your copied certificate under + :admin-docs:`SSL Certificates `. + + .. figure:: /images/install/elasticsearch/admin-certificate-management.png + :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). + + Without specifying CPU cores: + + .. code-block:: console + + $ zammad run rake zammad:searchindex:rebuild + + Example with specifying 8 CPU cores: + + .. code-block:: console + + $ zammad run rake zammad:searchindex:rebuild[8] + + +Optional settings +----------------- + +We collected some useful settings you may want to apply. For further +information please have a look at +`Elastic's documentation `_. + +.. tabs:: + + .. tab:: Index namespacing + + Useful when connecting multiple services or Zammad instances + to a single Elasticsearch server (to prevent name collisions during indexing). + + .. code-block:: console + + $ zammad run rails r "Setting.set('es_index', Socket.gethostname.downcase + '_zammad')" + + .. tab:: File-attachment indexing rules + + Zammad supports searching by the contents of file attachments, which means + Elasticsearch has to index those, too. Limiting such indexing can help + conserve system resources. + + Files with these extensions will not be indexed: + + .. code-block:: console + + $ zammad run rails r "Setting.set('es_attachment_ignore',\ + [ '.png', '.jpg', '.jpeg', '.mpeg', '.mpg', '.mov', '.bin', '.exe', '.box', '.mbox' ] )" + + Files larger than this size (in MB) will not be indexed: + + .. code-block:: console + + $ zammad run rails r "Setting.set('es_attachment_max_size_in_mb', 50)" + + .. tab:: Remote host + + Change your Elasticsearch URL if you have a separate Elasticsearch server. + Default is ``localhost``. + + .. code-block:: console + + $ zammad run rails r "Setting.set('es_url', 'https://example.com')" + + .. tab:: SSL Verification + + You can disable SSL verification, which is not recommended. Default is + ``true``. + + .. code-block:: console + + $ zammad run rails r "Setting.set('es_ssl_verify', false)" + + If you want to use custom certificates, you can find information about + how to use them in Zammad + :admin-docs:`here `. + + .. tab:: Asciifold + + By default, the + `Asciifold `_ + feature of Elasticsearch is enabled. This can be useful if you deal with + text which includes diacritics and/or umlauts. + + In case you need a more exact search, you can turn it off: + + .. code-block:: console + + $ zammad run rails r "Setting.set('es_asciifolding', false)" + +Appendix +-------- + +.. toctree:: + :maxdepth: 0 + :titlesonly: + + indexed-attributes + troubleshooting diff --git a/install/elasticsearch/install-elasticsearch-7.rst b/install/elasticsearch/install-elasticsearch-7.rst new file mode 100644 index 00000000..eaea078e --- /dev/null +++ b/install/elasticsearch/install-elasticsearch-7.rst @@ -0,0 +1,198 @@ +Install Elasticsearch 7 +======================= + +This guide shows a simple standard installation of Elasticsearch 7. The +intention is to get you up and running quickly. However, in case you +need a more advanced configuration or face any issues, have a look at +the `official Elasticsearch installation +documentation `__. +Adapt it wherever needed in case your use-case differs. + +You can find the consolidated installation steps below. +Be aware that the maintenance of version 7 might be stopped earlier than for +later versions, which also come with some additional security features. + +Installation +------------ + +.. tabs:: + + .. tab:: Ubuntu/Debian + + .. code-block:: console + + $ sudo apt install apt-transport-https sudo wget curl gnupg + + .. code-block:: console + + $ curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | \ + gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/elasticsearch.gpg> /dev/null + + .. tabs:: + + .. tab:: Deb822 format + + In this tab, the repository is added by using the + `deb822 format `_. + If you run a distribution which doesn't support it, use the legacy + format instead. + + .. code-block:: console + + $ printf "Types: deb + URIs: https://artifacts.elastic.co/packages/7.x/apt + Suites: stable + Components: main + Signed-By: /etc/apt/trusted.gpg.d/elasticsearch.gpg" | \ + sudo tee /etc/apt/sources.list.d/elastic-7.x.sources > /dev/null + + .. tab:: Legacy format + + .. code-block:: console + + $ echo "deb [signed-by=/etc/apt/trusted.gpg.d/elasticsearch.gpg] https://artifacts.elastic.co/packages/7.x/apt stable main"| \ + sudo tee -a /etc/apt/sources.list.d/elastic-7.x.list > /dev/null + + .. code-block:: console + + $ sudo apt update + + .. code-block:: console + + $ sudo apt install elasticsearch + + .. code-block:: console + + $ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment + + .. tab:: CentOS + + .. code-block:: console + + $ sudo rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch + + .. code-block:: console + + $ echo "[elasticsearch-7.x] + name=Elasticsearch repository for 7.x packages + baseurl=https://artifacts.elastic.co/packages/7.x/yum + gpgcheck=1 + gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch + enabled=1 + autorefresh=1 + type=rpm-md"| sudo tee /etc/yum.repos.d/elasticsearch-7.x.repo + + .. code-block:: console + + $ sudo yum install -y elasticsearch + + .. code-block:: console + + $ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment + + .. tab:: OpenSUSE + + .. code-block:: console + + $ sudo rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch + + .. code-block:: console + + $ echo "[elasticsearch-7.x] + name=Elasticsearch repository for 7.x packages + baseurl=https://artifacts.elastic.co/packages/7.x/yum + gpgcheck=1 + gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch + enabled=1 + autorefresh=1 + type=rpm-md"| sudo tee /etc/zypp/repos.d/elasticsearch-7.x.repo + + .. code-block:: console + + $ sudo zypper install elasticsearch + + .. code-block:: console + + $ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment + + .. tab:: Direct Download + + Find the latest release on the + `downloads page `_, + or see the + `installation guide `_ + for in-depth instructions. Ensure to also install the fitting + (and mandatory!) attachment plugin for Elasticsearch, if installing + version 7. + + Install the attachment plugin: + + .. code-block:: console + + $ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment + + Increase the virtual memory map limit: + + .. code-block:: console + + $ sudo sysctl -w vm.max_map_count=262144 + +After you installed Elasticsearch and its attachment plugin, +ensure to enable it by default and start it. + +.. code-block:: console + + $ sudo systemctl start elasticsearch + +.. code-block:: console + + $ sudo systemctl enable elasticsearch + +Configuration +------------- + +Install ingest-plugin (only for Elasticsearch <= 7) + .. code-block:: console + + $ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment + +Increase virtual memory map limit + .. code-block:: console + + $ sudo sysctl -w vm.max_map_count=262144 + +Adjust ``/etc/elasticsearch/elasticsearch.yml`` + We use the following settings to optimize the performance of our Elasticsearch + servers. You may want to append that to your ``elasticsearch.yml`` as a useful + basic configuration. + + .. code-block:: text + + # /etc/elasticsearch/elasticsearch.yml + + # Tickets above this size (articles + attachments + metadata) + # may fail to be properly indexed (Default: 100mb). + # + # When Zammad sends tickets to Elasticsearch for indexing, + # it bundles together all the data on each individual ticket + # and issues a single HTTP request for it. + # Payloads exceeding this threshold will be truncated. + # + # Performance may suffer if it is set too high. + http.max_content_length: 400mb + + # Allows the engine to generate larger (more complex) search queries. + # Elasticsearch will raise an error or deprecation notice if this value is too low, + # but setting it too high can overload system resources (Default: 1024). + # + # Available in version 6.6+ only. + indices.query.bool.max_clause_count: 2000 + +Enable and start Elasticsearch + .. code-block:: console + + $ sudo systemctl start elasticsearch + + .. code-block:: console + + $ sudo systemctl enable elasticsearch \ No newline at end of file diff --git a/install/elasticsearch/install-elasticsearch-9.rst b/install/elasticsearch/install-elasticsearch-9.rst new file mode 100644 index 00000000..2fcbacf1 --- /dev/null +++ b/install/elasticsearch/install-elasticsearch-9.rst @@ -0,0 +1,154 @@ +Install Elasticsearch 9 +======================= + +This guide shows a simple standard installation of Elasticsearch 9. The +intention is to get you up and running quickly. However, in case you +need a more advanced configuration or face any issues, have a look at +the `official Elasticsearch installation +documentation `__. +Adapt it wherever needed in case your use-case differs. + +Installation +------------ + +Download and Add the Public Signing Key +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. tabs:: + + .. tab:: Ubuntu/Debian + + Install required tools: + + .. code-block:: console + + $ sudo apt-get install apt-transport-https + + Add repo key: + + .. code-block:: console + + $ wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg + + .. tab:: OpenSUSE/SLES + + .. code-block:: console + + $ rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch + + .. tab:: CentOS/RHEL + + .. code-block:: console + + $ rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch + + +Add the Repository +^^^^^^^^^^^^^^^^^^ + +.. tabs:: + + .. tab:: Ubuntu/Debian + + .. code-block:: console + + $ echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/9.x/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-9.x.list + + .. tab:: OpenSUSE/SLES + + Create the file ``/etc/zypp/repos.d/elasticsearch.repo``and add: + + .. code-block:: text + + [elasticsearch] + name=Elasticsearch repository for 9.x packages + baseurl=https://artifacts.elastic.co/packages/9.x/yum + gpgcheck=1 + gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch + enabled=0 + autorefresh=1 + type=rpm-md + + .. tab:: CentOS/RHEL + + Create the file ``/etc/yum.repos.d/elasticsearch.repo``and add: + + .. code-block:: text + + [elasticsearch] + name=Elasticsearch repository for 9.x packages + baseurl=https://artifacts.elastic.co/packages/9.x/yum + gpgcheck=1 + gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch + enabled=0 + type=rpm-md + +Install Elasticsearch +^^^^^^^^^^^^^^^^^^^^^ + +.. tabs:: + + .. tab:: Ubuntu/Debian + + .. code-block:: console + + $ sudo apt-get update && sudo apt-get install elasticsearch + + .. tab:: OpenSUSE/SLES + + .. code-block:: console + + $ sudo zypper modifyrepo --enable elasticsearch && \ + sudo zypper install elasticsearch; \ + sudo zypper modifyrepo --disable elasticsearch + + .. tab:: CentOS/RHEL + + CentOS and RHEL 7 or earlier: + + .. code-block:: console + + $ sudo yum install --enablerepo=elasticsearch elasticsearch + + RHEL 8 and later: + + .. code-block:: console + + $ sudo dnf install --enablerepo=elasticsearch elasticsearch + +.. tip:: + + Make sure to check the output and to copy the password of the + built-in superuser. Otherwise, you have to recreate it by running + ``/usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic``. + +Configuration +------------- + +Open ``/etc/elasticsearch/elasticsearch.yml`` and adjust/uncomment the +following values: + +.. code-block:: yaml + + network.host: 0.0.0.0 + transport.host: 0.0.0.0 + +Optional to increase the maximum context size to index: + +.. code-block:: yaml + + http.max_content_length: 400mb + +Start and Enable Elasticsearch +------------------------------ + +.. code-block:: console + + $ sudo systemctl enable elasticsearch.service --now + +Next Steps +---------- + +Go on with the :doc:`installation of Zammad <../package>`. +After the installation of Zammad is completed, you can :doc:`connect Zammad +with Elasticsearch `. From b54b452663dcdac9a505d3344c71c66eca6e9145 Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Mon, 13 Oct 2025 09:14:59 +0000 Subject: [PATCH 2/4] Additional content and fixes --- install/elasticsearch.rst | 2 -- .../connect-configure-elasticsearch.rst | 16 +++++++++++++--- .../elasticsearch/install-elasticsearch-7.rst | 2 +- .../elasticsearch/install-elasticsearch-9.rst | 6 +++--- 4 files changed, 17 insertions(+), 9 deletions(-) diff --git a/install/elasticsearch.rst b/install/elasticsearch.rst index 2d84dc59..ccd0acf4 100644 --- a/install/elasticsearch.rst +++ b/install/elasticsearch.rst @@ -6,8 +6,6 @@ Elasticsearch Zammad's search function can be powered by Elasticsearch (which is **highly recommended**). - - .. toctree:: :maxdepth: 1 diff --git a/install/elasticsearch/connect-configure-elasticsearch.rst b/install/elasticsearch/connect-configure-elasticsearch.rst index 44667094..6adf9caa 100644 --- a/install/elasticsearch/connect-configure-elasticsearch.rst +++ b/install/elasticsearch/connect-configure-elasticsearch.rst @@ -42,13 +42,20 @@ Elasticsearch user and password (only for Elasticsearch >= 8) $ zammad run rails r "Setting.set('es_user', 'elastic')" - Set Elasticsearch password: + Set Elasticsearch password. Replace ```` with the one you got + during the installation of Elasticsearch. In case you need to create a new + password, run + ``/usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic``. .. code-block:: console $ zammad run rails r "Setting.set('es_password', '')" Add certificate to Zammad (only for Elasticsearch >= 8) + This step requires a running Zammad. If you are installing a new Zammad + instance, go on with the :doc:`installation <./package>` and come back here + when you can access the admin settings in the browser. + Show and copy the auto-generated certificate from Elasticsearch and add it to Zammad. Make sure to copy/paste the delimiters (e.g. ``-----BEGIN CERTIFICATE-----``) too. @@ -57,8 +64,11 @@ Add certificate to Zammad (only for Elasticsearch >= 8) $ sudo cat /etc/elasticsearch/certs/http_ca.crt - Go to the admin panel of Zammad and add your copied certificate under - :admin-docs:`SSL Certificates `. + To add it in Zammad, go to *Settings > Security > SSL Certificates* in the + :admin-docs:`admin settings ` and + add your copied certificate. Either upload the certificate file or paste the + content in the dialog. After saving the certificate, Zammad is now able to + connect to and access the Elasticsearch index. .. figure:: /images/install/elasticsearch/admin-certificate-management.png :alt: Screenshot shows certificate management in Zammad's admin panel diff --git a/install/elasticsearch/install-elasticsearch-7.rst b/install/elasticsearch/install-elasticsearch-7.rst index eaea078e..0c8130ad 100644 --- a/install/elasticsearch/install-elasticsearch-7.rst +++ b/install/elasticsearch/install-elasticsearch-7.rst @@ -6,7 +6,7 @@ intention is to get you up and running quickly. However, in case you need a more advanced configuration or face any issues, have a look at the `official Elasticsearch installation documentation `__. -Adapt it wherever needed in case your use-case differs. +Adapt it wherever needed if your use-case differs. You can find the consolidated installation steps below. Be aware that the maintenance of version 7 might be stopped earlier than for diff --git a/install/elasticsearch/install-elasticsearch-9.rst b/install/elasticsearch/install-elasticsearch-9.rst index 2fcbacf1..17cdfe8a 100644 --- a/install/elasticsearch/install-elasticsearch-9.rst +++ b/install/elasticsearch/install-elasticsearch-9.rst @@ -6,7 +6,7 @@ intention is to get you up and running quickly. However, in case you need a more advanced configuration or face any issues, have a look at the `official Elasticsearch installation documentation `__. -Adapt it wherever needed in case your use-case differs. +Adapt it wherever needed if your use-case differs. Installation ------------ @@ -56,7 +56,7 @@ Add the Repository .. tab:: OpenSUSE/SLES - Create the file ``/etc/zypp/repos.d/elasticsearch.repo``and add: + Create the file ``/etc/zypp/repos.d/elasticsearch.repo`` and add: .. code-block:: text @@ -71,7 +71,7 @@ Add the Repository .. tab:: CentOS/RHEL - Create the file ``/etc/yum.repos.d/elasticsearch.repo``and add: + Create the file ``/etc/yum.repos.d/elasticsearch.repo`` and add: .. code-block:: text From 187ae442686b43db65eb5bb82d8f67f358960e78 Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Mon, 13 Oct 2025 09:37:53 +0000 Subject: [PATCH 3/4] Final adjustments --- install/elasticsearch.rst | 12 +++++++++++- install/elasticsearch/install-elasticsearch-7.rst | 6 +++--- install/package.rst | 5 +++-- 3 files changed, 17 insertions(+), 6 deletions(-) diff --git a/install/elasticsearch.rst b/install/elasticsearch.rst index ccd0acf4..751451d7 100644 --- a/install/elasticsearch.rst +++ b/install/elasticsearch.rst @@ -6,8 +6,18 @@ Elasticsearch Zammad's search function can be powered by Elasticsearch (which is **highly recommended**). +The order for a package installation of Zammad is like this: + +1. :doc:`Install Elasticsearch (version 9 recommended) ` +2. :doc:`Install Zammad <./package>` +3. :doc:`Connect and configure Elasticsearch ` + +.. hint:: For a transition period, there is also a + :doc:`installation guide for Elasticsearch 7 ` available. + .. toctree:: - :maxdepth: 1 + :maxdepth: 0 + :hidden: elasticsearch/install-elasticsearch-7 elasticsearch/install-elasticsearch-9 diff --git a/install/elasticsearch/install-elasticsearch-7.rst b/install/elasticsearch/install-elasticsearch-7.rst index 0c8130ad..76850c71 100644 --- a/install/elasticsearch/install-elasticsearch-7.rst +++ b/install/elasticsearch/install-elasticsearch-7.rst @@ -8,9 +8,9 @@ the `official Elasticsearch installation documentation `__. Adapt it wherever needed if your use-case differs. -You can find the consolidated installation steps below. -Be aware that the maintenance of version 7 might be stopped earlier than for -later versions, which also come with some additional security features. +.. warning:: There are newer versions of Elasticsearch available. This guide + is just in place for a transition period. Consider the + :doc:`installation of Elasticsearch 9 ` instead. Installation ------------ diff --git a/install/package.rst b/install/package.rst index 49816420..b1724fa4 100644 --- a/install/package.rst +++ b/install/package.rst @@ -48,8 +48,9 @@ some operating systems may require additional packages if not already installed. ^^^^^^^^^^^^^^^^^^^^^^^^ Elasticsearch is not a hard dependency of Zammad, but strongly recommended! It -needs to be installed before Zammad. Please take a look at the -:doc:`instructions ` first. +needs to be installed before Zammad. Read on in the +:doc:`Elasticsearch section ` first and continue +with the next step after you finished the installation of it. 3. Ensure Correct Locale ^^^^^^^^^^^^^^^^^^^^^^^^ From 42bf0ef9ebf019ca3eb4c2b14bf69fad2119fa6d Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Tue, 14 Oct 2025 09:20:38 +0000 Subject: [PATCH 4/4] Changed ES version hints --- install/elasticsearch/connect-configure-elasticsearch.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/install/elasticsearch/connect-configure-elasticsearch.rst b/install/elasticsearch/connect-configure-elasticsearch.rst index 6adf9caa..69139eb7 100644 --- a/install/elasticsearch/connect-configure-elasticsearch.rst +++ b/install/elasticsearch/connect-configure-elasticsearch.rst @@ -26,14 +26,14 @@ Elasticsearch URL $ zammad run rails r "Setting.set('es_url', 'http://localhost:9200')" - Elasticsearch 8+: + Elasticsearch 8 and newer: .. code-block:: console $ zammad run rails r "Setting.set('es_url', 'https://localhost:9200')" -Elasticsearch user and password (only for Elasticsearch >= 8) +Elasticsearch user and password (Elasticsearch 8 and newer) Now you need your password which was shown during the installation. Set Elasticsearch user: @@ -51,9 +51,9 @@ Elasticsearch user and password (only for Elasticsearch >= 8) $ zammad run rails r "Setting.set('es_password', '')" -Add certificate to Zammad (only for Elasticsearch >= 8) +Add certificate to Zammad (Elasticsearch 8 and newer) This step requires a running Zammad. If you are installing a new Zammad - instance, go on with the :doc:`installation <./package>` and come back here + instance, go on with the :doc:`installation <../package>` and come back here when you can access the admin settings in the browser. Show and copy the auto-generated certificate from Elasticsearch and add it