Installation de Zammad

Bonne année à tous !

Aujourd'hui j'ai décidé de mettre en place une nouvelle plateforme pour la gestion des demandes supports avec Zammad.

Zammad est une solution de gestion des demandes support très complète et disponible en en version commerciale sur https://zammad.com/ ou open-source https://zammad.org/.
Vous y trouverez toutes les fonctionnalités nécessaires pour une plateforme support mais parmis les raisons de mon coup de coeur nous retrouvons les grandes possibilités d'intégration (LDAP, GPG, S/MINE, Exchange, VoIP, supervision, etc. liste exhaustive ici), la possibilité de recherche dans le contenu des tickets (nécessite Elasticsearch) et la présence de nombreux canaux de communication (interface web, formulaires, mail, chat, sms et plus encore).

Prérequis

Pour ce tutoriel nous allons déployer Zammad sur une machine virtuel Ubuntu 22.04, l'accès depuis l'extérieur se fera via un reverse proxy Caddy hébergé sur une autre machine.

En terme de spécification Zammad recommande au minimum :
- vCPU : 2
- RAM : 4Go (+4Go si vous voulez utiliser Elasticsearch pour les recherches)
Plus d'information dans la documentation.

Pour ce qui est de l'espace disque Zammad ne donne pas de recommandation comme il s'agit d'un point à définir en fonction de votre utilisation. Ici je vais partir sur 50Go afin d'avoir un dimensionnement suffisant pour un moment.

Installation

Nous allons maintenant passer à l'installation de notre plateforme.

Dépendances

Commençons par l'installation des dépendances :

sudo apt install apt-transport-https wget curl gnupg

Memcached

Pour la gestion du cache de Zammad j'ai choisi d'utiliser Memcached qui n'est pas obligatoire. Sans Memcached le cache sera stocké dans /opt/zammad/tmp/cache*.

sudo apt install memcached

Une valeur raisonnable pour la taille du cache est de 1Go que nous pouvons définir en modifiant la configuration de memcached :

-m 1024

Puis activer et redémarrer le service

sudo systemctl enable memcached.service
sudo systemctl restart memcached.service

Installation d'Elasticsearch

Que vous choisissiez d'utiliser Elasticsearch pour les fonctionnalités de recherche ou non sont installation avec le plugin "attachment" est nécessaire car il s'agit d'une dépendance obligatoire de Zammad.

Pour simplifier notre installation nous allons utiliser la version 7 d'Elasticsearch sur notre machine. Cependant il est également possible d'utiliser la version 8 ou un cluster distant, dans ces cas d'utilisation je vous invite à prendre connaissance de la documentation.

echo "deb [signed-by=/etc/apt/trusted.gpg.d/elasticsearch.gpg] https://artifacts.elastic.co/packages/7.x/apt stable main"| \
  sudo tee -a /etc/apt/sources.list.d/elastic-7.x.list > /dev/null
curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | \
  gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/elasticsearch.gpg> /dev/null
sudo apt update
sudo apt install elasticsearch
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment

Configuration d'Elasticsearch

La documentation recommande quelques modification afin de lancer le service afin de permettre un fonctionnement optimal des fonctions de recherche.

# Nom du cluster Elasticsearch
cluster.name: zammad
# Stockage des données (valeur définie par défaut)
path.data: /var/lib/elasticsearch
# Stockage des journaux (valeur définie par défaut)
path.logs: /var/log/elasticsearch

# Taille maximum d'indexation d'un ticket (risque de perte de performance au-delà de cette valeur)
http.max_content_length: 400mb
# Autoriser les requêtes de recherche plus complexe (Au dessus de cette valeur l'utilisation des ressources système peut devenir trop intensive)
indices.query.bool.max_clause_count: 2000

Nous pouvons maintenant passer démarrer le service Elasticsearch

sudo systemctl daemon-reload
sudo systemctl enable --now elasticsearch

Définition des locales

Afin d'assurer une bon fonctionnement pour notre langue nous allons définir les données de langage.

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

Installation de Zammad

L'installation de Zammad se fait directement via un paquet qui est disponible dans le dépôt officiel que nous allons ajouter :

curl -fsSL https://dl.packager.io/srv/zammad/zammad/key | \
  gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/pkgr-zammad.gpg> /dev/null
echo "deb [signed-by=/etc/apt/trusted.gpg.d/pkgr-zammad.gpg] https://dl.packager.io/srv/deb/zammad/zammad/stable/ubuntu 22.04 main"| \
  sudo tee /etc/apt/sources.list.d/zammad.list > /dev/null
sudo apt update

$ sudo apt install zammad

Configuration du serveur

Maintenant nous allons voir quelques étapes de configuration.

Connexion à Elasticsearch

Nous allons indiquer à Zammad les informations nécessaires pour la connexion à notre service Elasticsearch :

# Adresse pour se connecter à Elasticsearch
sudo zammad run rails r "Setting.set('es_url', 'http://localhost:9200')"

# Ignore l'indexationn de certains types de fichiers pour préserver les performance
sudo zammad run rails r "Setting.set('es_attachment_ignore',\
  [ '.png', '.jpg', '.jpeg', '.mpeg', '.mpg', '.mov', '.bin', '.exe', '.box', '.mbox' ] )"

# Définition de la taille maximal en MB des fichiers joints à indexer
sudo zammad run rails r "Setting.set('es_attachment_max_size_in_mb', 50)"

# Lancer la recréation de l'index
sudo zammad run rake zammad:searchindex:rebuild
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 0 seconds.
  - KnowledgeBase::Answer::Translation...
    done in 0 seconds.
  - KnowledgeBase::Category::Translation...
    done in 0 seconds.
  - KnowledgeBase::Translation...
    done in 0 seconds.
  - Organization...
    done in 0 seconds.
  - StatsStore...
    done in 0 seconds.
  - Ticket::Priority...
    done in 1 seconds.
  - Ticket::State...
    done in 1 seconds.
  - Ticket...
    done in 0 seconds.
  - User...
    done in 0 seconds.

Utilisation de Memcached pour le cache

L'utilisation de Memcached se fait simplement en indiquant l'adresse du service. Si ce dernier est installé sur la même machine que Zammad :

sudo zammad config:set MEMCACHE_SERVERS=127.0.0.1:11211

Dernier ajustements

Nous devons maintenant définir le nom de domaine qui sera utilisé ainsi que le protocole, dans cet example le nom de domaine sera support.thystips.net et en HTTPS. Nous allons ensuite redémarrer le service Zammad.

sudo zammad config:set ZAMMAD_FQDN=suport.thystips.net
sudo zammad config:set ZAMMAD_HTTP_TYPE=https
sudo systemctl restart zammad

Configuration du serveur web

Nous allons maintenant configurer notre serveur web, Nginx sera utilisé comme serveur web et nous verrons plus types de configurations.

Je vous laisse choisir uniquement la sous section qui convient à votre besoin :

• Déploiement uniquement pour des tests vous pouvez vous diriger vers la section : Sans SSL.
• Machine hébergeant Zammad directement accessible depuis l'extérieur (IP publique ou NAT) : Service exposée publiquement.
• Utilisation de Caddy comme reverse-proxy : Sans SSL puis Reverse proxy Caddy.

Sans SSL

Pour une utilisation en locale sans SSL nous allons récupérer le fichier d'exemple fourni avec le paquet Zammad.

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

Si Zammad est le seul hébergé par Nginx sur cette machine nous pouvons le définir comme site par défaut :

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

    server_name _;
[...]

sudo rm /etc/nginx/sites-enabled/default
sudo ln -s /etc/nginx/sites-{available,enabled}/zammad.conf
sudo systemctl restart nginx.service

Zammad est maintenant accessible sans SSL sur le port défini (ici 80) via l'IP de votre machine.

Service exposée publiquement

Si votre machine est accessible publiquement et que vous avez un domaine pointant vers cette dernière, par exemple support.thys.tips pour cet exemple.

Premièrement je vous recommande bien sécuriser votre machine en configurant correctement votre pare-feu (UFW sur ubuntu par défaut mais j'ai une préférence pour firewalld) et en utilisant une clé SSH pour la connexion à votre machine par exemple.

Afin de générer les certificats nécessaires nous allons utiliser certbot et l'exemple de configuration de Zammad sans SSL.

Les premières étapes sont proches de la section précédente :

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

Ensuite vous devez modifier server_name dans le fichier /etc/nginx/sites-available/zammad.conf afin d'y mettre le nom de domaine que vous avez choisi.

Vous pouvez ensuite activer et recharger la configuration Nginx :

sudo ln -s /etc/nginx/sites-{available,enabled}/zammad.conf
sudo systemctl restart nginx.service 

Nous pouvons ensuite passer à la génération des certificats :

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx --hsts --staple-ocsp -d <votre-domaine>

Vous pouvez indiquer que vous souhaitez la redirection HTTP vers HTTPS.

Certbot se chargera de modifier la configuration pour y inclure le nécessaire pour l'activation du SSL.

Votre instance de Zammad est maintenant accessible depuis : https://<votre-domaine>.

Reverse proxy Caddy

Après avoir suivi les instruction de la section Sans SSL nous pouvons configurer Caddy comme reverse proxy.

Caddy s'installe directement via son paquet :

sudo apt install caddy

La configuration de Caddy se fait dans le fichier `/etc/caddy/Caddyfile`, afin de simplifier la configuration ultérieure de plusieurs domaines j'utilise des blocs que je peux importer :

# Configuration par défaut
{
    # Email pour la génération des certificats
    email <votre-email-pour-letsencrypt>
}

# Définition des paramètres pour obtenir les logs sous forme de fichier
(logging) {
    log {
        output file /var/log/caddy/caddy-{args[0]}.log {
            roll_size 1Mib
            roll_local_time
            roll_keep 24
            roll_keep_for 7d
        }
    }
}

# Définition des entêtes pour la sécurité
(headers) {
    header {
        -server
        Permissions-Policy interest-cohort=()
        Strict-Transport-Security max-age=31536000;
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        Referrer-Policy no-referrer-when-downgrade
    }
}

Ensuite en dessous de cette configuration nous pouvons définir la configuration pour notre service Zammad :

<votre-domaine> {
	reverse_proxy http://<ip-de-zammad> {
		header_up X-Real-IP {remote_host}
	}
	encode zstd gzip
	import logging <nom-du-fichier-de-log>
	import headers
}

Voici la configuration que j'utilise :

support.thystips.net {
	reverse_proxy http://10.1.70.20 {
		header_up X-Real-IP {remote_host}
	}
	encode zstd gzip
	import logging support
	import headers
}

Il faut ensuite redémarrer le service associé afin que Caddy recharge sa configuration et commence la génération des certificats.

Vous instance Zammad est accessible depuis : https://<votre-domaine>.

Première connexion

Maintenant que vous avez accès à l'interface de Zammad vous devriez avoir la page suivante :

Nous allons pouvons procéder à la configuration de notre solution.

Commencez par créer votre compte administrateur :

Ensuite définir des informations de basiques au sujet de votre organisation :

La configuration d'un SMTP externe lors de la première configuration a tendance à être en échec, vous pouvez passer cette étape et revenir sur cette configuration par la suite :

Je vous recommande également de sauter l'étape suivant et de revenir sur la configuration des canaux de communication par la suite.

Configuration de Zammad

Nous pouvons maintenant passer à la configuration granulaire de notre plateforme support pour répondre à nos besoin.

L'accès aux paramètres se fait via l'icon en forme de roulette en bas à gauche de l'interface. Pensez également à bien valider les modification en appuyant sur le bouton Envoyer.

Nom de l'instance

Nous avons déjà défini le nom de notre organisation pendant la première connexion mais le nom de la plateforme est tout celui par défaut :

Groupes

Vous pouvez créer des groupes pour isoler différents services sur votre plateforme support. Ici j'ai simplement remplacer le groupe Users par un nom que j'ai défini.

Email

J'ai conseillé plus haut de sauter la configuration du serveur SMTP, nous allons y revenir maintenant.
La première chose à faire et de définir l'adresse qui devra être utilisée pour l'envoi des notifications :

Vous pouvez maintenant définir le serveur SMTP pour les notifications.

Enfin si vous souhaitez configurer la création de ticket par email vous pouvez définir des comptes et les attacher aux groupes définis plus haut.

Authentification externe

Il est possible de relier Zammad à un serveur LDAP afin de récupérer les utilisateurs depuis ce dernier.

On commence par définir les information pour joindre le serveur LDAP :

Puis la définition de l'utilisateur qu'utilisera Zammad pour s'y connecter :

Nous pouvons ensuite définir les attributs LDAP qui seront utilisés dans Zammad, cette configuration est adapté pour OpenLDAP et FreeIPA pour Active Directory l'attribut UID sera samAccountName. Vous pouvez également lié des groupes LDAP à des rôles dans Zammad comme ici où j'ai un groupe pour les administrateurs, un pour les agent et un dernier pour les personne ayant accès à la plateforme en tant que client.

Vous aurez ensuite un récapitulatif du nombre d'utilisateurs qui seront importés.

Premier ticket

La création de ticket peut se faire de plusieurs façon en fonction de votre configuration (interface web, mail, chat, etc.), comme nous avons configurer une boîte mail dans la section Email nous allons faire un test.

Voici le mail que je viens d'envoyer sur l'adresse configurée dans Zammad :

En retour j'ai automatiquement reçu ce mail pour confirmer la création de ma demande :

Il faudra que je pense à modifier ce message.

Maintenant allons faire un petit tour sur notre interface et probablement qu'il n'y aura pas de ticket 🥲
Si vous avez fait comme moi vous avez le rôle Admin mais pas le rôle Agent sauf que les tickets sont traités par les agents et non les admins donc on va rectifier ça !

Afin de se donner les droits d'Agent pour traiter les tickets :

Maintenant allons voir nos nouveaux tickets :

Comme vous pouvez le voir nous avons un nouveau ticket.

Une fois ouvert nous avons accès à une interface assez complète afin de répondre et classifier notre ticket.

Une fois les modification faites vous pouvez les valider avec le bouton Mise à jour en bas à droite.

J'espère que vous avez trouvez cet article utile !

N'hésitez pas à laisser un commentaire.