Zammad

Anforderungen

Zammad ist ein relativ umfangreiches, mächtiges und modernes OSS Helpdesk Tool. Für die Installation wird benötigt:

• eine (Sub)Domain
• 2 bis 4 GB RAM (Schätzung, eure Erfahrung kann abweichen, je nach Nutzung)
• ruby
• nodejs
• mehrere Daemons für Hintergrunddienste (worker, websocket)
• evtl. noch ElasticSearch für Volltextsuche

Installation

Die Installation orientiert sich an dieser Anleitung und wurde für zammad 6.3 verfasst. Einige HS spezifische Abweichungen gibt es jedoch.

• https://docs.zammad.org/en/latest/install/source.html

User anlegen

Für diese Anleitung wird angenommen das der User unter dem zammad laufen soll xyz00-zammad im Packet xyz00 ist.

Installation ruby / ruby env

Prüfe die Version von ruby die zammad benötigt hier.

Für diese Anleitung nehmen wir Version 3.2.3 an für zammad 6.3.

Die Installationsanleitung für rubyenv und ruby findet sich unter RubyRBEnv.

Verifiziere das die Installation geklappt hat mit

 ruby -v 

dies sollte der herausgesuchten Versionsnummer entsprechen

Installation nodejs

Prüfe die Version von nodejs die zammad benötigt hier.

Für diese Anleitung nehmen wir Version 20 an für zammad 6.3.

Verifiziere das die Installation geklappt hat mit

 node -v 

dies sollte der herausgesuchten Versionsnummer entsprechen

Installation Redis

Siehe Redis

Umgebungsvariablen

Meine `.profile`, `.bashrc`, `.bash_profile` sahen dann wie folgt aus (möglicherweise gibt es hier optimierungspotential)

Die Datei `.bash_profile`:

 . ~/.profile
 . ~/.bashrc

Die Datei `.profile` (vgl instalation ruby und nodejs):

 #ruby
 export PATH="$HOME/.rbenv/bin:$PATH"
 eval "$(rbenv init -)"
 #nodejs
 export NVM_DIR="$HOME/.nvm"
 [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
 [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

und die Datei `.bashrc`. Quellen vgl. [1] und [2]

 export REDIS_URL=redis://:<your-password-goes-here>@127.0.0.1:<port>

 export RAILS_ENV=production

Dann entweder alles neu einlesen oder einmal aus und wieder einloggen. Wenn alles geklappt hat, sollten die folgenden Befehle alle sinnvolle Ausgaben liefern

 echo $RAILS_ENV # Ausgabe: production
 ruby -v # Ausgabe vgl. oben
 nodejs -v #  Ausgabe vgl. oben

Installation von Zammad

Zuerst laden wir zammad herunter, entpacken es, und installieren die dependencies (nur production)

 mkdir zammad
 cd zammad
 wget -O - https://ftp.zammad.com/zammad-latest.tar.gz |tar -xvvz
 bundle config set --local without 'test development mysql'
 bundle install
 

Dann tragen wir die zugangsdaten der postgres Datenbank ein (auf HS Admin selbst erstellen) hier: beides `xyz00_zammad` Mit folgendem Inhalt (Einrückung beachten!):

 nano config/database.yml
 
 # config/database.yml
 production:
   adapter: postgresql
   host: localhost
   database: xyz00_zammad
   pool: 50
   timeout: 5000
   encoding: utf8
   username: xyz00_zammad
   password: changeme

Wenn alles stimmt sollten sich die folgenden Befehle ohne Fehler ausführen lassen und die Datenbanktabellen sowie die statischen Dateien zum ausliefern anlegen

  rake db:migrate
  rake assets:precompile

Zammad ausliefern

Um via Browser auf zammad zugreifen zu können kann es via Phusion Passenger ausgeliefert werden. Dazu muss im HS Admin eine Domain aufgeschaltet werden. Dann wird:

• die .htaccess wie folgend gesetzt werden
• der zammad ordner nach app-ssl gelinkt werden
• und der statische content in htdocs-ssl
• Optional kann das Domain Template noch um die subdomains bereinigt werden (2. Befehl)

 cd ~/doms/zammad.example.org/
 rm -r subs*
 rm -r htdocs-ssl
 rm -r app-ssl
 ln -s ~/zammad app-ssl
 ln -s ~/zammad/public htdocs-ssl
 nano .htaccess

In HS-Admin muss unter der Domain dann folgende Eigenschaft bei Passenger gesetzt werden:

 PassengerRuby /home/pacs/xyz00/users/zammad/.rbenv/shims/ruby

 # Inhalt .htaccess
 DirectoryIndex disabled
 RewriteEngine On
 RewriteBase /

 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteCond %{HTTP:Connection} Upgrade [NC]
 RewriteCond %{HTTP:Upgrade} websocket [NC]
 RewriteRule .* ws://127.0.0.1:6042/%{REQUEST_URI}  [P,L]

 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteCond %{REQUEST_FILENAME} !-l
 RequestHeader set X-Forwarded-Proto "https"
 RewriteRule .* http://127.0.0.1:6041/%{REQUEST_URI} [proxy,last]

Wenn alles geklappt hat sollte auf der Domain das restliche Web-basierte Setup zu sehen sein. Dort muss dann auch der andere HS Postfach User eingetragen werden. Theoretisch könnte man das auf dem gleichen Account abwickeln, ich persönlich würde es allerdings trennen. Piping wie bei manch andren Mailbasierten Anwendungen scheint nicht so einfach möglich zu sein (needs more investigation)

Hintergrunddienste

Damit der Websocket-Server und der Hintergrund Worker ordentlich laufen müssen folgende Befehle ausgeführt werden. Die IP Adresse und der Port beim Socket werden aus den Enviroment Variablen von oben bezogen, können allerdings auch manuell gesetzt werden.

 cd zammad
 bundle exec script/background-worker.rb start
 bundle exec script/websocket-server.rb -b ${ZAMMAD_BIND_IP} -p ${ZAMMAD_WEBSOCKET_PORT} start

Empfohlen: Monit

Ich habe alles monit spezifische in den ordner monit gepackt

 cd   
 mkdir monit
 cd monit

Zum starten habe ich ein kleines start und stop script (für monit) erstellt (lange zeile ggf. beachten)

 nano start-worker.sh

 #!/bin/bash
 . ~/.bash_profile
 cd ~/zammad
 exec  ${BUNDLE_BINARY} exec script/background-worker.rb start > ~/monit/worker.log 2>&1 &
 echo $! > ~/monit/worker.pid

 nano start-websocket.sh

 #!/bin/bash
 . ~/.bash_profile
 cd ~/zammad
 # warnung, der  socket  produziert relativ viel log output im normalen Betrieb ggf. anpassen
 exec ${BUNDLE_BINARY} exec script/websocket-server.rb -b ${ZAMMAD_BIND_IP} -p ${ZAMMAD_WEBSOCKET_PORT}  start > ~/monit/socket.log 2>&1 & 
 echo $! > ~/monit/socket.pid

 nano stop-worker.sh

 kill $( cat ~/monit/worker.pid )

 nano stop-websocket.sh

 kill $( cat ~/monit/socket.pid )

Das dann alles noch in der `~/.monitrc` zusammenführen (achtung einige xyz00, zammad (user) und Mail Platzhalter):

 nano ~/.monitrc

 set daemon 60 with start delay 10
 set logfile /home/pacs/xyz00/users/zammad/monit/monit.log
 set idfile /home/pacs/xyz00/users/zammad/monit/monit.id
 set statefile /home/pacs/xyz00/users/zammad/monit/monit.state
 set mailserver localhost
 set mail-format { from: monit@your-domain.com }
 #set httpd port 39008 address localhost
 #    allow zammadadmin:ein-monit-passwort
 check process zammad_worker with pidfile /home/pacs/xyz00/users/zammad/monit/worker.pid
   start program "/home/pacs/xyz00/users/zammad/monit/start-worker.sh"
   stop program "/home/pacs/xyz00/users/zammad/monit/stop-worker.sh"
 check process zammad_socket with pidfile /home/pacs/opa00/users/zammad/monit/socket.pid
   start program "/home/pacs/xyz00/users/zammad/monit/start-websocket.sh"
   stop program "/home/pacs/xyz00/users/zammad/monit/stop-websocket.sh"

Noch schnell die rechte der 4 scripts anpassen:

  chmod u+x ~/monit/*.sh

Monit kann dann mit

  monit

gestartet werden.

Sobald monit einmal erfolgreich anlief sollte der monit Ordner so aussehen:

 ls -lh

 -rw-r--r-- 1 xyz00-zammad xyz00    32 Feb 23 11:59 monit.id
 -rw-r--r-- 1 xyz00-zammad xyz00  2867 Feb 24 23:46 monit.log
 -rw------- 1 xyz00-zammad xyz00   800 Feb 24 13:20 monit.state
 -rw-r--r-- 1 xyz00-zammad xyz00 41048 Feb 25 00:49 socket.log
 -rw-r--r-- 1 xyz00-zammad xyz00     5 Feb 24 23:45 socket.pid
 -rwxr--r-- 1 xyz00-zammad xyz00   209 Feb 24 23:45 start-websocket.sh
 -rwxr--r-- 1 xyz00-zammad xyz00   161 Feb 24 23:27 start-worker.sh
 -rwxr--r-- 1 xyz00-zammad xyz00    34 Feb 24 23:30 stop-websocket.sh
 -rwxr--r-- 1 xyz00-zammad xyz00    34 Feb 23 11:53 stop-worker.sh
 -rw-r--r-- 1 xyz00-zammad xyz00     0 Feb 24 23:38 worker.log
 -rw-r--r-- 1 xyz00-zammad xyz00     5 Feb 24 23:38 worker.pid

Optional: Mail-Piping

Um ein bisschen (viel) Last vom Background-Worker zu nehmen kann Mailpiping eingerichtet werden. Dafür sollte vermutlich zuerst der Webinstaller mit einer anderen IMAP/SMTP config durchgeklickt werden. Zusätzlich reduziert sich die Latenz von Maileingang bis Ticketeingang ein wenig.

Ausgangsserver auf sendmail festlegen

Der folgende Code schnippsel legt einen Mail-Kanal an, ohne einen dedizierten Eingang der regelmäßig abgerufen werden müsste. Quelle [3]

 rails r "Channel.create(area: 'Email::Account', options: { inbound: { adapter: 'null', options: {} }, outbound: { adapter: 'sendmail' } }, active: true, preferences: { editable: false }, updated_by_id: 1, created_by_id: 1)"

Optional: Elasticsearch Anbindung

Weiteren User nach Elasticsearch anlegen. Dieser muss dann mit zammad verknüpft werden. Hier wird der Port 39200 angenommen.

 cd ~/zammad
 rails r "Setting.set('es_url', 'http://localhost:39200')"
 rails r "Setting.set('es_user', 'elasticsearch')"
 rails r "Setting.set('es_password', 'changeme')"

Um Elasticsearch wieder zu deaktivieren einfach die URL durch einen leeren string ersetzen.

Es wird für Zammad 5.x ein ElasticSearch 7.x benötigt. siehe auch https://docs.zammad.org/en/latest/install/elasticsearch.html

Zum ersten Einrichten, oder auch zum Testen der Verbindung:

cd ~/zammad
rake searchindex:rebuild --trace

Problem:

 create indexes...rake aborted!
 Can't find config setting 'es_multi_index'

Lösung:

  psql -U xyz00_zammad
    INSERT INTO settings \
      (title, name, description, area, frontend, created_at, updated_at) \
      VALUES ('ElasticSearch Multi Index', 'es_multi_index', \
      '','SearchIndex::ElasticSearch', \
      false, '2023-03-15 01:00:00', '2023-03-15 01:00:00');
  cd ~/zammad
  rails r "Setting.set('es_multi_index', false)"
  rake searchindex:rebuild --trace

Zammad Upgrade

Diese Seite muss überarbeitet werden

Diese Seite wurde als Baustelle gekennzeichnet, weil sie überarbeitet werden muss. Eine Begründung dafür findest du auf der Diskussionsseite. Bitte hilf mit, diese Seite zu verbessern!

killall -u $USER
killall -u $USER 9

cp -a zammad zammad-old
cd zammad
rm -Rf app
rm -Rf public/assets
wget -O - https://ftp.zammad.com/zammad-5.3.1.tar.gz |tar -xvvz

bundle config set --local without 'test development mysql'
bundle install

	Geht nicht, Ruby 2.2.5 fehlt!

cd
rbenv install 2.5.5

	Geht nicht, Rbenv ist zu alt!

cd ~/.rbenv/plugins/ruby-build
git pull
cd
rbenv install 2.5.5
rbenv global 2.5.5
rbenv local 2.5.5

cd zammad
gem install bundle
gem install bundler
bundle config set --local without 'test development mysql'
bundle install

Geht nicht, Bundler 1.17.x wird gebraucht.

gem install bundler==1.17.3

	Geht auch nicht.
	Dann hacken wir das mal versuchsweise ins Lock.

vim Gemfile.lock

bundle config set --local without 'test development mysql'
bundle install

	Es fehlen Libs.
	HS bitte installieren...
	[...]
	Danke!

bundle config set --local without 'test development mysql'
bundle install
export RAILS_ENV=production
rake db:migrate
rake assets:clean
rake zammad:flush:cache
rake assets:precompile

/usr/bin/supervisord -c $HOME/supervisor/etc/supervisord.conf

Nach Problemen mit Assets muss man den Dienst nochmal neustarten.

Nach dem Update testen, ob ElasticSearch noch funktioniert, eventuell muss auch ElasticSearch aktualisiert werden.

weiterführende Links

• Zammad Dokumentation
• Ansible Playbook für Hostsharing