Installing Znuny with Docker Compose

Docker Compose is the fastest way to get a Znuny test system, demo, or staging environment running. Unlike OTOBO, Znuny does not ship an official znuny-docker stack from the project maintainers — community-maintained compose projects fill that gap.

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

No official Docker stack

Znuny’s official documentation covers Apache + MariaDB/PostgreSQL on Linux. For production, follow that guide or use a vendor-supported deployment. The steps below use a community compose project — verify version, security, and maintenance status before relying on it in production.

Choose a Docker stack

Stack	Best for	Znuny versions	Installer URL
Erik-Donath/znuny-docker	Znuny 7.x, web installer workflow	7.1+ (configurable at build)	/znuny/installer.pl
juanluisbaptiste/docker-otrs	Mature all-in-one stack, backups built in	Znuny 6.x LTS	Pre-configured or /otrs/installer.pl

This guide walks through Erik-Donath/znuny-docker because it matches the current Znuny 7.x installer path. For Znuny 6.x LTS with automated backups and SMTP relay, see the juanluisbaptiste project and Znuny Docker operations.

System requirements

Component	Minimum	Recommended (staging / production)
CPU	2 cores	4+ cores
RAM	4 GB	8 GB or more
Disk	20 GB free	40 GB+ (SSD)
Docker	20.10	latest
Docker Compose	v2	latest
Git	2.17	latest

Step 1: Install Docker, Docker Compose, and Git

Install Docker on your server. Distribution-specific steps:

• Ubuntu
• Debian

On Windows or macOS, install Docker Desktop and run the commands below in a terminal.

Verify:

docker --version
docker compose version

Step 2: Clone the compose project

cd /opt
sudo git clone https://github.com/Erik-Donath/znuny-docker.git /opt/znuny-docker
cd /opt/znuny-docker

Review docker-compose.yaml and Dockerfile before starting — especially passwords, ports, and the ZNUNY_VERSION build argument.

Step 3: Configure database credentials

Edit docker-compose.yaml and replace all default passwords:

db:
  environment:
    MYSQL_ROOT_PASSWORD: <secure_root_password>
    MYSQL_PASSWORD: <secure_znuny_password>

The compose file maps Znuny on port 8080 by default (8080:80). Change the host port if 8080 is already in use.

Znuny version

To install a specific Znuny release, set ZNUNY_VERSION in the build.args section of docker-compose.yaml, then rebuild. Check the repository README for supported versions.

Step 4: Build and start the stack

sudo docker compose up --build -d

On first run, Docker downloads base images and builds the Znuny app image. This can take several minutes.

Check that both containers are healthy:

sudo docker compose ps
sudo docker compose logs -f znuny-app

Expected services:

Service	Role
znuny-app	Apache + Znuny application, cron, daemon
db	MariaDB with Znuny-tuned settings

Step 5: Complete the web installer

Open the installer in your browser:

http://<your-server-ip>:8080/znuny/installer.pl

Follow the installer and note:

• Choose MariaDB as the database type.
• Database host: db (the Compose service name — not localhost).
• Database user / password: use the values from your docker-compose.yaml (MYSQL_USER, MYSQL_PASSWORD).
• Root password: use MYSQL_ROOT_PASSWORD when the installer asks for the database administrator password.

When finished, log in to the agent interface. The default admin user is root@localhost; the installer shows the password at the end.

Step 6: Verify background jobs

Znuny needs cron and the daemon for mail fetch, escalations, and generic agents. The Erik-Donath image runs these inside znuny-app. Confirm they are active:

sudo docker compose exec znuny-app bash
bin/Cron.sh status
exit

If jobs are not running, check container logs and the official cron documentation.

After installation

Enter the app container

sudo docker compose exec znuny-app bash
bin/znuny.Console.pl --help

Persisted data (volumes)

The stack stores data in named volumes — not inside the container filesystem:

Volume	Contents
znuny-var	Attachments, cache, sessions, logs
znuny-config	Kernel/Config overrides
znuny-custom	Custom modules and extensions
db-data	MariaDB database files

Back up these volumes (or the database with mysqldump) before upgrades. See Znuny Docker operations.

Firewall

Open the mapped host port (default 8080) or place a reverse proxy (Nginx, Traefik, Caddy) in front of the stack for HTTPS.

Updating Znuny

1. Back up database volumes and znuny-var.
2. Set the new ZNUNY_VERSION in docker-compose.yaml.
3. Rebuild and restart:

sudo docker compose build znuny-app
sudo docker compose up -d

4. Run the database upgrade inside the container:

sudo docker compose exec znuny-app bin/znuny.Console.pl Maint::Database::Upgrade
sudo docker compose exec znuny-app bin/znuny.Console.pl Maint::Cache::Delete

Follow official update instructions for your target version.

Troubleshooting

Installer cannot reach the database

• Use hostname db, not 127.0.0.1 — inside the app container, localhost points to the app itself.
• Wait until docker compose ps shows the database as healthy.

Port 8080 already in use

Change the port mapping in docker-compose.yaml, e.g. "9080:80", then restart the stack.

Permission errors on volumes

Ensure Docker can write to named volumes. On Linux, avoid bind-mounting host directories owned by root unless permissions are adjusted.

View logs

sudo docker compose logs -f znuny-app
sudo docker compose logs -f db

Restart or stop

sudo docker compose restart
sudo docker compose down          # keeps volumes
sudo docker compose down --volumes  # deletes data — use with care

Next steps

• Znuny Docker operations — console commands, packages, backups, production tips
• Staging system — safe test environment before production changes
• Znuny REST API — integrations from your container stack
• Official installation docs — bare-metal and RPM/source installs

Frequently asked questions

Does Znuny ship an official Docker Compose stack?

No. Unlike some forks, Znuny has no official maintainer compose project. Community stacks such as Erik-Donath/znuny-docker fill that gap for test, demo, and staging setups.

Which database host should I use in the web installer?

Use the Compose service name db, not localhost. Inside the app container, localhost points to the Znuny app itself, so MariaDB is reached via the db hostname.