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>`
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.
Attention!
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
.. hint::
If not happened automatically, you may need 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 alot more use cases than we cover here.
.. tab:: acme.sh
.. hint::
The most reliable way is to use the method for your webserver.
.. 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 alot 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.
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
.. note::
| 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
.. note::
| 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``.
.. tip::
If above ports are used by other applications already you may want to
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.confordefault.confin your vhost directory possibly overrules your configuration.Sometimes this is also a DNS resolving issue.
