Install Zammad Helpdesk on Debian 12 / Debian 11

CloudSpinx
March 24, 2025
5:01 pm
No Comments

In this article we discuss the installation of Zammad Helpdesk on Debian 12 / Debian 11 Linux system. Zammad is a web based helpdesk and customer support system, released under GNU AGPLv3 open source license. With this tool it is easy and quicker to manage your customer communications via several channels such as twitter, telephone, chat, facebook, and e-mails.

Features of Zammad Helpdesk / Customer Support Tool

Here are some key features of Zammad Helpdesk system.

Groups: Form groups to create separation within your teams and departments
SSO: Zammad offers easy Single Sign-On with just one click thanks to the integration of architectures such as SAML or Shibboleth
LDAP integration: Zammad offers you centralized user/rights management options using our secure LDAP integration
External Authentication: Support for sign in through third parties such as Twitter, Facebook, LinkedIn, or Google via OAuth.
Slack Integration: You can automatically receive a message in Slack when there is a new ticket
Time recording: Zammad enables agents to record the exact processing time per ticket
Exchange Integration: Support for Exchange synchronization to import Exchange address book contacts
i-doit Integration: The i-doit integration makes it possible to keep an eye on your data, processes, and systems
Knowledge Base: Zammad has an extensive knowledge base that makes sure everyone is always in the picture
Multilingualism: Zammad web app supports over 30 languages
Check all Zammad features

Follow the steps in this guide to install Zammad Helpdesk and customer support system on Debian 12 and Debian 11 Linux operating system.

The recommended server server requirements for this installation are:

2 CPU cores
4 GB of RAM (+4 GB if you want to run Elasticsearch on the same server)

For optimal performance, i.e up to 40 agents, below are the recommended hardware specifications.

4 CPU cores
6 GB of RAM (+6 GB if you want to run Elasticsearch on the same server)

Step 1: Update Debian System

Before you begin the installation ensure your Debian system is up-to-date:

sudo apt update
sudo apt -y full-upgrade

If you have kernel updates it is recommended to perform system restart:

sudo systemctl reboot

Install required dependencies:

sudo apt install wget curl apt-transport-https gnupg2 libimlib2 libimlib2-dev -y

Step 2: Install MariaDB and Apache Web Server

A database server and web server which will serve as proxy to Zammad is required.

Set correct locale on the server:

sudo apt install locales
sudo locale-gen en_US.UTF-8
echo "LANG=en_US.UTF-8" | sudo tee /etc/default/locale

We’ll use MariaDB Database Server but you can also choose to use PostgreSQL:

sudo apt -y install mariadb-server

Initiate database security with the command below:

$ sudo mysql_secure_installation

NOTE: RUNNING ALL PARTS OF THIS SCRIPT IS RECOMMENDED FOR ALL MariaDB
      SERVERS IN PRODUCTION USE!  PLEASE READ EACH STEP CAREFULLY!

In order to log into MariaDB to secure it, we'll need the current
password for the root user. If you've just installed MariaDB, and
haven't set the root password yet, you should just press enter here.

Enter current password for root (enter for none): 
OK, successfully used password, moving on...

Setting the root password or using the unix_socket ensures that nobody
can log into the MariaDB root user without the proper authorisation.

You already have your root account protected, so you can safely answer 'n'.

Switch to unix_socket authentication [Y/n] n
 ... skipping.

You already have your root account protected, so you can safely answer 'n'.

Change the root password? [Y/n] Y
New password: 
Re-enter new password: 
Password updated successfully!
Reloading privilege tables..
 ... Success!


By default, a MariaDB installation has an anonymous user, allowing anyone
to log into MariaDB without having to have a user account created for
them.  This is intended only for testing, and to make the installation
go a bit smoother.  You should remove them before moving into a
production environment.

Remove anonymous users? [Y/n] Y
 ... Success!

Normally, root should only be allowed to connect from 'localhost'.  This
ensures that someone cannot guess at the root password from the network.

Disallow root login remotely? [Y/n] Y
 ... Success!

By default, MariaDB comes with a database named 'test' that anyone can
access.  This is also intended only for testing, and should be removed
before moving into a production environment.

Remove test database and access to it? [Y/n] Y
 - Dropping test database...
 ... Success!
 - Removing privileges on test database...
 ... Success!

Reloading the privilege tables will ensure that all changes made so far
will take effect immediately.

Reload privilege tables now? [Y/n] Y
 ... Success!

Cleaning up...

All done!  If you've completed all of the above steps, your MariaDB
installation should now be secure.

Thanks for using MariaDB!

Check and configure database server encoding if not set like below:

$ sudo vim /etc/mysql/mariadb.conf.d/50-server.cnf
character-set-server  = utf8mb4
collation-server      = utf8mb4_general_ci

Restart mariadb database server after the configuration:

sudo systemctl restart mariadb

Install Apache web server which will proxy requests to Zammad service:

sudo apt -y install apache2

Enable Apache headers:

sudo a2enmod headers
sudo systemctl stop apache2
sudo systemctl start  apache2
sudo systemctl restart apache2

Check service status:

$ sudo systemctl status apache2.service
● apache2.service - The Apache HTTP Server
     Loaded: loaded (/lib/systemd/system/apache2.service; enabled; preset: enabled)
     Active: active (running) since Fri 2025-03-21 18:02:02 EAT; 2s ago
       Docs: https://httpd.apache.org/docs/2.4/
    Process: 5532 ExecStart=/usr/sbin/apachectl start (code=exited, status=0/SUCCESS)
   Main PID: 5537 (apache2)
      Tasks: 55 (limit: 7032)
     Memory: 14.9M
        CPU: 42ms
     CGroup: /system.slice/apache2.service
             ├─5537 /usr/sbin/apache2 -k start
             ├─5539 /usr/sbin/apache2 -k start
             └─5540 /usr/sbin/apache2 -k start

Mar 21 18:02:02 zammad.africanfine.com systemd[1]: Starting apache2.service - The Apache HTTP Server...
Mar 21 18:02:02 zammad.africanfine.com systemd[1]: Started apache2.service - The Apache HTTP Server.

Step 3: Install ElasticSearch

Once the system is rebooted add Elasticsearch repository:

wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/8.x/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-8.x.list
sudo apt update -y

Then install Elasticsearch:

sudo apt-get update && sudo apt-get install elasticsearch

When installing Elasticsearch, security features are enabled and configured by default. When you install Elasticsearch, the following security configuration occurs automatically:

Authentication and authorization are enabled, and a password is generated for the elastic built-in superuser.
Certificates and keys for TLS are generated for the transport and HTTP layer, and TLS is enabled and configured with these keys and certificates.

The password and certificate and keys are output to your terminal. You can reset the password for the elastic user with the elasticsearch-reset-password command.

We recommend storing the elastic password as an environment variable in your shell. For example:

export ELASTIC_PASSWORD="your_password"

After you installed Elasticsearch and its attachment plugin:

sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment

Ensure elasticsearch is enabled by default and start it.

sudo systemctl enable elasticsearch
sudo systemctl start elasticsearch

Check that elasticsearch is running:

$ sudo systemctl status elasticsearch
● elasticsearch.service - Elasticsearch
     Loaded: loaded (/lib/systemd/system/elasticsearch.service; enabled; preset: enabled)
     Active: active (running) since Fri 2025-03-21 18:29:08 EAT; 3min 40s ago
       Docs: https://www.elastic.co
   Main PID: 6161 (java)
      Tasks: 92 (limit: 7032)
     Memory: 3.4G
        CPU: 42.000s
     CGroup: /system.slice/elasticsearch.service
             ├─6161 /usr/share/elasticsearch/jdk/bin/java -Xms4m -Xmx64m -XX:+UseSerialGC -Dcli.name=server -Dcli.script=/usr/share/elasticsearch>
             ├─6219 /usr/share/elasticsearch/jdk/bin/java -Des.networkaddress.cache.ttl=60 -Des.networkaddress.cache.negative.ttl=10 -XX:+AlwaysP>
             └─6241 /usr/share/elasticsearch/modules/x-pack-ml/platform/linux-x86_64/bin/controller

Mar 21 18:28:51 zammad.africanfine.com systemd[1]: Starting elasticsearch.service - Elasticsearch...
Mar 21 18:28:54 zammad.africanfine.com systemd-entrypoint[6219]: CompileCommand: dontinline java/lang/invoke/MethodHandle.setAsTypeCache bool don>
Mar 21 18:28:54 zammad.africanfine.com systemd-entrypoint[6219]: CompileCommand: dontinline java/lang/invoke/MethodHandle.asTypeUncached bool don>
Mar 21 18:29:08 zammad.africanfine.com systemd[1]: Started elasticsearch.service - Elasticsearch.

Step 4: Install Zammad on Debian 12 /11

Install Repository Key:

curl -fsSL https://dl.packager.io/srv/zammad/zammad/key | \
   gpg --dearmor | sudo tee /etc/apt/keyrings/pkgr-zammad.gpg> /dev/null

Add repository to Debian:

Debian 11 (Bullseye):

echo "deb [signed-by=/etc/apt/keyrings/pkgr-zammad.gpg] https://dl.packager.io/srv/deb/zammad/zammad/stable/debian 11 main"| \
   sudo tee /etc/apt/sources.list.d/zammad.list > /dev/nul

Debian 12 (Bookworm):

echo "deb [signed-by=/etc/apt/keyrings/pkgr-zammad.gpg] https://dl.packager.io/srv/deb/zammad/zammad/stable/debian 12 main"| \
   sudo tee /etc/apt/sources.list.d/zammad.list > /dev/null

With the repository added you can begin the installation of Zammad on Debian 12 / Debian 11 system:

sudo apt update -y 
sudo apt install zammad

Accept any installation prompts you get on the screen.

Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following packages were automatically installed and are no longer required:
  linux-image-6.1.0-25-amd64 linux-image-6.1.0-30-amd64
Use 'sudo apt autoremove' to remove them.
The following additional packages will be installed:
  liblzf1 libpq5 redis-server redis-tools
Suggested packages:
  ruby-redis
The following NEW packages will be installed:
  liblzf1 libpq5 redis-server redis-tools zammad
0 upgraded, 5 newly installed, 0 to remove and 0 not upgraded.
Need to get 181 MB of archives.
After this operation, 625 MB of additional disk space will be used.
Do you want to continue? [Y/n] y

A database named zammad is created by the installer.

Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 69
Server version: 10.11.11-MariaDB-0+deb12u1 Debian 12

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]> SHOW DATABASES;
+--------------------+
| Database           |
+--------------------+
| information_schema |
| mysql              |
| performance_schema |
| sys                |
| zammad             |
+--------------------+
5 rows in set (0.009 sec)

MariaDB [(none)]>

If you have ufw firewall open http and https ports:

sudo ufw allow 80,443
sudo ufw reload

Start Zammad service and enable it to start at system boot:

sudo systemctl start zammad
sudo systemctl enable zammad

Set the Elasticsearch server address:

sudo zammad run rails r "Setting.set('es_url', 'https://localhost:9200')"

Now you need your password which was shown to you while installing Elasticsearch.

# Set Elasticsearch user and password
sudo zammad run rails r "Setting.set('es_user', 'elastic')"
sudo zammad run rails r "Setting.set('es_password', '<password>')"

Build/rebuild the search index:

sudo zammad run rake zammad:searchindex:rebuild

First, disable the Apache default virtual host file with the following command:

sudo a2dissite 000-default.conf

Restart apache2 web server:

sudo systemctl restart apache2

Confirm service is started without an error:

$ systemctl status apache2
● apache2.service - The Apache HTTP Server
     Loaded: loaded (/lib/systemd/system/apache2.service; enabled; preset: enabled)
     Active: active (running) since Fri 2025-03-21 19:21:23 EAT; 11s ago
       Docs: https://httpd.apache.org/docs/2.4/
    Process: 8684 ExecStart=/usr/sbin/apachectl start (code=exited, status=0/SUCCESS)
   Main PID: 8689 (apache2)
      Tasks: 55 (limit: 7032)
     Memory: 9.3M
        CPU: 33ms
     CGroup: /system.slice/apache2.service
             ├─8689 /usr/sbin/apache2 -k start
             ├─8690 /usr/sbin/apache2 -k start
             └─8691 /usr/sbin/apache2 -k start

Mar 21 19:21:23 zammad.africanfine.com systemd[1]: Starting apache2.service - The Apache HTTP Server...
Mar 21 19:21:23 zammad.africanfine.com systemd[1]: Started apache2.service - The Apache HTTP Server.

If you get an error “apachectl[2095]: Invalid command ‘RequestHeader’, perhaps misspelled or defined by a module not included in the server configuration“, ensure you’ve enabled Apache headers:

sudo a2enmod headers
sudo systemctl stop apache2
sudo systemctl start  apache2

Step 4: Access Zammad Web Interface

Open your web browser and access Zammad web interface on the URL.

http://your_server_ip_or_hostname

You should see the following screen. Select “Setup new system” to initiate configuration.

Create the first admin user account for Zammad.

Input organization name

Setup Email comments channel – this is an optional configuration that can be done after the installation and you can skip it.

Configure notification email sending Local MTA or configure your own SMTP settings.

If you did not skip the SMTP configuration, then setup the communiation channels you want to use with your Zammad. Otherwise, skip this step for later setup.

Connect an email account:

Complete installation of Zammad Helpdesk on Debian 12 / Debian 11 Linux system.

Add certificate to Zammad

Show and copy the auto-generated certificate from Elasticsearch and add it to Zammad. Make sure to copy/paste the delimiters (e.g. -----BEGIN CERTIFICATE-----) too.

sudo cat /etc/elasticsearch/certs/http_ca.crt

Go to the admin panel of Zammad and add your copied certificate under SSL Certificates.

Click Add SSL Certificate, then add what you just pasted from your terminal:

Then click Add.

Reference:

More guides from our team:

Your IT Journey Starts Here!

Ready to level up your IT skills? Our new eLearning platform is coming soon to help you master the latest technologies.

Be the first to know when we launch! Join our waitlist now.