Configure the Webserver

Tip

Are you tired of complex setup, configuration, backup and update tasks? Let us handle this stuff for you! 🚀

The easiest and often most cost-effective way to operate Zammad is our cloud service. Give it a try with a free trial instance!

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. 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

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 environment variables page.

Obtain an SSL Certificate

Zammad requires HTTPS in production. Use one of the options below to obtain a certificate before continuing with the webserver configuration.

Commercial Certificate Authority

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.

Let’s Encrypt

Let’s Encrypt issues free, automatically renewable certificates. Two clients are commonly used.

Certbotacme.sh

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 <webserver> with nginx or apache and zammad.example.com with your subdomain:

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

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.

Adjust the Webserver Configuration

Nginx (default)Apache 2Local testing or other proxy servers

Get the sample config into place

Copy the SSL sample configuration to your Nginx config directory:

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

Most common Nginx config directories:

• /etc/nginx/conf.d/

• /etc/nginx/vhosts.d/

• /etc/nginx/sites-available/

Adjust server name and certificate paths

Adjust the just copied file with a text editor of your 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. 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:

$ sudo openssl dhparam -out /etc/ssl/dhparam.pem 4096

Reload and verify

Verify the configuration:

$ sudo nginx -t

Reload Nginx:

$ sudo systemctl reload nginx

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 Troubleshooting section below.

Troubleshooting

Default Landing Page Instead of Zammad

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.

DNS Not Resolving

If the subdomain does not resolve, double-check the DNS records for 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:

$ host zammad.example.com

CSRF Token Errors

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.

Nginx

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

Apache 2

Within your virtual host configuration, just above the first ProxyPass directive, insert:

RequestHeader set X_FORWARDED_PROTO 'https'
RequestHeader set X-Forwarded-Ssl on