Znuny Docker – Setup, docker-compose & commands (2026)

Znuny ticket system with Docker

Related: Docker Compose installation · Staging & test system · Znuny REST API · Add-ons & plugins · OpenTicketAI

Introduction

Znuny Docker runs the ticket system in isolated containers: the same runtime on every host, clear separation of services, and simple stack lifecycle. Docker is especially useful for demos, test systems, and staging before rolling changes to production.

:::caution Community stacks, not official Znuny does not publish an official Docker image or compose stack (see feature request #38). Community projects maintain Docker setups. For production architecture and bare-metal installs, follow doc.znuny.org. :::

New to Docker install? Start with the step-by-step guide: Installing Znuny with Docker Compose.

Available Docker stacks

Project	Znuny versions	Highlights	Installer path
Erik-Donath/znuny-docker	7.1+	Apache, cron, daemon, MariaDB, healthchecks	`/znuny/installer.pl`
juanluisbaptiste/docker-otrs	6.x LTS	Mature stack, automated backups, SMTP relay, upgrade helpers	`/otrs/` (legacy path)
nyanmark/znuny-docker	varies	Minimal Nginx + PostgreSQL example	`/otrs/installer.pl`

Always check repository activity, open issues, and Znuny version support before choosing a stack for anything beyond local testing.

Quick start with Docker Compose

Typical workflow (details depend on your compose file):

Install Docker — see Ubuntu or Debian
Clone a compose project (e.g. Erik-Donath/znuny-docker)
Replace default passwords in docker-compose.yaml
Start: docker compose up --build -d
Open the web installer (Znuny 7.x: http://<host>:8080/znuny/installer.pl)
Use database hostname db (Compose service name), not localhost
After version updates: Maint::Database::Upgrade in the app container

docker compose up -d
docker compose ps
docker compose logs -f znuny-app

Full walkthrough: Docker Compose installation.

Test system, demo, and staging with Docker

A Znuny test system or demo environment is quick to spin up with Docker:

Goal	Recommendation
Local demo	Small compose stack on a dev PC or VM
Test / staging	Separate compose instance with anonymized production data
CI / E2E	Ephemeral stack in a pipeline, then `docker compose down`

Full staging workflow (data copy, disable mail, hardening): Znuny staging system.

:::tip AI automation in Docker OpenTicketAI runs as an additional on-premise container and uses the Znuny REST API — a practical add-on for test systems with AI routing. :::

Docker vs. classic installation

Practical differences:

Topic	Docker	Classic (doc.znuny.org)
Setup	Compose file + images	Apache, MariaDB/PostgreSQL, Perl modules on Linux
Configuration	`docker-compose.yaml`, env vars, volumes	Host packages, `Config.pm`, SysConfig
Persistence	Named volumes or bind mounts required	Filesystem paths on the server
Updates	Rebuild image + `Maint::Database::Upgrade`	Package/tar upgrade + console migration
Background jobs	Cron/daemon in app container or separate service	`Cron.sh`, systemd
Official support	Community stacks only	Documented by Znuny project

Typical containers in compose stacks

Many Znuny Docker setups split work across services. Names like znuny_web_1 are examples — Compose names containers from project and service names. Always check with docker ps.

Common roles:

Web / app — HTTP access (Apache + mod_perl or PSGI)
Database — MariaDB or PostgreSQL with a persistent volume
Daemon / scheduler — background jobs (mail, Generic Agent, escalations)
SMTP relay (optional) — outbound mail in stacks like juanluisbaptiste
Reverse proxy (optional) — Nginx or Traefik for HTTPS

The Erik-Donath stack combines web, cron, and daemon in a single znuny-app container plus a separate db container.

What are Docker containers?

Containers isolate processes and filesystem views while sharing the host kernel — lighter than full VMs. Persistent data lives in volumes or mounted directories; the container filesystem itself is ephemeral.

Controlling the Docker service (Linux with systemd)

On Linux with systemd, Docker is usually a system service:

Start: sudo systemctl start docker
Enable on boot: sudo systemctl enable docker
Stop: sudo systemctl stop docker
Status: sudo systemctl status docker

On Docker Desktop (Windows/macOS), the app manages the daemon — no systemctl commands.

Listing and controlling containers

Running containers: docker ps
All containers: docker ps -a
Images: docker images
Logs: docker logs <container-name> (follow: docker logs -f <container-name>)
Start/stop: docker start <name> / docker stop <name>

With Docker Compose (v2):

Start stack: docker compose up -d
Stop: docker compose down (without removing volumes unless --volumes)
Rebuild after config change: docker compose up --build -d

Znuny console commands in the container

Shell in the right container

docker ps
docker compose exec znuny-app bash

Service names differ per stack — znuny-app, web, znuny are common. Use docker compose ps to see yours.

Running `znuny.Console.pl`

Run from the Znuny install root inside the container — typically /opt/znuny on Znuny 7.x stacks.

bin/znuny.Console.pl --help
bin/znuny.Console.pl Maint::Database::Upgrade
bin/znuny.Console.pl Maint::Cache::Delete
bin/znuny.Console.pl Maint::Config::Rebuild

::: details CLI overview

znuny.Console.pl handles admin tasks without the web UI:

Maint::Cache::Delete — clear cache
Maint::Config::Rebuild — rebuild SysConfig
Admin::Package::Install — install OPM package
Admin::Package::UpgradeAll — upgrade packages from repos
Maint::Test::System — system self-test

:::

::: details Migration and updates

For OTRS migration or version upgrades, follow vendor docs and backups:

Dev::Tools::Migrate::OTRSToZnuny — migration tooling (check docs for your version)
Admin::Package::UpgradeAll — upgrade installed packages

Always backup database and volumes before major steps. Test in staging first.

:::

Volumes, backup, and restore

Named volumes (Erik-Donath stack)

Volume	Contents
`znuny-var`	Attachments, cache, sessions, logs
`znuny-config`	`Kernel/Config`
`znuny-custom`	Custom code
`db-data`	MariaDB data files

Backup approaches

Database dump (works on any stack):

docker compose exec db mysqldump -u root -p znuny > znuny-backup-$(date +%F).sql

Volume archive (stop stack first for consistency):

docker compose down
sudo tar -czf znuny-volumes-$(date +%F).tar.gz /var/lib/docker/volumes/
docker compose up -d

juanluisbaptiste stack — built-in daily backups to /var/otrs/backups; configure with OTRS_BACKUP_TIME, OTRS_BACKUP_TYPE, and related env vars. See the project README.

For backups, include database volumes and mounts with Znuny data (var, attachments, config) — not only a DB dump.

Packages and add-ons in the container

Install OPM packages inside the app container like on a classic server:

docker compose exec znuny-app bash
bin/znuny.Console.pl Admin::Package::Install /tmp/my-package.opm
bin/znuny.Console.pl Maint::Config::Rebuild
bin/znuny.Console.pl Maint::Cache::Delete

Copy OPM files into the container first (docker cp) or mount a host directory.

Browse Znuny add-ons on OpenITSMHub — see Znuny add-ons.

Production considerations

Change default passwords in compose files before first start.
TLS: use a reverse proxy or mount certificates (Erik-Donath: apache-certs volume).
Resources: plan 8 GB RAM for staging; more if you add Elasticsearch or heavy integrations.
Mail: disable outbound mail on test systems (SendmailModule → Kernel::System::Email::DoNotSendEmail in SysConfig).
Monitoring: watch docker compose ps, container healthchecks, and Znuny daemon/cron logs.
Updates: never skip Maint::Database::Upgrade after image bumps.

Migrating from OTRS

Plan backup, package migration, and database upgrade. Console helpers include Dev::Tools::Migrate::OTRSToZnuny and Admin::Package::UpgradeAll — follow official migration docs and test in staging first.

Stacks based on juanluisbaptiste can restore OTRS backup directories with OTRS_INSTALL=restore — see that project’s documentation.