How to install latest version of Zammad on Ubuntu 22.04?

The following instructions guide is always a WIP (work in progress) and if it does not work in case on your dev machine then feel free to comment and we will figure out to make sure Zammad gets running on your dev machine successfully.

1. Install required packages

1a. $ sudo apt install postgresql ruby-foreman curl wget apt-transport-https gnupg2 libimlib2 libimlib2-dev openssl direnv shellcheck chromium-chromedriver

2. Install geckodriver

2a. Download GeckoDriver (amd-64) tar.gz for Ubuntu 22.04 from https://github.com/mozilla/geckodriver/releases
- Follow the tutorial at https://tutorialforlinux.com/2022/06/10/step-by-step-ubuntu-22-04-geckodriver-installation/2/ to install GeckoDriver successfully
2b.

$ tar xvzf ~/Downloads/geckodriver*.tar.gz -C /tmp/

$ sudo chown -R root:root /tmp/geckodriver*

$ sudo mv /tmp/geckodriver* /usr/local/bin/

$ geckodriver --version

3. Install RVM and Ruby Lang

ruby-3.0.4 [ubuntu-22.04]

Follow the discussion at https://github.com/rvm/rvm/issues/5209 and install old version of OpenSSL to get Ruby-lang version 3.0.4 and prior working on Ubuntu 22.04.

- It is better to install Ruby v3.1.2 on Ubuntu 22.04 because of the compatibility. Read my previous blog on my first pull request to Zammad. OR you can view my pull request [4268] on Github if you want to use Ruby v3.1.2 for Zammad.

$ sudo apt install libssl-dev=1.1.1l-1ubuntu1.4

- install rvm using apt [Follow the guide at github.com/rvm/rvm/issues/5209]

$ rvm install ruby-3.0.4

ruby-3.1.2

$ gpg2 --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB

$ curl -sSL https://get.rvm.io | bash -s stable

$ rvm install 3.1.2

$ rvm --default use 3.1.2

4. Install NVM, Node.js and Yarn

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

$ nvm install node

$ npm install -g yarn

$ npm install -g coffeelint@1

$ npm install -g stylelint

5. Install elasticsearch

$ sudo apt install apt-transport-https sudo wget curl gnupg

$ sudo -i

$ echo "deb [signed-by=/etc/apt/trusted.gpg.d/elasticsearch.gpg] https://artifacts.elastic.co/packages/7.x/apt stable main"| \ tee -a /etc/apt/sources.list.d/elastic-7.x.list > /dev/null

$ curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | \ gpg --dearmor | tee /etc/apt/trusted.gpg.d/elasticsearch.gpg> /dev/null

$ apt update

$ apt install elasticsearch

$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment note:- everytime elasticsearch is upgraded; need to re-install ingest-attachment plugin

$ /usr/share/elasticsearch/bin/elasticsearch-plugin remove ingest-attachment

$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment

$ exit

$ sudo systemctl enable elasticsearch

$ sudo systemctl start elasticsearch

$ sudo systemctl stop elasticsearch

# in case you want to start elasticsearch server later

If elasticsearch gives timeout error on ubuntu 22.04 then follow instructions in below url https://sleeplessbeastie.eu/2020/02/29/how-to-prevent-systemd-service-start-operation-from-timing-out/

6. Setup zammad

a) Install required modules

$ cd </path/to/zammad-develop>

b) Install gems

If you are using mysql

$ bundle config set --local without 'postgres'

copy database.yml and update it with your mysql settings

If you are using postgresql

$ bundle config set --local without 'mysql'

copy database.yml and update it with your pg settings

Then

$ bundle install

c) Create development and test databases

$ rails db:create

d) Verify postgresql if databases are created

$ sudo -u postgres psql

> \l

# see if zammad databases are listed. if yes cont ... else create databases

> \q

7. Run migrations and insert seed data

$ rails zammad:bootstrap:init

# on a fresh install

OR

$ rails zammad:bootstrap:reset

# on an existing install

a) Configure locales else it takes a lllllong time to insert seed data

$ Z_LOCALES=en-us:de-de rails db:seed

8. Verify setup

a) Install Foreman gem to run multiples services from single command

$ gem install foreman

$ foreman start -f Procfile.dev

# test if zammad runs

b) Insert example-user

$ cp contrib/auto_wizard_test.json auto_wizard.json

$ rails c

# run console

Loading development environment (Rails 6.1.6.1)
>> AutoWizard.setup
=> #<User:0x000056220b14db50...
=> :q # to exit above command
>> UserInfo.current_user_id = 1 # just copy/paste in console
=> 1
>> Setting.set('system_init_done', true)
=> true
>> exit

9. Install JS dependencies

$ yarn install

#install required node packages

10. Setup elasticsearch for zammad rails app

$ sudo systemctl start elasticsearch

#if you had stopped elasticsearch server earlier

$ rails r "Setting.set('es_url', 'http://localhost:9200')"

#make sure your elasticsearch is running on port 9200 else change 'port' here

$ rails zammad:searchindex:rebuild

11. Bootup the server to develop zammad

$ foreman start -f Procfile.dev

#use 'Procfile' if you are setting up a production server manually
OR 'Procfile.dev' for development server because it starts a vite server to develop/test VueJS based mobile frontend

or run manually #in three separate terminal windows -

$ rails server

$ script/scheduler.rb start

#runs in bg; use -t for fg
-

$ script/websocket-server.rb start

#runs in fg; use -d for bg

12. Verify server

Once you’ve started the Zammad server locally, access the app in your browser by visiting localhost:3000 and log in using following credentials:

User: admin@example.com
Pasword: test

Appendices

a) Proper database.yml.example - PostgreSQL

default: &default
  adapter: postgresql
  # encoding: unicode
  # pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  encoding: utf8
  pool: 50
  timeout: 5000
  username: chetanmittal # change it to your dev-machine username
  password: <%= ENV['APPNAME_DATABASE_PASSWORD'] %>

development:
  <<: *default
  database: zammad_development

test:
  <<: *default
  database: zammad_test

production:
  <<: *default
  database: zammad_production
  username: zammad
  password: <%= ENV["ZAMMAD_DATABASE_PASSWORD"] %>

b) Testing

$ RAILS_ENV=test bundle exec rake db:drop db:create zammad:ci:test:prepare

# just run this once to setup zammad_test database

hmm .. there is not much documentation on how to run tests and specs (i see both written in codebase) so ...

HMM! RUN TESTS

$ rails --tasks | grep test

# see all rake tasks you can use for testing

ok, lets start testing

-

$ rails test

# just run basic cmd to run unit tests alone at first

got error 'Your Firefox profile cannot be loaded. It may be missing or inaccessible.' # do i need to create some profile for forefox too??? hmm

run tests again .. 1 using chromium

$ BROWSER=chrome rails test

# make sure your server at http://localhost:3000 is running else it will give give 404 error

$ foreman start -f Procfile.dev

# hit browser to test

run tests again .. 2

$ BROWSER=chrome rails test

# a lot of tests failed because of development|test databases seed data mismatch

run server again in test env

-

$ RAILS_ENV=test foreman start -f Procfile.dev

# hit browser to test

run tests again .. 3