Skip to content

Latest commit

 

History

History
410 lines (264 loc) · 13.9 KB

configure-webserver.rst

File metadata and controls

410 lines (264 loc) · 13.9 KB

Configure the webserver

You can find current sample configuration files for your webserver within contrib/ of your Zammad installation.

If you're using the package installation, Zammad attempts to automatically install a configuration file to your nginx for you.

Note

The Zammad installation will not automatically set any host- or server name for you.

Docker Compose / Kubernetes users
Please also note the environment information on :doc:`this page </install/docker-compose/environment>`

Get a ssl certificate (recommended)

Don't know how to get SSL certificates and install them on a webserver yet? The guide within the tabs below can help you jumping in.

Make sure to used named configuration. The default sample configuration for both nginx and apache are not named.

To fix this, open the zammad.conf in your webservers configuration directory and make sure to replace server_name localhost; (nginx) or ServerName localhost (Apache 2) with Zammad's actual subdomain.

Where?

nginx:

Apache 2:

.. tabs::

   .. tab:: I don't need that

      You either already know what you're doing, you're developing or like the
      danger. ⚔️

   .. tab:: letsencrypt

      letsencrypt is an easy and free way to retreive valid ssl certificates.
      These certificates are valid for 90 days and can be renewed automatically.

      The two most common tools are
      `certbot <https://certbot.eff.org/instructions>`_ and
      `acme.sh <https://github.com/acmesh-official/acme.sh>`_.

      .. tabs::

         .. tab:: certbot

            If not happened automatically, you have to install
            the nginx or apache plugin for certbot:
            ``python3-certbot-nginx`` OR ``python3-certbot-apache``

            During the first certbot run it will request additional information
            once. Replace ``<webserver>`` in below command by either
            ``apache``, ``httpd`` or ``nginx`` and to match your setup.

            .. code-block:: sh

               $ certbot --<webserver> -d zammad.example.com

            Certbot will now attempt to issue a certificate for you.
            If successful, certbot will ask you if you want to
            ``[1] not redirect`` or ``[2] redirect`` automatically.
            You can choose to not redirect **if** you plan to use the sample
            configuration of Zammad. If not, select ``[2] redirect``.

            From this moment on, certbot will automatically renew your
            installed certificates if they're valid for another 30 days or less.

            .. hint:: **Not exactly what you're looking for?**

               The `cerbot documentation`_
               has a lot more use cases than we cover here.

         .. tab:: acme.sh

            .. note::

               acme.sh by default no longer uses letsencrypt.
               For this reason you'll have to change the default CA.

               .. code-block:: sh

                  $ acme.sh --set-default-ca  --server letsencrypt

               If you want to use any other CA with acme.sh, consult their
               documentation on how to.

            First of all you'll need to issue your certificate.
            acme.sh will save this certificate to
            ``/root/.acme.sh/<your-domain>/``

            Replace ``<webserver>`` in the following command by either
            ``apache`` or ``nginx`` and to match your setup, use ``standalone`` for other webservers.

            .. code-block:: sh

               $ acme.sh --issue --<webserver> -d zammad.example.com

            It's not recommended to use the just stored certificates directly.
            Instead you should install the certificate to a directory of your
            choice.

            We're using ``/etc/ssl/private/`` in this case, but you can use any
            directory you like.

            .. warning::

               Ensure to adjust value for ``--reloadcmd`` as this will
               ensure that acme.sh reloads your webserver automatically
               after getting a renewal. Replace ``<webserver>`` by either
               ``apache2``, ``httpd`` or ``nginx``

            .. code-block:: sh

               $ acme.sh --install-cert -d zammad.example.com \
                   --cert-file      /etc/ssl/private/zammad.example.com.pem  \
                   --key-file       /etc/ssl/private/zammad.example.com.key  \
                   --fullchain-file /etc/ssl/private/zammad.example.com.full.pem \
                   --reloadcmd     "systemctl force-reload <webserver>"

            From this moment on, acme.sh will automatically renew your
            installed certificates if they're valid for another 30 days or less.

            .. hint::

               **Not exactly what you're looking for?**

               The `acme.sh documentation`_ has a lot more use cases than
               we cover here.

   .. tab:: public, paid CA

      If you prefer to use certificates from other official CAs than
      letsencrypt, you can do so as well. Just get your certificate bundle from
      the source you prefer and continue with
      `Adjusting the webserver configuration`_.

      .. note::

         **🙋 I'm new to SSL certificates. Where can I get a certificate?**

         The easiest way to get certificates is to buy an annual
         subscription through a commercial CA, such as:

         * `Sectigo (formerly Comodo)`_
         * `Secorio`_
         * `GlobalSign`_

         (Zammad is not affiliated with these CAs in any way.)

   .. tab:: self-signed (discouraged)

      Another way is to use self signed certificates from your own CA.
      In general you shouldn't use this option when you have users accessing
      Zammad that can't verify your certificates.

      Beside creating own certificates via e.g. XCA or Microsoft CA, you can
      also generate a certificate really quick like so:

      On any system with ``openssl`` installed, you can run below command.
      Provide the requested information and ensure to provide the fqdn of
      Zammad when being asked for
      ``Common Name (e.g. server FQDN or YOUR name)``.

      .. code-block:: sh

         $ openssl req -newkey rsa:4096 -nodes -x509 -days 1825\
             -keyout key.pem -out certificate.pem

      Above command creates a certificate that's valid for 5 years. It will
      write the certificate and private key to the current directory you're in.
      If you want to check your certificate you just created, you can use the
      following command.

      .. code-block:: sh

         $ openssl x509 -text -noout -in certificate.pem

      .. hint::

         **Not good enough for you?**

         If above command is not good enough for you, the
         `openSSL documentation`_ is a good place to learn more.

Adjusting the webserver configuration

Warning

For a quick start, we're installing a HTTP configuration. You should never use HTTP connections for authentication - instead, we encourage you to use HTTPS!

If Zammad scripts automatically installed your webserver configuration file, ensure to not rename it. Below we'll cover HTTPs for above reason.

.. tabs::

   .. tab:: nginx (default)

      Step 1 - Get a current config file
         Copy & overwrite the default ``zammad.conf`` by using

         .. code-block:: sh

            $ cp /opt/zammad/contrib/nginx/zammad_ssl.conf /etc/nginx/sites-available/zammad.conf

         Your nginx directories may differ, please adjust your commands if
         needed.

         Most common:

         .. include:: includes/nginx-config-paths.include.rst

      Step 2 - Adjust the config file
         Adjust the just copied file with a text editor of your choice (e.g.
         ``vi`` or ``nano``).

         Locate any ``server_name`` directive and adjust ``example.com`` to the
         subdomain you have chosen for your Zammad instance.

         Now you'll need to adjust the path and file names for your ssl
         certificates your obtained on the prior steps. Adjust the following
         directives to match your setup:

            * ``ssl_certificate`` (your ssl certificate)
            * ``ssl_certificate_key`` (the certificates private key)
            * ``ssl_trusted_certificate`` (the public CA certificate)

            .. note::

               Technically this is not a hard requirement, but recommended!

         .. include:: /getting-started/include-dhparam-webserver.rst

      (Optional) - Adjust HTTPs configuration
         .. include:: /getting-started/include-ssl-config-generator-webserver.rst

      Step 3 - Save & reload
         Reload your nginx ``systemctl reload nginx`` to apply your
         configuration changes.

   .. tab:: apache2

      Step 1 - Ensure required modules are enabled
         Zammad requires modules that are not enabled by default. By default
         use ``a2enmod`` (**not** CentOS) to do so.

         .. tabs::

            .. tab:: a2enmod

               .. code-block:: sh

                  $ a2enmod proxy proxy_html proxy_http proxy_wstunnel headers ssl
                  $ systemctl restart apache2

            .. tab:: via configuration file (CentOS)

               add/uncomment the appropriate ``LoadModule`` statements
               in your Apache config:

               .. code-block::

                  # /etc/httpd/conf/httpd.conf

                  LoadModule headers_module modules/mod_headers.so
                  LoadModule proxy_module modules/mod_proxy.so
                  LoadModule proxy_html_module modules/mod_proxy_html.so
                  LoadModule proxy_http_module modules/mod_proxy_http.so
                  LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so

               Don't forget to restart your apache.

      Step 2 - Get a current config file
         .. note::

            Package installations attempt to copy a ``zammad.conf`` to your
            webservers configuration directory. **Do not rename** this file!

         Copy & overwrite the default ``zammad.conf`` by using

         .. code-block:: sh

            $ cp /opt/zammad/contrib/apache2/zammad_ssl.conf /etc/apache2/sites-available/zammad.conf

         Your apache directories may differ, please adjust your commands
         if needed.

         Most common:

         .. include:: includes/apache-config-paths.include.rst

      Step 3 - Adjust the config file
         Adjust the just copied file with a text editor of your choice (e.g.
         ``vi`` or ``nano``).

         Locate any ``ServerName`` directive and adjust ``example.com`` to the
         subdomain you have chosen for your Zammad instance.

         Now you'll need to adjust the path and file names for your ssl
         certificates your obtained on the prior steps. Adjust the following
         directives to match your setup:

            * ``SSLCertificateFile`` (your ssl certificate)
            * ``SSLCertificateKeyFil`` (the certificates private key)
            * ``SSLCertificateChainFile`` (the public CA certificate)

            .. note::

               Technically this is not a hard requirement, but recommended!

         .. include:: /getting-started/include-dhparam-webserver.rst

      (Optional) - Adjust HTTPs configuration
         .. include:: /getting-started/include-ssl-config-generator-webserver.rst

      (Optional) - Enable the site
         .. hint::

            This step mostly depends on your selected folders and most often
            only affects ``sites-available`` folders.

         .. tabs::

            .. tab:: Ubuntu / Debian / openSUSE

               .. code-block:: sh

                  $ a2ensite zammad

            .. tab:: CentOS

               .. code-block:: sh

                  $ ln -s /etc/httpd/sites-available/zammad_ssl.conf /etc/httpd/sites-enabled/

         Also, make sure the following line is present in your Apache
         configuration:

         .. code-block::

            # /etc/apache2/apache2.conf (Ubuntu, Debian, & openSUSE)
            # /etc/httpd/conf/httpd.conf (CentOS)

            IncludeOptional sites-enabled/*.conf

      Step 4 - Save & reload
         Reload your apache ``systemctl reload apache2`` to apply your
         configuration changes.

   .. tab:: local testing or other proxy servers

      Want to test locally first or use a different Proxy we don't support?
      The main application (rails server) is listening on
      ``http://127.0.0.1:3000``.

      If you're using a proxy server, also ensure that you proxy the websockets
      as well. The websocket server listens on ``ws://127.0.0.1:6042``.

      If above ports are used by other applications already, please
      have a look at :ref:`network options <network_options>` on our
      environment page.

      .. warning::

         Do not expose Zammad directly to the internet, as Zammad only provides
         HTTP!

If you just installed Zammad, you'll be greeted by our getting started wizard. 🙌 You now can continue with :doc:`first-steps`.

Hint

You're not seeing Zammads page but a default landing page of your OS?

Ensure that you did restart your webserver - also check if 000-default.conf or default.conf in your vhost directory possibly overrules your configuration.

Sometimes this is also a DNS resolving issue.

Getting started wizard after installing Zammad