How to install latest version of Zammad on Ubuntu 22.04?
Tags: zammad, javascript, rails, webdev
Published: 2022-09-28 16:54:29

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/```
- 2c. 
```$ sudo chown -R root:root /tmp/geckodriver*```
- 2d. 
```$ sudo mv /tmp/geckodriver* /usr/local/bin/```
- 2e. 
```$ 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](https://blog.chetanmittaldev.com/my-first-pull-request-to-zammad-bump-to-ruby-v-31). OR you can view my pull request [[4268](https://github.com/zammad/zammad/pull/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](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
https://sleeplessbeastie.eu/2020/02/29/how-to-prevent-systemd-service-start-operation-from-timing-out/

## 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](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

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

- https://github.com/zammad/zammad/blob/develop/doc/developer_manual/development_environment/how-to-set-up-a-development-environment.md
- https://computingforgeeks.com/install-zammad-helpdesk-system-on-ubuntu/
- https://docs.zammad.org/en/latest/install/package.html

Originally posted on: [https://blog.chetanmittaldev.com/best-guide-on-how-to-install-zammad-on-ubuntu-2204-for-local-development](https://blog.chetanmittaldev.com/best-guide-on-how-to-install-zammad-on-ubuntu-2204-for-local-development)