Manual Setup

Overview

This guide explains how to set up a native Zammad development environment on your machine.

Use this if you prefer not to use the Devcontainer Setup.

Tested environments (others may work):

Zammad requires the following core components to run:

Ruby: Use the version defined in the .ruby-version file (recommended via rbenv or RVM)
Node.js & PNPM: Use the version specified in package.json (recommended via NVM)
Database: PostgreSQL
Elasticsearch
Redis

The following tools are highly recommended to start hacking Zammad.

brew install forego imlib2 openssl direnv geckodriver chromedriver shellcheck

sudo apt install libimlib2 libimlib2-dev openssl direnv shellcheck

Unfortunately there is no forego package / binary available for Linux. We recommend to build it from source or alternatively use foreman.

To ensure a well-readable and maintainable code base, we're using linting tools like:

There is also a dependency on Docker for some linting tasks, make sure it's available on your system.

Zammad uses the Ruby gem localhost to automatically generate self-signed certificates for HTTPS.

When needed, this will create:

console

~/.local/state/localhost.rb/localhost.crt
~/.local/state/localhost.rb/localhost.key

To start the development server in HTTPS mode:

VITE_RUBY_HOST=0.0.0.0 VITE_RUBY_HTTPS=true RAILS_ENV=development forego start -r -f Procfile.dev-https
# or
pnpm dev:https

The application will be listening on https://localhost:3000.

Most browsers will warn about self-signed certificates. Add an exception via Advanced → Proceed (unsafe) or Accept the Risk and Continue.

In Firefox, you will also have to add an exemption for WebSocket addresses, since they use a different port. Visit:

and then try to reload the app.

If you need a trusted HTTPS setup, you can obtain a free signed certificate via Let’s Encrypt.

For more information see: