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!

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

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 webserver’s configuration directory and make sure to replace server_name localhost; (Nginx) or ServerName localhost (Apache 2) with Zammad’s actual subdomain.

Where?

/etc/nginx/conf.d/
/etc/nginx/vhosts.d/
/etc/nginx/sites-available/

/etc/apache2/conf.d/
/etc/httpd/vhosts.d/
/etc/apache2/sites-available/

How?

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

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.

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.

$ 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 Certbot documentation has a lot more use cases than we cover here.

Note

acme.sh by default no longer uses Let’s Encrypt. For this reason you’ll have to change the default CA.

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

$ 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

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

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

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

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

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-available/zammad.conf

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

Most common:

/etc/nginx/conf.d/
/etc/nginx/vhosts.d/
/etc/nginx/sites-available/

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 with systemctl reload nginx to apply your configuration changes.

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.

$ a2enmod proxy proxy_html proxy_http proxy_wstunnel headers ssl

If you want to run Zammad under HTTP/2, you will also need

$ a2enmod h2 proxy_http2 mpm_event

$ sudo systemctl restart apache2

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

# /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 webserver’s configuration directory. Do not rename this file!

Copy & overwrite the default zammad.conf by using

$ 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:

/etc/apache2/conf.d/
/etc/httpd/vhosts.d/
/etc/apache2/sites-available/

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)

SSLCertificateKeyFile (the certificates private key)

SSLCertificateChainFile (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!

(Optional) - Enable the site

Hint

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

$ a2ensite zammad

$ 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:

IncludeOptional sites-enabled/*.conf

You can find your config file in Ubuntu, Debian & openSUSE under /etc/apache2/apache2.conf and for CentOS under /etc/httpd/conf/httpd.conf.

Step 4 - Save & reload

Reload your Apache to apply your configuration changes:

$ sudo systemctl reload apache2

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

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

Hint

You’re not seeing Zammad’s 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. 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:

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

Getting started wizard after installing Zammad