🛠️ This documentation is still under construction, please report any issues. 🔗
Zammad Hub

Appearance

English

DeutschсрпскиItalianoPortuguês (Brasil)

Docker installation ​

Zammad can be deployed using Docker Compose. You can even use graphical Docker front ends like Portainer.

INFO

We do not provide support in terms of Docker (-Compose) or Portainer specific problems. If you choose to run Zammad via Docker, support is only provided for the Zammad application.

Prerequisites ​

  • Make sure your Docker Compose setup matches the requirements you can find in the README of Zammad's Docker Compose repository.

  • Make sure to have at least 4 GB of RAM to run the containers.

  • Adjust your host's settings to run Elasticsearch properly:

    sh
    sudo sysctl -w vm.max_map_count=262144

Deployment with Docker Compose ​

Step 1: Clone the GitHub repo ​

sh
git clone https://github.com/zammad/zammad-docker-compose.git

Make sure to run git pull frequently to fetch updates. Alternatively, you can download the files from the releases page.

Step 2: Adjust environment as needed ​

In case our default environment is not what you are looking for, you can customize the stack using predefined scenarios and adjust environment variables. Jump to the customization section below to find more information.

Step 3: Start the stack ​

sh
cd zammad-docker-compose
sh
docker compose up -d

Optional: Use an additional .yml file to use a pre-defined scenario. Read on in the Customizing the Zammad Stack section.

After the stack is ready, you can access Zammad via the configured Docker host and port, e.g. http://localhost:8080/.

Deployment with Portainer ​

The easiest way to get Zammad running is via a graphical Docker UI. We recommend Portainer. For installation instructions, check out Portainer's documentation.

Step 1: Add stack ​

In the Portainer GUI (e.g. https://yourdomain.tld:9443), choose your target environment, select Stacks and click on Add stack as you can see in the screenshot below.

Screenshot in the Stacks section and highlighted "Add stack".

Step 2: Build from repository ​

Switch to Repository build method and provide the information below:

  • Name: enter a desired name of the stack
  • Repository URL: https://github.com/zammad/zammad-docker-compose
  • Repository reference: refs/heads/master
  • Compose path: docker-compose.yml (default)

In case our default environment is not what you are looking for, you can customize the stack using predefined scenarios and adjust environment variables. Jump to the customization section below to find more information.

Stack creation with provided information in Repository screen

Step 3: Deploy the stack ​

Finally, click the Deploy the stack button. The first time, it may take some time until the Docker images are fetched.

After the stack is ready, you can access Zammad via the configured Docker host and port, e.g. http://localhost:8080/.

Exposing the stack via HTTPS ​

To publish a Zammad stack on the internet, it needs to be secured via the HTTPS protocol. To achieve that without modifying the Zammad stack, you can:

  • Use a reverse proxy like Nginx Proxy Manager (NPM). It has a GUI that provides an easy Let's Encrypt integration.
  • Use a Cloudflare tunnel, which provides SSL termination.

Both scenarios are covered in the separate Docker Compose Scenarios page.

Single sign-on with Kerberos uses the same reverse proxy, see Single sign-on with Kerberos.

Customizing the Zammad stack ​

The Zammad Docker Compose stack is ready to run with its default settings. You can adapt it to your environment by loading predefined scenario files, adjusting environment variables and adding files specific to your instance.

See the Docker Compose scenarios page for supported use cases and detailed instructions on loading scenario files. To change individual settings, use Docker specific environment variables.

If you deployed the stack with Docker Compose by cloning the repository, use its local/ directory for files that belong only to your instance. See the customize the stack locally section for details.

How to run commands in the stack ​

Execute commands in your Docker stack by calling rails or rake via one of the following methods by using bundle exec.

Directly execute a specific command:

sh
docker compose run --rm zammad-railsserver bundle exec rails r '...your rails command here...'

Run the interactive Rails console to manually enter Rails commands:

sh
docker compose run --rm zammad-railsserver bundle exec rails c

Via docker compose exec:

sh
docker compose exec zammad-railsserver bundle exec rails r '...your rails command here...'

TIP

If you need to retrieve information from the Rails server, you can, for example, place pp (pretty print) in front of your Rails command. This leads to an output in your terminal.