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

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.

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.

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

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

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.

Frequently asked questions

Does Znuny provide an official Docker image?

No. Znuny has no official Docker image or compose stack. Community projects maintain Docker setups; for production architecture, follow doc.znuny.org.

How do I run Znuny console commands in Docker?

Open a shell in the app container (e.g. docker compose exec znuny-app bash) and run bin/znuny.Console.pl from the Znuny install root, typically /opt/znuny.

Is Docker suitable for a Znuny test or staging system?

Yes. Docker Compose is a practical way to spin up demos, test systems, and staging before you roll changes to production.