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. 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 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 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
Top comments (1)
this croud link for my ukraine blog about install zammad on ubuntu 22.04