Install from Source

Tip

Are you tired of complex setup, configuration, backup and update tasks? Let us handle this stuff for you! 🚀

The easiest and often most cost-effective way to operate Zammad is our cloud service. Give it a try with a free trial instance!

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:

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 the developer documentation here.

Prerequisites

Software Dependencies

Please ensure that you already provided mentioned Software requirements.

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

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.

Please also make sure to have pnpm installed, which is required for asset compilation. See pnpm.io for more information.

$ apt update
$ apt install postgresql postgresql-contrib
$ systemctl start postgresql
$ systemctl enable postgresql
Install Node.js
# see https://github.com/nodesource/distributions#debian-and-ubuntu-based-distributions
# for detailed installation instructions.

$ apt install -y ca-certificates curl gnupg
$ mkdir -p /etc/apt/keyrings
$ curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
$ NODE_MAJOR=20
  echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
$ apt update
$ apt install nodejs -y
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 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.2.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.2.3
$ su - zammad
$ rvm install ruby-3.2.3

# Install bundler, rake and rails
$ rvm use ruby-3.2.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

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
   encoding: utf8
   username: zammad
   password: changeme # You can remove this 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!

Tip

🤓 Avoid a restart …

You can set the base URL of your Zammad installation by setting the ZAMMAD_HTTP_TYPE and ZAMMAD_FQDN environment variables before initializing the database (see below).

# Example for a base URL of https://zammad.example.com
$ su - zammad
$ export ZAMMAD_HTTP_TYPE=https
$ export ZAMMAD_FQDN=zammad.example.com

$ 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

Note

The commands below only work on Ubuntu, Debian and CentOS. If you use a different distribution, please have a look at their documentation.

$ # Allow nginx or apache to access public files of Zammad and communicate
$ sudo chcon -Rv --type=httpd_sys_content_t /opt/zammad/public/
$ sudo setsebool httpd_can_network_connect on -P
$ sudo semanage fcontext -a -t httpd_sys_content_t /opt/zammad/public/
$ sudo restorecon -Rv /opt/zammad/public/
$ sudo chmod -R a+r /opt/zammad/public/

Firewall

Ensure to open ports 80 and 443 (TCP & UDP) beside of the ports you need. Below you can find a few examples for different distributions. If you are using a different distribution, please have a look at their documentation.

Please note that the examples below only cover the distribution’s default firewall. It may not cover your case.

$ # Open Port 80 and 443 on your Firewall
$ sudo ufw allow 80
$ sudo ufw allow 443
$ sudo 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.