Install from source¶
Note
The source installation is the most difficult installation type of Zammad. If you’re not too experienced with Linux and all that, you may want to use another installation type:
sudo
after direct user changes.
In all other situations you can expect root
being in charge.Hint
🔎 Looking for MacOS hints? You can find outdated documentation here.
Prerequisites¶
Software dependencies¶
Please ensure that you already provided mentioned Software requirements.
Also ensure to provide your database server and web server at this point.
Setup Elasticsearch¶
Elasticsearch is a dependency of Zammad and needs to be provided before installing Zammad. Please take a look at the following page: Set up Elasticsearch.
Ensure correct locale¶
For Zammad to function correctly, your system has to use the correct locales.
List your current locale settings.
$ locale |grep "LANG="
If above does not return <lang_code>.utf8
you can correct this issue as follows.
$ apt install locales
$ locale-gen en_US.UTF-8
$ echo "LANG=en_US.UTF-8" > /etc/default/locale
List your current locale settings.
$ locale |grep "LANG="
If above does not return <lang_code>.utf8
you can correct this issue as follows.
$ localectl set-locale LANG=en_US.utf8
List your current locale settings.
$ localectl status |grep "LC_CTYPE"
If above does not return <lang_code>.utf8
you can correct this issue as follows.
$ localectl set-locale LC_CTYPE=en_US.UTF-8
Hint
By default OpenSUSE uses POSIX
as LANG
value for the root
user. Learn more about this within the OpenSUSE documentation.
This does not affect other users and thus can be ignored.
Add user¶
$ useradd zammad -m -d /opt/zammad -s /bin/bash
$ groupadd zammad
Installation¶
Step 1: Get the source¶
Note
Not all distributions ship wget
and tar
by default, you may need to
install it manually.
Get the latest stable release of Zammad here. This file will be updated whenever new bug-fixes are applied, so you can update from this URL regularly.
$ cd /opt
$ wget https://ftp.zammad.com/zammad-latest.tar.gz
$ tar -xzf zammad-latest.tar.gz --strip-components 1 -C zammad
$ chown -R zammad:zammad zammad/
$ rm -f zammad-latest.tar.gz
Step 2: Install dependencies¶
Note
Zammad requires specific ruby versions. Adapt the commands below if you install older versions. A list of required versions can be found on the Software requirements page.
$ apt update
$ apt install postgresql postgresql-contrib
$ systemctl start postgresql
$ systemctl enable postgresql
# CentOS 7
$ yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
$ yum install postgresql14-server postgresql14-contrib
$ postgresql14-setup initdb
$ systemctl start postgresql14
$ systemctl enable postgresql14
# CentOS 8
$ yum install postgresql-server postgresql-contrib
$ postgresql-setup initdb
$ systemctl start postgresql
$ systemctl enable postgresql
$ zypper refresh
$ zypper install postgresql postgresql-server postgresql-contrib
# openSuSE 15 also requires:
$ zypper install postgresql-server-devel
$ systemctl start postgresql
$ systemctl enable postgresql
- Install Node.js
$ apt update $ apt install curl $ curl -fsSL https://deb.nodesource.com/setup_lts.x | bash - $ apt install nodejs
- Install RVM
$ apt install curl git patch build-essential bison zlib1g-dev libssl-dev libxml2-dev libxml2-dev autotools-dev\ libxslt1-dev libyaml-0-2 autoconf automake libreadline-dev libyaml-dev libtool libgmp-dev libgdbm-dev libncurses5-dev\ pkg-config libffi-dev libimlib2-dev gawk libsqlite3-dev sqlite3 software-properties-common $ apt-add-repository -y ppa:rael-gc/rvm $ apt update $ apt install rvm
- Set relevant Environment variables
# Set rails environment specific things $ echo "export RAILS_ENV=production" >> /opt/zammad/.bashrc $ echo "export RAILS_SERVE_STATIC_FILES=true" >> /opt/zammad/.bashrc $ echo "rvm --default use 3.1.3" >> /opt/zammad/.bashrc # Debian, CentOS & OpenSuSE $ echo "source /usr/local/rvm/scripts/rvm" >> /opt/zammad/.bashrc # Ubuntu $ echo "source /usr/share/rvm/scripts/rvm" >> /opt/zammad/.bashrc
- Install Ruby Environment
# Add zammad user to RVM group $ usermod -a -G rvm zammad # Install Ruby 3.1.3 $ su - zammad $ rvm install ruby-3.1.3 # Install bundler, rake and rails $ rvm use 3.1.3 $ gem install bundler rake rails
- Install Node.js
$ apt update $ apt install curl $ curl -fsSL https://deb.nodesource.com/setup_lts.x | bash - $ apt install nodejs
- Install RVM
$ apt install curl git patch build-essential bison zlib1g-dev libssl-dev libxml2-dev libxml2-dev autotools-dev\ libxslt1-dev libyaml-0-2 autoconf automake libreadline-dev libyaml-dev libtool libgmp-dev libgdbm-dev libncurses5-dev\ pkg-config libffi-dev libimlib2-dev gawk libsqlite3-dev sqlite3 $ gpg --keyserver keyserver.ubuntu.com --recv-keys\ 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB $ curl -L https://get.rvm.io | bash -s stable
- Set relevant Environment variables
# Set rails environment specific things $ echo "export RAILS_ENV=production" >> /opt/zammad/.bashrc $ echo "export RAILS_SERVE_STATIC_FILES=true" >> /opt/zammad/.bashrc $ echo "rvm --default use 3.1.3" >> /opt/zammad/.bashrc # Debian, CentOS & OpenSuSE $ echo "source /usr/local/rvm/scripts/rvm" >> /opt/zammad/.bashrc # Ubuntu $ echo "source /usr/share/rvm/scripts/rvm" >> /opt/zammad/.bashrc
- Install Ruby Environment
# Add zammad user to RVM group $ usermod -a -G rvm zammad # Install Ruby 3.1.3 $ su - zammad $ rvm install ruby-3.1.3 # Install bundler, rake and rails $ rvm use 3.1.3 $ gem install bundler rake rails
- Install Node.js
$ curl -fsSL https://rpm.nodesource.com/setup_lts.x | bash -
- Install RVM
$ yum install epel-release $ yum install patch autoconf automake bison bzip2 gcc-c++ libffi-devel libtool make patch readline-devel ruby sqlite-devel\ zlib-devel glibc-headers glibc-devel openssl-devel git imlib2 imlib2-devel $ gpg --keyserver keyserver.ubuntu.com --recv-keys\ 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB $ curl -L https://get.rvm.io | bash -s stable
- Set relevant Environment variables
# Set rails environment specific things $ echo "export RAILS_ENV=production" >> /opt/zammad/.bashrc $ echo "export RAILS_SERVE_STATIC_FILES=true" >> /opt/zammad/.bashrc $ echo "rvm --default use 3.1.3" >> /opt/zammad/.bashrc # Debian, CentOS & OpenSuSE $ echo "source /usr/local/rvm/scripts/rvm" >> /opt/zammad/.bashrc # Ubuntu $ echo "source /usr/share/rvm/scripts/rvm" >> /opt/zammad/.bashrc
- Install Ruby Environment
# Add zammad user to RVM group $ usermod -a -G rvm zammad # Install Ruby 3.1.3 $ su - zammad $ rvm install ruby-3.1.3 # Install bundler, rake and rails $ rvm use 3.1.3 $ gem install bundler rake rails
- Install Node.js
$ zypper install nodejs16
- Install RVM
$ zypper install patch autoconf automake bison bzip2 gcc-c++ libffi-devel libtool make patch readline-devel sqlite3-devel\ sqlite3 zlib-devel glibc-devel openssl-devel git imlib2 imlib2-devel gdbm-devel libyaml-devel $ gpg --keyserver keyserver.ubuntu.com --recv-keys\ 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB $ curl -L https://get.rvm.io | bash -s stable
- Set relevant Environment variables
# Set rails environment specific things $ echo "export RAILS_ENV=production" >> /opt/zammad/.bashrc $ echo "export RAILS_SERVE_STATIC_FILES=true" >> /opt/zammad/.bashrc $ echo "rvm --default use 3.1.3" >> /opt/zammad/.bashrc # Debian, CentOS & OpenSuSE $ echo "source /usr/local/rvm/scripts/rvm" >> /opt/zammad/.bashrc # Ubuntu $ echo "source /usr/share/rvm/scripts/rvm" >> /opt/zammad/.bashrc
- Install Ruby Environment
# Add zammad user to RVM group $ usermod -a -G rvm zammad # Install Ruby 3.1.3 $ su - zammad $ rvm install ruby-3.1.3 # Install bundler, rake and rails $ rvm use 3.1.3 $ gem install bundler rake rails
Other systems than above mentioned are out of scope of this documentation. Please check the rvm documentation on how to install rvm on your system.
Please also ensure to install nodejs
.
After that install the specific required ruby version.
- Install PostgreSQL Dependencies
$ apt install libpq-dev
# CentOS 7 $ yum install postgresql14-libs postgresql14-devel # CentOS 8 $ yum install postgresql-libs postgresql-devel
$ zypper install postgresql-devel
- Install Gems for Zammad
$ su - zammad $ bundle config set without "test development mysql" $ bundle install # CentOS 7 users - above command might fail, run the following # command and repeat above bundle install. # Adjust pg_config path according to your environment $ gem install pg -v '1.2.3' -- --with-pg-config=/usr/pgsql-14/bin/pg_config
Step 3: Configure database settings¶
Tip
🤓 For easiest usage …
If you provide your Zammad user with database creation permission, you can
run db:create
in the following section. If you don’t want that, you’ll
have to create the database manually.
$ cp config/database/database.yml config/database.yml
$ vi config/database.yml
Here’s a sample configuration to give you an idea on how your configuration file could look like. Please also have a look at Configure Database server for deeper details.
production: adapter: postgresql database: zammad pool: 50 timeout: 5000 encoding: utf8 username: zammad password: changeme
Hint
You can remove the password
line if you enable socket based
authentication!
Hint
If you want to use an existing database server that’s not on the same
machine, you can also use host
and port
to set that up.
For security reasons, ensure that your database configuration is readable for the Zammad user only.
$ chmod 600 /opt/zammad/config/database.yml
$ chown zammad:zammad /opt/zammad/config/database.yml
Step 4: Initialize your database¶
Warning
Ensure to do this as zammad
user in your Zammad directory!
$ su - zammad
$ rake db:create # SKIP IF you already created zammads database (see tip of step 3)
$ rake db:migrate
$ rake db:seed
# Synchronize translations
$ rails r "Locale.sync"
$ rails r "Translation.sync"
Step 5: Pre compile all Zammad assets¶
$ rake assets:precompile
Step 6: Start Zammad or install as service¶
Note
Run the following commands as root
.
You can start all services by hand or use systemd to start / stop Zammad.
$ cd /opt/zammad/script/systemd
$ ./install-zammad-systemd-services.sh
Warning
This method is not suitable for production use - you should avoid it.
$ rails s -p 3000 # application web server
$ script/websocket-server.rb start # non blocking websocket server
$ script/background-worker.rb start # generate overviews on demand, just send changed data to browser
Danger
⚠️ Zammads background worker cannot run in daemon mode!
Manage services of Zammad¶
In general Zammad uses three services - these can be (re)started & stopped
with the parent zammad
.
$ # Zammad service to start all services at once
$ systemctl (status|start|stop|restart) zammad
$ # Zammads internal puma server (relevant for displaying the web app)
$ systemctl (status|start|stop|restart) zammad-web
$ # Zammads background worker - relevant for all delayed- and background jobs
$ systemctl (status|start|stop|restart) zammad-worker
$ # Zammads websocket server for session related information
$ systemctl (status|start|stop|restart) zammad-websocket
Firewall & SELinux¶
Some parts of these steps may not apply to you, feel free to skip them!
SELinux¶
$ # Allow nginx or apache to access public files of Zammad and communicate
$ chcon -Rv --type=httpd_sys_content_t /opt/zammad/public/
$ setsebool httpd_can_network_connect on -P
$ semanage fcontext -a -t httpd_sys_content_t /opt/zammad/public/
$ restorecon -Rv /opt/zammad/public/
$ chmod -R a+r /opt/zammad/public/
SELinux support on SUSE seems to be in early state, at least for SLES 12 (and Leap 42.x). This is why we won’t cover it in this documentation.
See the documentation for more input if you still wish to continue.
Firewall¶
Note
Below only covers the distributions default firewall. It may not cover your case.
$ # Open Port 80 and 443 on your Firewall
$ ufw allow 80
$ ufw allow 443
$ ufw reload
Warning
We’re covering nftables
in this part - iptables is discouraged
starting from Debian 10 (Buster).
Our example uses the input
chain, yours may be a different one!
Add the following lines to /etc/nftables.conf
or your specific rule
file. Ensure to add these lines to your input-chain.
# Open Port 80 and 443 for Zammad
tcp dport { http, https } accept
udp dport { http, https } accept
The result should look like the following. Keep in mind that your enviroment could require different / more rules.
#!/usr/local/sbin/nft -f
flush ruleset
table inet filter {
chain input {
type filter hook input priority 0; policy drop;
ct state established,related accept
tcp dport ssh log accept
tcp dport { http, https } accept
udp dport { http, https } accept
}
chain forward {
type filter hook forward priority 0; policy accept;
}
chain output {
type filter hook output priority 0; policy accept;
}
}
To load your new rules, simply run systemctl reload nftables
.
$ # Open Port 80 and 443 on your Firewall
$ firewall-cmd --zone=public --add-service=http --permanent
$ firewall-cmd --zone=public --add-service=https --permanent
$ firewall-cmd --reload
If your system does not yet know webserver rules, you can add a new one
for your firewall by creating the file
/etc/sysconfig/SuSEfirewall2.d/services/webserver
with this content:
## Name: Webserver
## Description: Open ports for HTTP and HTTPs
# space separated list of allowed TCP ports
TCP="http https"
# space separated list of allowed UDP ports
UDP="http https"
After that locate FW_CONFIGURATIONS_EXT
within
/etc/sysconfig/SuSEfirewall2
and add the option webserver
to the
list. The list is seperated by spaces.
You may require a different zone, above covers the external zone.
Now ensure to restart the firewall service.
systemctl restart SuSEfirewall2
If we didn’t cover your distribution or firewall in question, ensure to
open ports 80
and 443
(TCP & UDP) beside of the ports you need.
Next steps¶
With this Zammad technically is ready to go. However, you’ll need to follow the following further steps to access Zammads Web-UI and getting started with it.
You may also find Zammads Console commands useful
If you expect usage with 5 agents or more you may also want to consider the following pages.