Skip to content

Commit

Permalink
Fixes #497 - Update package and elasticsearch installation instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
@ralf401
ralf401 committed Jun 28, 2024
1 parent 3c9a98b commit 12a71e6
Show file tree
Hide file tree
Showing 6 changed files with 213 additions and 302 deletions.
176 changes: 41 additions & 135 deletions install/elasticsearch.rst
View file
Original file line number Diff line number Diff line change
@@ -1,128 +1,33 @@
Set up Elasticsearch
********************

Zammad's search function is powered by Elasticsearch, and requires the
`ingest attachment plugin <https://www.elastic.co/guide/en/elasticsearch/plugins/current/ingest-attachment.html>`_.
Zammad's search function can be powered by Elasticsearch (which is **highly
recommended**).

This guide uses the ``zammad run`` command prefix in command line examples.
This prefix is only applicable to package installations
(*i.e.,* via apt/yum/zypper, or ``.deb``/``.rpm`` files).

If you installed from source, be sure to omit this prefix
and run the bare ``rails ...`` or ``rake ...`` commands instead.
If these manual steps aren't what you are looking for, consider a `hosted Zammad
setup <https://zammad.com/en/pricing>`_ or :doc:`deploy Zammad via Docker </install/docker-compose>`.

Step 1: Installation
====================

Starting with Zammad 4.0, our packages allow you to decide whether to use
``elasticsearch`` or ``elasticsearch-oss``.

``elasticsearch-oss`` users please use below "direct download" tab for
further installation steps.

.. warning::

Above does not apply to CentOS because of compatibility reasons.

.. tabs::

.. tab:: Ubuntu

::

$ apt install apt-transport-https sudo wget curl gnupg
$ echo "deb [signed-by=/etc/apt/trusted.gpg.d/elasticsearch.gpg] https://artifacts.elastic.co/packages/7.x/apt stable main"| \
tee -a /etc/apt/sources.list.d/elastic-7.x.list > /dev/null
$ curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | \
gpg --dearmor | tee /etc/apt/trusted.gpg.d/elasticsearch.gpg> /dev/null
$ apt update
$ apt install elasticsearch
$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment

.. tab:: Debian

::

$ apt install apt-transport-https sudo wget curl gnupg
$ echo "deb [signed-by=/etc/apt/trusted.gpg.d/elasticsearch.gpg] https://artifacts.elastic.co/packages/7.x/apt stable main"| \
tee -a /etc/apt/sources.list.d/elastic-7.x.list > /dev/null
$ curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | \
gpg --dearmor | tee /etc/apt/trusted.gpg.d/elasticsearch.gpg> /dev/null
$ apt update
$ apt install elasticsearch
$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment

.. tab:: CentOS

::

$ rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch
$ 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"| tee /etc/yum.repos.d/elasticsearch-7.x.repo
$ yum install -y elasticsearch
$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment

.. tab:: OpenSUSE

::

$ rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch
$ 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"| tee /etc/zypp/repos.d/elasticsearch-7.x.repo
$ zypper install elasticsearch
$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment

.. tab:: Direct Download

Find the latest release on the
`downloads page <https://www.elastic.co/downloads/elasticsearch>`_,
or see the
`installation guide <https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html>`_
for in-depth instructions. Ensure to also install the fitting
(and mandatory!) attachment plugin for elasticsearch.

If you prefer the Open Source version of Elasticsearch, please use the
`Elasticsearch-OSS <https://www.elastic.co/downloads/past-releases#elasticsearch-oss>`_
download page.
Zammad allows you to use **elasticsearch** or **elasticsearch-oss**.
For installation instructions please follow
`Elastic's installation instructions <https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html>`_.

.. code-block:: sh
# Install the attachment plugin
$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
# Increase the virtual memory map limit
$ sysctl -w vm.max_map_count=262144
After you installed Elasticsearch and its attachment plugin,
ensure to enable it by default and start it.
Step 2: Configuration
=====================

.. code-block:: sh
$ systemctl start elasticsearch
$ systemctl enable elasticsearch
.. note:: 🐋 **Docker installations on macOS/Windows:**
# Install the ingest-attachment plugin manually, if running ES 7 or older
$ sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
Setting the ``vm.max_map_count`` kernel parameter requires
`additional steps <https://www.elastic.co/guide/en/elasticsearch/reference/master/docker.html#_set_vm_max_map_count_to_at_least_262144s>`_.

Step 2: Suggested Configuration
===============================
# Increase the virtual memory map limit
$ sudo sysctl -w vm.max_map_count=262144
We use the following settings to optimize the performance of our Elasticsearch
servers. Your mileage may vary.
servers. You may want to append that to your ``elasticsearch.yml`` as a useful
basic configuration.

.. code-block:: sh
Expand All @@ -146,8 +51,13 @@ servers. Your mileage may vary.
# Available in version 6.6+ only.
indices.query.bool.max_clause_count: 2000
.. note:: For more information on the ``indices.query.bool.max_clause_count`` setting,
see the `Elasticsearch 6.6 release notes <https://www.elastic.co/guide/en/elasticsearch/reference/6.8/breaking-changes-6.6.html#_literal_query_string_literal_literal_multi_match_literal_and_literal_simple_query_string_literal_query>`_.
After installation and configuration, ensure to enable Elasticsearch
by default and start it:

.. code-block:: sh
$ systemctl start elasticsearch
$ systemctl enable elasticsearch
.. _configure_zammad_with_elasticsearch:

Expand All @@ -157,29 +67,35 @@ Step 3: Connect Zammad
Before proceeding here, make sure to install Zammad before running below
commands, as this will fail otherwise.

* install from :doc:`package <package>`
* install from :doc:`source <source>`
* install from :doc:`package <package>`
* install from :doc:`source <source>`

.. note::
This guide uses the ``zammad run`` command prefix in command line examples.
This prefix is only applicable to package installations.
If you installed from source, be sure to omit this prefix
and run the bare ``rails ...`` or ``rake ...`` commands instead.

.. code-block:: sh
# Set the Elasticsearch server address
$ zammad run rails r "Setting.set('es_url', 'http://localhost:9200')"
# It has to be https starting with ES8
$ sudo zammad run rails r "Setting.set('es_url', 'http://localhost:9200')"
# Build the search index
$ zammad run rake zammad:searchindex:rebuild
$ sudo 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]
Starting with Elasticsearch 8+, you need to use a HTTPS URL in
'es_url' as 'https://localhost:9200' and configure an
authentication (see HTTP Basic below).

$ sudo 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 <https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html>`_.

.. tabs::

.. tab:: Authentication
Expand All @@ -190,13 +106,6 @@ Optional settings
$ zammad run rails r "Setting.set('es_user', '<username>')"
$ zammad run rails r "Setting.set('es_password', '<password>')"
.. hint:: 🤔 **How do I set up authentication on my Elasticsearch server?**

Elasticsearch provides many different authentication methods.
Some of them may require paid X-Pack, please check the
`elastic documentation <https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-up-authentication.html>`_
for more information.

.. tab:: Index namespacing

Useful when connecting multiple services or Zammad instances
Expand Down Expand Up @@ -241,12 +150,9 @@ Optional settings
# Deactivating SSL verification is NOT recommended
$ zammad run rails r "Setting.set('es_ssl_verify', false)"
.. hint:: 🤔 **But how to handle an Elasticsearch server with custom
certificates?**

You can import custom certificates and custom CA certificates to
Zammad. Please have a look
:admin-docs:`in the admin documentation </settings/security/ssl-certificates.html>`.
If you want to use custom certificates, you can find information about
how to use them in Zammad
:admin-docs:`here </settings/security/ssl-certificates.html>`.

Appendix
========
Expand Down
30 changes: 15 additions & 15 deletions install/includes/firewall-and-selinux.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,11 @@ SELinux
.. code-block:: sh
$ # Allow nginx or apache to access public files of Zammad and communicate
$ chcon -Rv --type=httpd_sys_content_t /opt/zammad/public/
$ setsebool httpd_can_network_connect on -P
$ semanage fcontext -a -t httpd_sys_content_t /opt/zammad/public/
$ restorecon -Rv /opt/zammad/public/
$ chmod -R a+r /opt/zammad/public/
$ sudo chcon -Rv --type=httpd_sys_content_t /opt/zammad/public/
$ sudo setsebool httpd_can_network_connect on -P
$ sudo semanage fcontext -a -t httpd_sys_content_t /opt/zammad/public/
$ sudo restorecon -Rv /opt/zammad/public/
$ sudo chmod -R a+r /opt/zammad/public/
.. tab:: OpenSUSE

Expand All @@ -39,9 +39,9 @@ Firewall
.. code-block:: sh
$ # Open Port 80 and 443 on your Firewall
$ ufw allow 80
$ ufw allow 443
$ ufw reload
$ sudo ufw allow 80
$ sudo ufw allow 443
$ sudo ufw reload
.. tab:: Debian

Expand All @@ -57,8 +57,8 @@ Firewall
.. code-block::
# Open Port 80 and 443 for Zammad
tcp dport { http, https } accept
udp dport { http, https } accept
sudo tcp dport { http, https } accept
sudo udp dport { http, https } accept
The result should look like the following. Keep in mind that your
enviroment could require different / more rules.
Expand Down Expand Up @@ -86,16 +86,16 @@ Firewall
}
}
To load your new rules, simply run ``systemctl reload nftables``.
To load your new rules, simply run ``sudo systemctl reload nftables``.

.. tab:: CentOS

.. code-block:: sh
$ # Open Port 80 and 443 on your Firewall
$ firewall-cmd --zone=public --add-service=http --permanent
$ firewall-cmd --zone=public --add-service=https --permanent
$ firewall-cmd --reload
$ sudo firewall-cmd --zone=public --add-service=http --permanent
$ sudo firewall-cmd --zone=public --add-service=https --permanent
$ sudo firewall-cmd --reload
.. tab:: OpenSUSE

Expand All @@ -122,7 +122,7 @@ Firewall

.. code-block:: sh
systemctl restart SuSEfirewall2
sudo systemctl restart SuSEfirewall2
.. tab:: other

Expand Down
2 changes: 1 addition & 1 deletion install/includes/manage-services.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,6 @@ with the parent ``zammad``.
$ # Zammads background worker - relevant for all delayed- and background jobs
$ systemctl (status|start|stop|restart) zammad-worker
$ # Zammads websocket server for session related information
$ systemctl (status|start|stop|restart) zammad-websocket
65 changes: 0 additions & 65 deletions install/includes/prerequisites.rst
View file

This file was deleted.

Loading

0 comments on commit 12a71e6

Please sign in to comment.