Skip to content

Installing Znuny with Docker Compose

Docker Compose is the fastest way to get a Znuny test system, demo, or staging environment running. Prefer the official znuny/znuny-docker project. Community stacks remain useful when you want a web installer, Znuny 6.x LTS extras, or PostgreSQL.

Related: Znuny Docker operations · Staging system · Official install docs

StackBest forZnuny versionsFirst login
znuny/znuny-docker (official)Split httpd + daemon + MariaDB7.3.x (build arg ZNUNY_VERSION)Auto-install; admin password from .env
Erik-Donath/znuny-dockerWeb installer workflow7.1+http://<host>:8080/znuny/installer.pl
juanluisbaptiste/docker-otrsBuilt-in backups, SMTP relay6.x LTSPre-configured or /otrs/installer.pl

This guide walks through znuny/znuny-docker. Compose reads docker-compose.yml or compose.yml — the official repo uses docker-compose.yml.

ComponentMinimumRecommended (staging)
CPU2 cores4+ cores
RAM4 GB8 GB or more (official defaults reserve ~5 GB across services)
Disk20 GB free40 GB+ (SSD)
Docker20.10latest
Docker Composev2latest
Git2.17latest

Step 1: Install Docker, Docker Compose, and Git

Section titled “Step 1: Install Docker, Docker Compose, and Git”

On Windows or macOS, install Docker Desktop.

Terminal window
docker --version
docker compose version
Terminal window
sudo git clone https://github.com/znuny/znuny-docker.git /opt/znuny-docker
cd /opt/znuny-docker

Review docker-compose.yml, dockerfiles/, and .env.example before starting.

Terminal window
cp .env.example .env

Set all three required passwords (the compose file refuses to start without them):

ROOT_PASS=<secure_mariadb_root>
DB_USER_PASS=<secure_znuny_db>
ZNUNY_ADMIN_PASS=<secure_admin>

Useful optional keys:

VariableDefaultPurpose
external_port80Host HTTP port
DB_HOSTznuny-dbDatabase hostname inside the stack
ZNUNY_IMAGE_TAGlatestTag when pulling pre-built images
CONTAINER_REGISTRYznunyUse ghcr.io/znuny/znuny-docker to pull instead of build
DEFAULT_INTERFACEagentDefault UI: agent or customer

Build locally (downloads the Znuny tarball; default version in the Dockerfile is 7.3.1):

Terminal window
sudo docker compose up -d --build

Or pull official images:

CONTAINER_REGISTRY=ghcr.io/znuny/znuny-docker
ZNUNY_IMAGE_TAG=stable
Terminal window
sudo docker compose up -d

Pin a release at build time:

Terminal window
sudo docker compose build --build-arg ZNUNY_VERSION=7.3.1 znuny-base
sudo docker compose up -d --build

ZNUNY_VERSION also accepts nightly and lts-nightly.

Check health:

Terminal window
sudo docker compose ps
sudo docker compose logs -f znuny-httpd
ServiceContainerRole
znuny-httpdznuny_httpdApache, first-boot install
znuny-daemonznuny_daemonBackground jobs
znuny-dbznuny_dbMariaDB

First boot can take several minutes (start_period on httpd is 300s).

http://<your-server-ip>/znuny/

If you changed external_port, use that port. Log in with the initial admin account and ZNUNY_ADMIN_PASS. There is no installer.pl step on the official stack.

Terminal window
# TLS with Let's Encrypt
sudo docker compose -f docker-compose.yml -f docker-compose.traefik.yml up -d --build

Set ZNUNY_DOMAIN and ACME_EMAIL in .env.

Terminal window
# Existing MariaDB/MySQL
sudo docker compose -f docker-compose.yml -f docker-compose.external-db.yml up -d --build

Set DB_HOST, DB_NAME, DB_USER, and DB_USER_PASS to the external server. ROOT_PASS remains required by the base file but is unused.

Terminal window
sudo docker exec -u znuny znuny_daemon /opt/znuny/bin/znuny.Console.pl List
sudo docker exec -u znuny znuny_daemon /opt/znuny/bin/znuny.Console.pl Maint::Cache::Delete
VolumeContents
ZnunyAppApplication files
ZnunyPersistentConfig.pm, version, restart triggers
MariaDBVolDatabase files

Back up before upgrades — see Znuny Docker operations.

Open external_port (default 80) or terminate TLS with Traefik / another reverse proxy.

  1. Back up MariaDBVol, ZnunyApp, and ZnunyPersistent.
  2. Read the official README — the upgrade process is still incomplete.
  3. Local build: docker compose build --build-arg ZNUNY_VERSION=<new> znuny-base then docker compose up -d --build.
  4. Pre-built: set ZNUNY_IMAGE_TAG, then docker compose pull && docker compose up -d.

The httpd entrypoint compares /persistent/version and runs upgrade.sh when the image version differs.

Containers exit because .env is incomplete

Compose requires ROOT_PASS, DB_USER_PASS, and ZNUNY_ADMIN_PASS.

Port 80 already in use

Set external_port=8080 (or another free port) in .env and recreate the stack.

Daemon not healthy

httpd must become healthy first (install/upgrade). Check docker compose logs znuny-httpd.

View logs / stop

Terminal window
sudo docker compose logs -f znuny-httpd
sudo docker compose logs -f znuny-daemon
sudo docker compose logs -f znuny-db
sudo docker compose down # keeps volumes
sudo docker compose down --volumes # deletes data

Use these when the official stack does not fit.

Terminal window
sudo git clone https://github.com/Erik-Donath/znuny-docker.git /opt/znuny-docker-community
cd /opt/znuny-docker-community
# replace default passwords in docker-compose.yaml
sudo docker compose up --build -d

Open http://<host>:8080/znuny/installer.pl. Database host is db, not localhost. Services are typically znuny-app and db.

See juanluisbaptiste/docker-otrs for SMTP relay and automated backups.

Get Znuny professionally installed

Avoid trial and error in production: Softoft handles turnkey Znuny deployment, Docker or bare-metal setup, security hardening, and baseline configuration.

Frequently asked questions

What are the key differences between the official Znuny Docker Compose stack and community alternatives?

The official znuny/znuny-docker stack, while experimental, is designed for Znuny 7.3.x and newer, featuring an auto-installation process that configures the database from .env variables on first start. It splits services into httpd, daemon, and MariaDB. This approach streamlines setup without requiring the traditional installer.pl web interface. In contrast, community stacks like Erik-Donath/znuny-docker often target a web installer workflow for Znuny 7.1+, providing flexibility for users who prefer a guided setup. Another alternative, juanluisbaptiste/docker-otrs, is tailored for Znuny 6.x LTS and may include additional features such as built-in backups or SMTP relay capabilities. The choice depends on the desired Znuny version, installation preference, and specific feature requirements.

Quellen / Sources:

How does the official Znuny Docker Compose stack handle initial database setup and admin login, and is the web installer required?

No, the traditional web installer (installer.pl) is not required for the official znuny/znuny-docker stack. This stack automates the initial setup process. Upon its first start, the install.sh script automatically configures the database using the credentials provided in your .env file. It's crucial to define three specific passwords in this file: ROOT_PASS for the MariaDB root user, DB_USER_PASS for the Znuny database user, and ZNUNY_ADMIN_PASS for the initial Znuny administrator account. Once the Docker Compose stack is fully up and running, you can access the Znuny interface via http://<your-server-ip>/znuny/ and log in with the default admin username (typically root@localhost) and the password you set for ZNUNY_ADMIN_PASS. This automated configuration simplifies deployment and eliminates manual steps.

Quellen / Sources:

Which `.env` variables are essential for the official Znuny Docker Compose setup, and what are some useful optional configurations?

For the official znuny/znuny-docker stack, three password variables are absolutely essential in your .env file; the compose file will explicitly refuse to start without them. These are ROOT_PASS for the MariaDB root user, DB_USER_PASS for the Znuny database user, and ZNUNY_ADMIN_PASS for the initial Znuny administrator account. Beyond these mandatory settings, several optional variables allow for significant customization. For example, external_port (default 80) dictates the host HTTP port for accessing Znuny, DB_HOST (default znuny-db) specifies the database hostname within the Docker network, and ZNUNY_IMAGE_TAG (default latest) controls which pre-built image tag to pull. To pull official images rather than building locally, you can set CONTAINER_REGISTRY=ghcr.io/znuny/znuny-docker. Additionally, DEFAULT_INTERFACE can be set to agent or customer to define the default user interface upon login.

Quellen / Sources:

How can I configure HTTPS with Traefik or use an external database with the official Znuny Docker Compose stack?

The official znuny/znuny-docker project provides dedicated Docker Compose override files to facilitate advanced configurations like HTTPS with Traefik or integration with an external database. To enable HTTPS with Traefik and automatically obtain Let's Encrypt certificates, you can use docker-compose.traefik.yml in conjunction with your main docker-compose.yml. For this, you must define ZNUNY_DOMAIN with your domain name and ACME_EMAIL for certificate registration within your .env file. If you wish to use an existing external MariaDB or MySQL database, you would utilize docker-compose.external-db.yml. In this scenario, you need to set DB_HOST, DB_NAME, DB_USER, and DB_USER_PASS in your .env to point to your external server. While ROOT_PASS remains a required variable in the base compose file, it becomes unused when an external database is specified.

Quellen / Sources:

What firewall considerations are necessary after deploying Znuny with Docker Compose?

After deploying Znuny using Docker Compose, it is essential to configure your host system's firewall to allow external network access to the Znuny web interface. By default, the official stack exposes Znuny on port 80 (HTTP) on the host machine, which is controlled by the external_port variable in your .env file. If you have modified external_port to a different value, you must ensure that this specific port is open in your firewall rules. If you have opted for an HTTPS configuration using Traefik or another reverse proxy, you will typically need to open port 443 (HTTPS) instead of or in addition to port 80. In such cases, ensure that Traefik or your chosen proxy is correctly configured to terminate TLS and forward traffic to the Znuny container. Always adhere to the principle of least privilege by opening only the necessary ports to maintain system security.

Quellen / Sources:

What are the recommended system requirements for running Znuny with Docker Compose, especially for a staging environment?

For a basic Znuny test system or demo, the minimum system requirements include 2 CPU cores, 4 GB of RAM, and 20 GB of free disk space. However, for a more robust staging environment that can handle realistic loads and provide better performance, it is highly recommended to allocate more resources. This typically means 4 or more CPU cores, 8 GB or more of RAM (as the official Docker Compose stack's default services reserve approximately 5 GB), and at least 40 GB of free disk space, ideally on an SSD for improved I/O operations. Furthermore, your host system should have Docker version 20.10 or later, Docker Compose v2 or later, and Git version 2.17 or later installed to ensure compatibility, access to the latest features, and security updates.

Quellen / Sources: