Install Zammad Ticketing System on Ubuntu 22.04

Welcome to our tutorial on how to install Zammad ticketing system on Ubuntu 22.04. According to Zammad documentation page, “Zammad is a web based open source helpdesk/customer support system with many features to manage customer communication via several channels like telephone, facebook, twitter, chat and emails”.

Read about Zammad Ticketing system features on its features page, link provided below.

Zammad Ticketing system features.

Installing Zammad Ticketing System on Ubuntu 22.04

Prerequisites

There are a number of requirements that your system must meet (as of this writing) before you can install Zammad Ticketing system.

Refer to these links for Software and Hardware Requirements;

Software Requirements;

Hardware Requirements

Install Zammad Ticketing System

Configure Locales in Debian

In this tutorial, we will be installing Zammad with PostgreSQL which is the recommended database and is supported by default.

As such, if you are using PostgreSQL database backend, you need to enable UTF-8 locale.

To check if UTF-8 local is enabled, run the locale command from terminal as shown below.

locale

LANG=en_US.UTF-8
LANGUAGE=
LC_CTYPE="en_US.UTF-8"
LC_NUMERIC="en_US.UTF-8"
LC_TIME="en_US.UTF-8"
LC_COLLATE="en_US.UTF-8"
LC_MONETARY="en_US.UTF-8"
LC_MESSAGES="en_US.UTF-8"
LC_PAPER="en_US.UTF-8"
LC_NAME="en_US.UTF-8"
LC_ADDRESS="en_US.UTF-8"
LC_TELEPHONE="en_US.UTF-8"
LC_MEASUREMENT="en_US.UTF-8"
LC_IDENTIFICATION="en_US.UTF-8"
LC_ALL=

If you do not see such a line from the above output;

LANG=en_US.UTF-8

The you need to generate and update the locales.

locale-gen en_US.UTF-8

update-locale LANG=en_US.UTF-8

This will update the /etc/default/locale file with the set LANG environment variable.

Install Elasticsearch on Debian

Zammad v5.2+ is compatible with Elasticsearch v7.8+. Hence, we install the current Elasticsearch, v8.9.1, which is the latest version as of this writing, on Debian.

Install the Elasticsearch repository signing key;

sudo su -

apt update

apt install sudo gnupg2 apt-transport-https curl vim -y

wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch \
--no-check-certificate \
| gpg --dearmor > /etc/apt/trusted.gpg.d/elastic.gpg

Install Elasticsearch repo;

echo "deb https://artifacts.elastic.co/packages/8.x/apt stable main" \
| tee -a /etc/apt/sources.list.d/elastic-8.x.list

Install Elasticsearch on Debian;

apt update

apt install elasticsearch -y

Elasticsearch v8 enabled authentication and HTTPS connection by default. You will see an output similar to the one below during the installation;

Unpacking elasticsearch (8.9.1) ...
Setting up elasticsearch (8.9.1) ...
--------------------------- Security autoconfiguration information ------------------------------

Authentication and authorization are enabled.
TLS for the transport and HTTP layers is enabled and configured.

The generated password for the elastic built-in superuser is : *s_woa-wYubWz8A91oWA

If this node should join an existing cluster, you can reconfigure this with
'/usr/share/elasticsearch/bin/elasticsearch-reconfigure-node --enrollment-token '
after creating an enrollment token on your existing cluster.

You can complete the following actions at any time:

Reset the password of the elastic built-in superuser with 
'/usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic'.

Generate an enrollment token for Kibana instances with 
 '/usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s kibana'.

Generate an enrollment token for Elasticsearch nodes with 
'/usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s node'.

-------------------------------------------------------------------------------------------------
### NOT starting on installation, please execute the following statements to configure elasticsearch service to start automatically using systemd
 sudo systemctl daemon-reload
 sudo systemctl enable elasticsearch.service
### You can start elasticsearch service by executing
 sudo systemctl start elasticsearch.service

Installing Zammad Ticketing System from Zammad APT Repo

Install Zammad repo lists on Debian

wget -qO- https://dl.packager.io/srv/zammad/zammad/key \
| gpg --dearmor > /etc/apt/trusted.gpg.d/zammad.gpg

echo "deb https://dl.packager.io/srv/deb/zammad/zammad/stable/ubuntu 22.04 main" > /etc/apt/sources.list.d/zammad.list

Update package cache;

apt update

Next, install Zammad ticketing system and all the other required packages.

apt install zammad -y

As the installation completes, you will see such an output;

 (Re)building Elasticsearch searchindex...
# Enforcing 0600 on database.yml ...
Setting default Logging to file, set via "zammad config:set RAILS_LOG_TO_STDOUT=true" if you want to log to STDOUT!
# Starting Zammad
# Creating webserver bootstart
Synchronizing state of nginx.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable nginx
# Restarting webserver nginx
####################################################################################

Add your fully qualified domain name or public IP to servername directive of
nginx, if this installation is done on a remote server. You have to change:
/etc/nginx/sites-available/zammad.conf and restart nginx process.
Otherwise just open http://localhost/ in your browser to start using Zammad.

####################################################################################
Processing triggers for ufw (0.36.1-4build1) ...
Processing triggers for man-db (2.10.2-1) ...
Processing triggers for libc-bin (2.35-0ubuntu3.1) ...

Managing Zammad Services

Zammad

systemctl status zammad
systemctl stop zammad
systemctl start zammad
systemctl restart zammad
systemctl enable zammad

Only web application server

systemctl status zammad-web
systemctl stop zammad-web
systemctl start zammad-web
systemctl restart zammad-web

Only worker process

systemctl status zammad-worker
systemctl stop zammad-worker
systemctl start zammad-worker
systemctl restart zammad-worker

Only websocket server

systemctl status zammad-websocket
systemctl stop zammad-websocket
systemctl start zammad-websocket
systemctl restart zammad-websocket

Configure Elasticsearch for Zammad

Next, configure Elasticsearch search engine for Zammad.

Running Elasticsearch

We have already installed Elasticsearch 8.9.1. Thus, you can start and enable it to run on system boot by running the command below;

systemctl enable --now elasticsearch

Elasticsearch is now running with the default settings. Note that by default, Elasticsearch 8.x enables HTTPS and Authentication.

Initial credentials are printed to standard output during installation. Check Elasticsearch installation above.

You can verify by running the command below;

curl -XGET "https://localhost:9200" \
--cacert /etc/elasticsearch/certs/http_ca.crt \
-u elastic

Enter host password for user 'elastic':
{
  "name" : "debian",
  "cluster_name" : "elasticsearch",
  "cluster_uuid" : "f4ri8w0DTuWRBvITLjl8Rg",
  "version" : {
    "number" : "8.9.1",
    "build_flavor" : "default",
    "build_type" : "deb",
    "build_hash" : "a813d015ef1826148d9d389bd1c0d781c6e349f0",
    "build_date" : "2023-08-10T05:02:32.517455352Z",
    "build_snapshot" : false,
    "lucene_version" : "9.7.0",
    "minimum_wire_compatibility_version" : "7.17.0",
    "minimum_index_compatibility_version" : "7.0.0"
  },
  "tagline" : "You Know, for Search"
}

Define Elasticsearch Server Address on Zammad

To define Elasticsearch server address for Zammad, run the command below;

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

Note that we set HTTPS on the address.

Define Elasticsearch Authentication Credentials

As already mentioned, ES 8.x enables authentication by default. Note that we are using the default credentials for the super-admin Elasticsearch user

Thus, define the ES connection credentials accordingly.

Disable credentials saving on history;

set +o history

NOTE: Be wary about using the elastic super user here. You can create a user that Zammad can use to manage it’s indices! Refer to other online documentation for the same.

zammad run rails r "Setting.set('es_user', 'elastic')"

zammad run rails r "Setting.set('es_password', '*s_woa-wYubWz8A91oWA')"

Enable history;

set -o history

Other Elasticsearch Settings

Run the command below to rebuild index, adjust the index namespacing as well as the file attachment indexing rules.

zammad run rake zammad:searchindex:rebuild

Sample output;

Dropping indexes... done.
Deleting pipeline... done.
Creating indexes... done.
Creating pipeline... done.
Reloading data... 
  - Chat::Session... 
    done in 0 seconds.                    
  - Cti::Log... 
    done in 0 seconds.                    
  - Group... 
    done in 4 seconds.                    
  - KnowledgeBase::Answer::Translation... 
    done in 0 seconds.                    
  - KnowledgeBase::Category::Translation... 
    done in 0 seconds.                    
  - KnowledgeBase::Translation... 
    done in 0 seconds.                    
  - Organization... 
    done in 17 seconds.                    
  - StatsStore... 
    done in 0 seconds.                    
  - Ticket::Priority... 
    done in 9 seconds.                    
  - Ticket::State... 
    done in 22 seconds.                    
  - Ticket... 
    done in 9 seconds.                    
  - User... 
    done in 7 seconds.

Disable Elasticsearch indexing of some of the attachment extensions to reduce resource consumption;

zammad run rails r "Setting.set('es_attachment_ignore', [ '.png', '.jpg', '.jpeg', '.mpeg', '.mpg', '.mov', '.bin', '.exe', '.box', '.mbox' ] )"

zammad run rails r "Setting.set('es_attachment_max_size_in_mb', 50)"

[Optional] If you are connection mutiple Zammad instances into Elasticsearch, consider defining index namespacing to able to create indices based on Zammad host hostname.

zammad run rails r "Setting.set('es_index', Socket.gethostname.downcase + '_zammad')"

Tune Elasticsearch

Increase the virtual memory map count;

echo vm.max_map_count=262144 >> /etc/sysctl.conf

sysctl -p

Increase the maximum size of an HTTP request body (default is 100MB).

echo "http.max_content_length: 400mb" >> /etc/elasticsearch/elasticsearch.yml

Update Elasticsearch JVM heap size settings. You need to update this value depending on the size of the RAM your system is assigned.

We will set this to 1GB in our demo server.

echo '-Xms1g
-Xmx1g' > /etc/elasticsearch/jvm.options.d/jvm-custom-heap.options

Restart Elasticsearch

systemctl stop elasticsearch

systemctl start elasticsearch

Configure Web Server for Zammad

By default, Zammad uses Nginx web server. If you want to use Apache instead, see the guide below;

How to use Apache Web Server with Zammad

Setup Zammad Nginx Site Configuration for HTTP (NOT RECOMMENDED!)

Running Zammad onNginx via HTTP is not recommended security wise. You can only use this for your local environment testing.

If you want to go this route, update the default Zammad Nginx configuration for HTTP, /etc/nginx/sites-enabled/zammad.conf, and modify it to suite your needs.

vim /etc/nginx/sites-enabled/zammad.conf

Sample Zammad Nginx site configuration file;

#
# this is the nginx config for zammad
#

upstream zammad-railsserver {
    server 127.0.0.1:3000;
}

upstream zammad-websocket {
    server 127.0.0.1:6042;
}

server {
    listen 80;
    listen [::]:80;

    # replace 'localhost' with your fqdn if you want to use zammad from remote
    server_name localhost;

    # security - prevent information disclosure about server version
    server_tokens off;

    root /opt/zammad/public;

    access_log /var/log/nginx/zammad.access.log;
    error_log  /var/log/nginx/zammad.error.log;

    client_max_body_size 50M;

    location ~ ^/(assets/|robots.txt|humans.txt|favicon.ico|apple-touch-icon.png) {
        expires max;
    }

    # legacy web socket server
    location /ws {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header CLIENT_IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
        proxy_pass http://zammad-websocket;
    }

    # action cable
    location /cable {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header CLIENT_IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
        proxy_pass http://zammad-railsserver;
    }

    location / {
        proxy_set_header Host $http_host;
        proxy_set_header CLIENT_IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Change this line in an SSO setup
        proxy_set_header X-Forwarded-User "";

        proxy_read_timeout 300;
        proxy_pass http://zammad-railsserver;

        gzip on;
        gzip_types text/plain text/xml text/css image/svg+xml application/javascript application/x-javascript application/json application/xml;
        gzip_proxied any;
    }
}

To use HTTPS, see below configuration.

Setup Zammad Nginx Site Configuration for HTTPS (RECOMMENDED!)

It is recommended to setup Zammad with HTTPS for secured connection.

This is the method that we will use in this guide. Our SSL certificates are Let’s Encrypt SSL certificates. If you have your commercial CA signed certificates, you can use it.

Thus, copy the default Zammad Nginx configuration for HTTPS, /opt/zammad/contrib/nginx/zammad_ssl.conf, and modify it to suite your needs.

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

This is our modified configuration file;

cat /etc/nginx/sites-enabled/zammad_ssl.conf

upstream zammad-railsserver {
  server 127.0.0.1:3000;
}

upstream zammad-websocket {
  server 127.0.0.1:6042;
}

server {
  listen 80;
  listen [::]:80;

  server_name kifarunix.com;

  # security - prevent information disclosure about server version
  server_tokens off;

  access_log /var/log/nginx/zammad.access.log;
  error_log /var/log/nginx/zammad.error.log;

  location /.well-known/ {
    root /var/www/html;
  }

  return 301 https://$server_name$request_uri;

}


server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2;

  server_name kifarunix.com;

  # security - prevent information disclosure about server version
  server_tokens off;

  ssl_certificate /etc/letsencrypt/live/kifarunix.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/kifarunix.com/privkey.pem;

  ssl_protocols TLSv1.2;

  ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';

  ssl_dhparam /etc/nginx/dhparam.pem;

  ssl_prefer_server_ciphers on;

  ssl_session_cache shared:SSL:10m;
  ssl_session_timeout 180m;

  ssl_stapling on;
  ssl_stapling_verify on;

  resolver 8.8.8.8 8.8.4.4;

  add_header Strict-Transport-Security "max-age=31536000" always;

  location = /robots.txt  {
    access_log off; log_not_found off;
  }

  location = /favicon.ico {
    access_log off; log_not_found off;
  }

  root /opt/zammad/public;

  access_log /var/log/nginx/zammad.access.log;
  error_log  /var/log/nginx/zammad.error.log;

  client_max_body_size 50M;

  location ~ ^/(assets/|robots.txt|humans.txt|favicon.ico|apple-touch-icon.png) {
    expires max;
  }

  # legacy web socket server
  location /ws {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header CLIENT_IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 86400;
    proxy_pass http://zammad-websocket;
  }

  # action cable
  location /cable {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header CLIENT_IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 86400;
    proxy_pass http://zammad-railsserver;
  }

  location / {
    proxy_set_header Host $http_host;
    proxy_set_header CLIENT_IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto	$scheme;

    # change this line in an SSO setup
    proxy_set_header X-Forwarded-User "";

    proxy_read_timeout 180;
    proxy_pass http://zammad-railsserver;

    gzip on;
    gzip_types text/plain text/xml text/css image/svg+xml application/javascript application/x-javascript application/json application/xml;
    gzip_proxied any;
  }
}

Disable the default HTTP and Zammad sites;

unlink /etc/nginx/sites-enabled/default

unlink /etc/nginx/sites-enabled/zammad.conf

Also, generate Deffie-Hellman certificate to ensure a secured key exchange. The -dsaparam option in the command below is added to speed up the generation.

openssl dhparam -dsaparam -out /etc/nginx/dhparam.pem 4096

Check Nginx configuration syntax

nginx -t

If it is okay;

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

The restart;

systemctl restart nginx

Install Postfix for Zammad Email Notifications

To have Zammad deliver email notifications, you can install postfix and choose Internet Site option if prompted.

apt install postfix -y

Accessing Zammad Web Interface

You can now access your Zammad from the browser.

First of all, open the web server ports if you have firewall running;

Using UFW;

ufw allow "Nginx Full"

You can now access Zammad Web interface by navigating to the URL, http://<server-fqdn> or https://<server-fqdn>.

You will be welcomed by Zammad setup page;

Click on Setup new system to proceed.

Setup Zammad Administrator account.

Next, set you organization name, logo and the zammad url;

Configure Email notification settings. We use Gmail relay in our case.

If you are using Gmail relay, then check this guide on how to setup app passwords in the guide Configure Postfix to Use Gmail App Passwords

Click Continue to setup your email notifications.

Password required is the app password.

You can setup the Zammad communications channels. Click Email to setup email communication channel.

A verification Email will be sent to your inbox as a confirmation of the function of the communications channel.

Once you have set your Zammad communications channel, you can choose to invite colleagues;

Click Continue to go to the dashboard, stats.

Dashboard, First Steps

OverView

And that is all on installing Zammad Ticketing System on Ubuntu 22.04.

You can continue with the setup in order to fully use the Zammad ticketing system.

Reference

Zammad Documentation

Other Tutorials

Install Zammad Ticketing System on Ubuntu 20.04

Install Request Tracker (RT) with MariaDB on CentOS 8

Configure Request Tracker (RT) to send Mails using MSMTP via Office 365 Relay