Zammad – mit Docker Compose und Traefik

Zammad ist eine leistungsstarke Open-Source-Helpdesk-Software, die eine vereinheitlichte Plattform für die Verwaltung von Kundenanfragen bietet, die aus verschiedenen Kommunikationskanälen wie E-Mail, sozialen Medien und Telefonanrufen stammen. Sie bietet eine klare und intuitive Benutzeroberfläche, die den Support-Teams die Möglichkeit gibt, Tickets zu erstellen, zuzuweisen und zu verfolgen.

Zusätzlich zur Ticketverwaltung verfügt Zammad über eine Reihe von Features, die das Kundenbeziehungsmanagement (CRM) unterstützen, eine Wissensdatenbank zur Organisation und Speicherung relevanter Informationen bereitstellen und verschiedene Automatisierungsoptionen ermöglichen. Zammad kann entweder auf einem privaten Server installiert oder als gehosteter Service genutzt werden.

0. Versionierung

1. Zielsetzung

Unser Ziel in dieser Anleitung ist es, den Installationsprozess von Zammad in einem Docker-Container auf einem Server zu erleichtern und zu erklären, wie man Traefik als Reverse Proxy konfiguriert.

2. Voraussetzung

Bevor wir mit der Installation und Konfiguration von Zammad beginnen, müssen wir einige Voraussetzungen erfüllen. Die wichtigste davon ist, dass wir Traefik ab v3.6 mit CrowdSec installieren und konfigurieren installiert haben.

Für Zammad ist mindestens empfohlen:

• 2 CPU-Kerne
• 4 GB RAM (+4 GB, wenn wir Elasticsearch auf demselben Server ausführen möchten)

Natürlich hängt dies letztendlich von der tatsächlichen Last durch gleichzeitige Agenten und Datenverkehr ab.

3. Verzeichnisse / Dateien anlegen

Um mit der Installation und Konfiguration von Zammad zu beginnen, müssen wir zuerst die notwendigen Verzeichnisse und Dateien erstellen. Dazu erstellen wir ein Hauptverzeichnis für Zammad und verschiedene Dateien, die wir im Verlauf dieser Anleitung benötigen.

Führen Sie die folgenden Befehle in Ihrer Linux-Shell aus, um das Verzeichnis und die Dateien zu erstellen:

# Hier erstellen wir das Hauptverzeichnis und ein Unterverzeichnis für Zammad
mkdir -p /opt/containers/zammad/zammad-backupCode-Sprache: PHP (php)

Sie dienen als Grundlage für die Installation und Konfiguration von Zammad in den nachfolgenden Schritten.

4. Erstellung der docker-compose.yml

4.1. Original Datei von Github

Die docker-compose.yml Datei ist das Herzstück unserer Docker Konfiguration. Sie definiert, welche Dienste gestartet werden und wie sie miteinander interagieren. Um diese Datei zu erstellen, nehmen wir uns die Vorlage aus der offiziellen Zammad-Dokumentation als Basis, welche unter folgendem Link zu finden ist: https://docs.zammad.org/en/latest/install/docker-compose.html.

Die docker-compose.yml Vorlage befindet sich im Zammad Github-Repository: https://github.com/zammad/zammad-docker-compose. Wir kopieren den Inhalt dieser Datei in unsere neu erstellte docker-compose.yml:

nano /opt/containers/zammad/docker-compose.yml

In die geöffnete Datei kopieren wir folgenden Inhalt:

---
x-shared:
  zammad-service: &zammad-service
    environment: &zammad-environment
      MEMCACHE_SERVERS: ${MEMCACHE_SERVERS:-zammad-memcached:11211}
      POSTGRESQL_DB: ${POSTGRES_DB:-zammad_production}
      POSTGRESQL_HOST: ${POSTGRES_HOST:-zammad-postgresql}
      POSTGRESQL_USER: ${POSTGRES_USER:-zammad}
      POSTGRESQL_PASS: ${POSTGRES_PASS:-zammad}
      POSTGRESQL_PORT: ${POSTGRES_PORT:-5432}
      POSTGRESQL_OPTIONS: ${POSTGRESQL_OPTIONS:-?pool=50}
      POSTGRESQL_DB_CREATE:

      # Redis standalone
      REDIS_URL: ${REDIS_URL:-redis://zammad-redis:6379}
      # Redis sentinel
      REDIS_SENTINELS:
      REDIS_SENTINEL_NAME:
      REDIS_USERNAME:
      REDIS_PASSWORD:
      REDIS_SENTINEL_USERNAME:
      REDIS_SENTINEL_PASSWORD:

      S3_URL:
      # Backup settings
      BACKUP_DIR: "${BACKUP_DIR:-/var/tmp/zammad}"
      BACKUP_TIME: "${BACKUP_TIME:-03:00}"
      BACKUP_ON_START: "${BACKUP_ON_START:-false}"
      HOLD_DAYS: "${HOLD_DAYS:-10}"
      TZ: "${TZ:-Europe/Berlin}"
      # Allow passing in these variables via .env:
      AUTOWIZARD_JSON:
      AUTOWIZARD_RELATIVE_PATH:
      ELASTICSEARCH_ENABLED:
      ELASTICSEARCH_SCHEMA:
      ELASTICSEARCH_HOST:
      ELASTICSEARCH_PORT:
      ELASTICSEARCH_USER:
      ELASTICSEARCH_PASS:
      ELASTICSEARCH_NAMESPACE:
      ELASTICSEARCH_REINDEX:
      NGINX_PORT:
      NGINX_CLIENT_MAX_BODY_SIZE:
      NGINX_SERVER_NAME:
      NGINX_SERVER_SCHEME:
      RAILS_TRUSTED_PROXIES:
      ZAMMAD_HTTP_TYPE:
      ZAMMAD_FQDN:
      ZAMMAD_WEB_CONCURRENCY:
      ZAMMAD_MANAGE_SESSIONS_JOBS_WORKERS:
      ZAMMAD_PROCESS_SESSIONS_JOBS_WORKERS:
      ZAMMAD_PROCESS_SCHEDULED_JOBS_WORKERS:
      ZAMMAD_PROCESS_DELAYED_JOBS_WORKERS:
      ZAMMAD_PROCESS_DELAYED_JOBS_WORKER_THREADS:
      ZAMMAD_PROCESS_DELAYED_AI_JOBS_WORKERS:
      ZAMMAD_PROCESS_DELAYED_AI_JOBS_WORKER_THREADS:
      ZAMMAD_PROCESS_DELAYED_COMMUNICATION_INBOUND_JOBS_WORKERS:
      ZAMMAD_PROCESS_DELAYED_COMMUNICATION_INBOUND_JOBS_WORKER_THREADS:
      ZAMMAD_OTRS_IMPORT_READ_TIMEOUT:
      ZAMMAD_OTRS_IMPORT_TOTAL_TIMEOUT:
      ZAMMAD_HTTP_OPEN_TIMEOUT:
      ZAMMAD_HTTP_READ_TIMEOUT:
      ZAMMAD_HTTP_TOTAL_TIMEOUT:
      ZAMMAD_HTTP_AI_READ_TIMEOUT:
      ZAMMAD_HTTP_AI_TOTAL_TIMEOUT:
      ZAMMAD_HTTP_ELASTICSEARCH_READ_TIMEOUT:
      ZAMMAD_HTTP_ELASTICSEARCH_TOTAL_TIMEOUT:
      ZAMMAD_HTTP_ELASTICSEARCH_REINDEX_READ_TIMEOUT:
      ZAMMAD_HTTP_ELASTICSEARCH_REINDEX_TOTAL_TIMEOUT:
      ZAMMAD_HTTP_IMPORT_ATTACHMENT_READ_TIMEOUT:
      ZAMMAD_HTTP_IMPORT_ATTACHMENT_TOTAL_TIMEOUT:
      ZAMMAD_HTTP_WEBHOOK_READ_TIMEOUT:
      ZAMMAD_HTTP_WEBHOOK_TOTAL_TIMEOUT:

      # Allow disabling individual background services in the scheduler container.
      ZAMMAD_PROCESS_SESSIONS_JOBS_DISABLE:
      ZAMMAD_MANAGE_SESSIONS_JOBS_DISABLE:
      ZAMMAD_PROCESS_SCHEDULED_JOBS_DISABLE:
      ZAMMAD_PROCESS_DELAYED_JOBS_DISABLE:
      ZAMMAD_PROCESS_DELAYED_AI_JOBS_DISABLE:
      ZAMMAD_PROCESS_DELAYED_COMMUNICATION_INBOUND_JOBS_DISABLE:

      ZAMMAD_GRAPHQL_INTROSPECTION:
      ZAMMAD_AI_API_URL:
      ZAMMAD_AI_TOKEN:
      ZAMMAD_UI_BULK_BACKGROUND_UPDATE_THRESHOLD:
      ZAMMAD_SETTING_TTL:
      ZAMMAD_SAFE_MODE:
      ZAMMAD_WEBSOCKET_SESSION_STORE_FORCE_FS_BACKEND:
      ZAMMAD_RAILSSERVER_PORT:

      # ZAMMAD_SESSION_JOBS_CONCURRENT is deprecated, please use ZAMMAD_PROCESS_SESSIONS_JOBS_WORKERS instead.
      ZAMMAD_SESSION_JOBS_CONCURRENT:
      # Variables used by ngingx-proxy container for reverse proxy creations
      # for docs refer to https://github.com/nginx-proxy/nginx-proxy
      VIRTUAL_HOST:
      VIRTUAL_PORT:
      # Variables used by acme-companion for retrieval of LetsEncrypt certificate
      # for docs refer to https://github.com/nginx-proxy/acme-companion
      LETSENCRYPT_HOST:
      LETSENCRYPT_EMAIL:

    image: ${IMAGE_REPO:-ghcr.io/zammad/zammad}:${VERSION:-7.1.3-0000}
    init: true
    restart: ${RESTART:-always}
    volumes:
      - ./zammad-backup:/var/tmp/zammad:ro # needed for waiting on restore operations
      - zammad-storage:/opt/zammad/storage
    depends_on:
      zammad-memcached:
        condition: service_healthy
      zammad-postgresql:
        condition: service_healthy
      zammad-redis:
        condition: service_healthy

services:
  zammad-backup:
    <<: *zammad-service
    command: ["zammad-backup"]
    volumes:
      - ./zammad-backup:/var/tmp/zammad
      - zammad-storage:/opt/zammad/storage
    user: 0:0

  zammad-elasticsearch:
    image: elasticsearch:${ELASTICSEARCH_VERSION:-9.5.2}
    restart: ${RESTART:-always}
    volumes:
      - elasticsearch-data:/usr/share/elasticsearch/data
    environment:
      discovery.type: single-node
      xpack.security.enabled: "false"
      ES_JAVA_OPTS: ${ELASTICSEARCH_JAVA_OPTS:--Xms1g -Xmx1g}

  zammad-init:
    <<: *zammad-service
    command: ["zammad-init"]
    restart: on-failure
    user: 0:0

  zammad-memcached:
    command: memcached -m 256M
    image: memcached:${MEMCACHE_VERSION:-1.6.45-alpine}
    restart: ${RESTART:-always}
    healthcheck:
      test: ["CMD", "nc", "-z", "127.0.0.1", "11211"]
      interval: 10s
      timeout: 5s
      start_period: 10s
      retries: 5

  zammad-nginx:
    <<: *zammad-service
    command: ["zammad-nginx"]
    init: false
    depends_on:
      zammad-railsserver:
        condition: service_healthy

  zammad-postgresql:
    environment:
      POSTGRES_DB: ${POSTGRES_DB:-zammad_production}
      POSTGRES_USER: ${POSTGRES_USER:-zammad}
      POSTGRES_PASSWORD: ${POSTGRES_PASS:-zammad}
    image: postgres:${POSTGRES_VERSION:-17.11-alpine}
    restart: ${RESTART:-always}
    volumes:
      - postgresql-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      start_period: 60s
      retries: 5

  zammad-railsserver:
    <<: *zammad-service
    command: ["zammad-railsserver"]
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://127.0.0.1:${ZAMMAD_RAILSSERVER_PORT:-3000}"]
      interval: 30s
      timeout: 5s
      start_period: 120s
      retries: 3

  zammad-redis:
    image: redis:${REDIS_VERSION:-8.10.1-alpine}
    restart: ${RESTART:-always}
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      start_period: 10s
      retries: 5

  zammad-scheduler:
    <<: *zammad-service
    command: ["zammad-scheduler"]

  zammad-websocket:
    <<: *zammad-service
    command: ["zammad-websocket"]

volumes:
  elasticsearch-data:
    driver: local
  postgresql-data:
    driver: local
  redis-data:
    driver: local
  zammad-storage:
    driver: localCode-Sprache: PHP (php)

Bei dieser Datei wurde das Zammad-Backup Volume entfernt, damit wir später einfacher auf unsere Backups zugreifen können. Ebenfalls wurden die Ports bei nginx entfernt.

4.2. Erstellen der docker-compose.override.yml

Um Änderungen an den Servicekonfigurationen vorzunehmen, ohne die ursprüngliche docker-compose.yml-Datei zu ändern, erstellen wir eine docker-compose.override.yml. Diese Methode behält die Integrität der Hauptkonfigurationsdatei bei und erleichtert die Wartung, sollten an der Originaldatei signifikante Änderungen vorgenommen werden.

Erstellen Sie die docker-compose.override.yml Datei:

nano /opt/containers/zammad/docker-compose.override.yml

Fügen Sie den folgenden Inhalt ein:

services:
  zammad-nginx:
    networks:
      - default
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.zammad.rule=Host(`${ZAMMAD_FQDN}`)"
      - "traefik.http.routers.zammad.entrypoints=websecure"
      - "traefik.http.routers.zammad.tls.certresolver=http_resolver"
      - "traefik.http.routers.zammad.middlewares=default@file"
      - "traefik.http.services.zammad.loadbalancer.server.port=${NGINX_PORT:-8080}"

networks:
  proxy:
    name: proxy
    external: trueCode-Sprache: JavaScript (javascript)

In dieser Datei definieren wir spezifische Netzwerk- und Umgebungsparameter für unsere Zammad-Dienste und passen die Nginx Konfiguration an Traefik an.

Diese docker-compose.override.yml Datei ermöglicht uns eine flexible und wartungsfreundliche Konfiguration unserer Zammad-Installation. Durch die Verwendung dieser Datei können wir Änderungen an unserer Konfiguration vornehmen, ohne die ursprüngliche docker-compose.yml-Datei zu beeinträchtigen, was insbesondere bei zukünftigen Updates und Upgrades nützlich ist.

5. Erstellung der .env-Datei

Jetzt benötigen wir einige spezifische Umgebungsvariablen für unsere Zammad-Installation. Diese Variablen sind in einer .env Datei definiert.

Wir öffnen unsere neue Datei namens .env im Verzeichnis /opt/containers/zammad/

nano /opt/containers/zammad/.env

und kopieren die folgenden Zeilen in die .env Datei:

# --- Version ---------------------------------------------------------------
# Feste Version eintragen oder kann auch latest sein
VERSION=7.1.3-0000

# --- Basis -----------------------------------------------------------------
TZ=Europe/Berlin
ZAMMAD_HTTP_TYPE=https
ZAMMAD_FQDN=zammad.euredomain.de

# --- Reverse Proxy ---------------------------------------------------------
NGINX_PORT=8080
NGINX_SERVER_SCHEME=https
NGINX_CLIENT_MAX_BODY_SIZE=50M
RAILS_TRUSTED_PROXIES=127.0.0.1,::1,172.16.0.0/12

# --- Datenbank -------------------------------------------------------------
POSTGRES_DB=zammad_production
POSTGRES_USER=zammad
POSTGRES_PASS=HIER-32-ZEICHEN-EINSETZEN

# --- Elasticsearch ---------------------------------------------------------
ELASTICSEARCH_ENABLED=true
ELASTICSEARCH_JAVA_OPTS=-Xms1g -Xmx1g

# --- Backup ----------------------------------------------------------------
BACKUP_DIR=/var/tmp/zammad
BACKUP_TIME=03:00
BACKUP_ON_START=false
HOLD_DAYS=10Code-Sprache: PHP (php)

Generiert entsprechend nun noch ein sicheres Postgres Passwort:

head -c 4096 /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32; echoCode-Sprache: PHP (php)

Ansonsten müsst ihr natürlich die Domain noch anpassen. Am Schluss passen wir noch die Rechte an:

chmod 600 /opt/containers/zammad/.env

Hier kommt ihr zur offiziellen .env Datei, wo noch viele weitere Parameter enthalten sind.

Bei Zammad auf der Homepage bekommt ihr eine Erklärung der Variablen: https://docs.zammad.org/en/latest/appendix/environment-variables.html

6. Elasticsearch optimieren

Um sicherzustellen, dass Elasticsearch effizient funktioniert, ist es möglicherweise notwendig, den vm.max_map_count-Wert auf dem Host-System selbst anzupassen.

Der Wert für vm.max_map_count bestimmt die maximale Anzahl von Speicherzuordnungen (Memory Mappings), die ein Prozess erstellen kann. Elasticsearch benötigt oft einen höheren Wert als den standardmäßigen, um optimal zu funktionieren.

Dafür öffnen wir die Datei /etc/sysctl.conf auf dem Host-System:

nano /etc/sysctl.conf

Wur fügen die folgende Zeile am Ende der Datei hinzu und speichern die Änderungen:

vm.max_map_count=262144

Wenn du dir nicht sicher bist, welchen Wert du einstellen sollen, beginne mit dem doppelten des aktuellen Werts und erhöhe diesen schrittweise, bis Elasticsearch erfolgreich startet. Die offizielle Dokumentation empfiehlt einen Wert von mindestens 262144.

Wir starten unser System neu oder laden Sie die Konfiguration mit dem folgenden Befehl neu, um die Änderungen wirksam zu machen:

sysctl -p

Mit diesem Schritt stellen wir sicher, dass Elasticsearch die erforderlichen Ressourcen zur Verfügung hat, um optimal zu funktionieren.

7. Zammad starten

Nachdem alle Vorbereitungen abgeschlossen sind, können wir nun Zammad starten. Wir wechseln zuerst in das Verzeichnis, in dem sich die Docker-Compose- und .env-Dateien befinden:

cd /opt/containers/zammad/

Jetzt können wir Zammad mit dem Befehl docker compose up -d starten:

docker compose up -d

Dieser Befehl startet alle Dienste, die in der docker-compose.yml– und docker-compose.override.yml-Datei definiert sind, im Hintergrund und lässt sie laufen, selbst wenn wir die Terminal-Sitzung beenden.

Die Option -d steht für “detached” und bedeutet, dass die Container im Hintergrund laufen und die Shell nach dem Start der Container zur Verfügung steht.

8. FAQ

8.1. Warum wählen wir in diesem Setup Docker Volumes statt lokaler Mounts, und warum ist das Backup die Ausnahme zu dieser Regel?

Die Wahl, Docker Volumes anstelle von lokalen Mounts zu verwenden, hängt in erster Linie mit den besonderen Eigenschaften von Zammad und dessen Verwendung von verschiedenen Containern, insbesondere solchen, die auf Java basieren, zusammen. Java-basierte Anwendungen können bei unsachgemäßer Konfiguration zu Benutzerrechtsproblemen auf dem Server führen. Die Benutzung von Docker Volumes erleichtert das Management von Benutzerrechten, da Docker Volumes standardmäßig die korrekten Berechtigungen und Besitzer haben.

Zudem ist der Prozess der Anpassung der Docker-Compose-Datei, um lokale Mounts zu verwenden, tendenziell komplizierter und zeitaufwendiger. Er kann auch die Wartungsfreundlichkeit beeinträchtigen, da jede zusätzliche Anpassung der ursprünglichen Docker-Compose-Datei die Wahrscheinlichkeit erhöht, dass zukünftige Updates Probleme verursachen.

Aus all diesen Gründen habe ich mich dazu entschieden, in dieser Anleitung die Verwendung von Docker Volumes zu empfehlen und mich auf die bereitgestellte .env-Datei zu verlassen, anstatt eine eigene zu erstellen. Das Ziel ist es, einen klaren, einfach zu folgenden und wartungsfreundlichen Prozess zu gewährleisten.

Eine wichtige Ausnahme hierbei sind die Backups. Für diese nutzen wir lokale Mounts, um eine einfache Integration in bestehende Backup-Lösungen wie Borg Backup zu ermöglichen. Lokale Backups ermöglichen uns auch einen schnelleren Zugriff auf Backup-Dateien und eine flexiblere Handhabung der Backup-Datensicherung.

8.2. Wann werden Backups erstellt und wo kann ich diese finden?

In unserer .env haben wir folgendes hinterlegt:

BACKUP_DIR=/var/tmp/zammad
BACKUP_TIME=03:00
BACKUP_ON_START=false
HOLD_DAYS=10Code-Sprache: JavaScript (javascript)

Es werden also um 03:00 Uhr Backups erstellt und insgesamt 10 Tage gehalten. Der Speicherort befindet sich hier:

ls -l /opt/containers/zammad/zammad-backup/

Dort sollte auch bereits nach dem ersten Start ein Backup erstellt worden sein. Weitere Infos zum Backup findet ihr hier.

Hinweis

Hinweis zu Kommentaren

Wenn etwas nicht funktioniert, gehe noch einmal alle einzelnen Punkte in der Anleitung durch. Ich habe die Anleitung mehrfach getestet. Wenn du sicher bist, dass du alles richtig konfiguriert hast und das noch einmal überprüft hast, dann hinterlasse gerne einen Kommentar. Der Blog wird von Christian betrieben und er, sowie alle Co-Autoren, bemühen uns, alle Fragen und Probleme zu lösen – allerdings ist dies auch immer von unserer verfügbaren Zeit abhängig!

Bitte abonniert goNeuland, damit dieser Blog uns auch weiterhin viele Jahre Freude bereiten kann 😉