Chetan Mittal
Chetan Mittal Dev - Blog

Chetan Mittal Dev - Blog

Best guide on how to install Zammad on Ubuntu 22.04 for local development

How can I install latest version of Zammad (currently 5.2.2 - released on 13th Sep 2022) on Ubuntu 22.04?

Chetan Mittal's photo
Chetan Mittal
·Sep 28, 2022·

6 min read

Best guide on how to install Zammad on Ubuntu 22.04 for local development

Table of contents

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

3. Install RVM and Ruby Lang


ruby-3.0.4 [ubuntu-22.04]


  • Follow the discussion at 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


  • 3a. $ gpg2 --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
  • 3b. $ curl -sSL https://get.rvm.io | bash -s stable
  • 3c. $ rvm install 3.1.2
  • 3d. $ rvm --default use 3.1.2

4. Install NVM, Node.js and Yarn

  • 4a. $ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
  • 4b. $ nvm install node
  • 4c. $ npm install -g yarn
  • 4d. $ npm install -g coffeelint@1
  • 4e. $ npm install -g stylelint

5. Install elasticsearch

  • 5a. $ sudo apt install apt-transport-https sudo wget curl gnupg
  • 5b. $ sudo -i
  • 5c. $ 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
  • 5d. $ curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | \ gpg --dearmor | tee /etc/apt/trusted.gpg.d/elasticsearch.gpg> /dev/null
  • 5e. $ apt update
  • 5f. $ apt install elasticsearch
  • 5g. $ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment note:- everytime elasticsearch is upgraded; need to re-install ingest-attachment plugin
  • 5h. $ /usr/share/elasticsearch/bin/elasticsearch-plugin remove ingest-attachment
  • 5i. $ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
  • 5j. $ exit
  • 5k. $ sudo systemctl enable elasticsearch
  • 5l. $ sudo systemctl start elasticsearch
  • 5m. $ 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 sleeplessbeastie.eu/2020/02/29/how-to-preve..

6. Setup zammad

a) Install required modules

  • 6a. $ 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:

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 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

  • $ BROWSER=chrome rails test

YES! RUN SPECS

  • $ rails --tasks | grep spec # see all rake tasks you can use for testing (rspec)

lets test database

  • $ bundle exec rspec spec/db

lets test models

  • $ bundle exec rspec spec/models

running functional and integration tests take toooooooo llllllllllllong so avoid them to run on your dev machine; it would be better to setup a FREE CircleCI for your dev env

Notes

  • There are 2 frontends
    • 1) Desktop - based on Coffeescript
    • 2) Mobile - based on VueJS/GraphQL
  • For running mobile frontend we need
    • PostgreSQL
    • add env_var ENABLE_EXPERIMENTAL_MOBILE_FRONTEND=true in ~/.bash_profile
      • $ echo 'ENABLE_EXPERIMENTAL_MOBILE_FRONTEND=true' > ~/.bash_profile
      • and run
      • $ source ~/.bash_profile
  • Mobile frontend (based on VueJS) is barely functional

References

 
Share this