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:

Administrative note
Please note that we only use 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

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

Below commands do neither include the database server nor the web server.
We do cover important web server related stuff within Configure the webserver.

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
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
After installing bundler, rake and rails we’ll need to install all required gems.
The command depends on the database server you are using.
Install PostgreSQL Dependencies
$ apt install libpq-dev
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

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/

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

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.

If you expect usage with 5 agents or more you may also want to consider the following pages.