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 this page

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.

Step 1 - Get a current config file

Copy & overwrite the default zammad.conf by using

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

Note

Your nginx directories may differ, please adjust your commands if needed.
Most common:
  • /etc/nginx/conf.d/

  • /etc/nginx/vhosts.d/

  • /etc/nginx/sites-enabled/

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!

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)

$ openssl dhparam -out <path>/dhparam.pem 4096
(Optional) - Adjust HTTPs configuration

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!

Step 3 - Save & reload

Reload your nginx systemctl reload nginx to apply your configuration changes.

If you just installed Zammad, you’ll be greeted by our getting started wizard. 🙌 You now can continue with 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.

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.

Warning

Do not use below options if you’re unsure, they may technically be a security issue!

The following options expect HTTPs connections which should be your goal.

Within your virtual host configuration, locate both directives proxy_set_header X-Forwarded-Proto and replace $scheme by https.

Getting started wizard after installing Zammad