Znuny Hosting & Maintenance
Worry-free Znuny operations: Softoft manages hosting, staging setups, regular patching, automated backups, and proactive monitoring.
Znuny Docker – official stack, compose & commands (2026)
Related: Docker Compose installation · Staging & test system · Znuny REST API · Add-ons & plugins · OpenTicketAI
Introduction
Section titled “Introduction”Znuny Docker runs the ticket system in isolated containers: the same runtime on every host, clear separation of services, and a 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
Section titled “Available Docker stacks”| Project | Status | Best for | Notes |
|---|---|---|---|
| znuny/znuny-docker | Official (experimental) | Znuny 7.3.x, split httpd + daemon + MariaDB | Auto-install via .env, Traefik and external-DB overrides, GHCR images |
| Erik-Donath/znuny-docker | Community | Znuny 7.x with web installer (/znuny/installer.pl) | Single app container + MariaDB |
| juanluisbaptiste/docker-otrs | Community | Znuny 6.x LTS, SMTP relay, scheduled backups | Legacy /otrs/ paths |
| nyanmark/znuny-docker | Community | Minimal Nginx + PostgreSQL example | Check activity before use |
| cygnusnetworks/znuny | Community image | Debian images from official tarballs | Not Znuny GmbH; useful as a packaged alternative |
Always check repository activity, open issues, and Znuny version support before choosing a stack beyond local testing.
Official stack architecture
Section titled “Official stack architecture”The official Compose file (docker-compose.yml in the repo — Compose v2 loads compose.yml or docker-compose.yml automatically) splits roles:
| Service | Container name | Role |
|---|---|---|
znuny-httpd | znuny_httpd | Apache + install/upgrade lifecycle |
znuny-daemon | znuny_daemon | Znuny daemon (scheduled tasks; no Linux cron) |
znuny-db | znuny_db | MariaDB (skip with docker-compose.external-db.yml) |
znuny-base | (build only) | Shared image: Debian, Perl modules, Znuny tarball |
Shared volumes: ZnunyApp (/opt/znuny), ZnunyPersistent (Config.pm, version file), MariaDBVol.
Required .env values (no defaults): ROOT_PASS, DB_USER_PASS, ZNUNY_ADMIN_PASS. Optional: ZNUNY_IMAGE_TAG, CONTAINER_REGISTRY=ghcr.io/znuny/znuny-docker, external_port (default 80), resource limits.
First start runs install.sh (schema, SecureMode, random SystemID, admin password). There is no web installer on the official stack.
Quick start with Docker Compose
Section titled “Quick start with Docker Compose”Official path (details in the install guide):
- Install Docker — see Ubuntu or Debian
- Clone znuny/znuny-docker
cp .env.example .envand set the three required passwords- Start:
docker compose up -d --build(or pull GHCR images and omit--build) - Open
http://<host>:<external_port>/znuny/and log in as the admin user withZNUNY_ADMIN_PASS - Database hostname inside the stack is
znuny-db, notlocalhost
docker compose up -d --builddocker compose psdocker compose logs -f znuny-httpdTest system, demo, and staging with Docker
Section titled “Test system, demo, and staging with Docker”| Goal | Recommendation |
|---|---|
| Local demo | Official 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
Section titled “Docker vs. classic installation”| Topic | Official Docker | Classic (doc.znuny.org) |
|---|---|---|
| Setup | Clone repo, .env, docker compose up | Apache, MariaDB/PostgreSQL, Perl modules on Linux |
| Configuration | .env, volumes, optional Traefik override | Host packages, Config.pm, SysConfig |
| Persistence | ZnunyApp, ZnunyPersistent, MariaDBVol | Filesystem paths on the server |
| Updates | New image tag + entrypoint upgrade.sh (still experimental) | Package/tar upgrade + console migration |
| Background jobs | Separate znuny-daemon container | Cron.sh, systemd |
| Official support | Experimental Docker repo + classic install docs | Documented by Znuny project |
Typical containers in compose stacks
Section titled “Typical containers in compose stacks”Names come from the compose project. Always check with docker compose ps.
Common roles:
- Web / app — HTTP (Apache + mod_perl)
- Database — MariaDB or PostgreSQL with a persistent volume
- Daemon / scheduler — mail, Generic Agent, escalations
- SMTP relay (optional) — juanluisbaptiste and similar
- Reverse proxy (optional) — official Traefik override, or Nginx/Caddy
The official stack keeps web and daemon in separate containers. Erik-Donath combines web, cron, and daemon in one znuny-app plus db.
What are Docker containers?
Section titled “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)
Section titled “Controlling the Docker service (Linux with systemd)”- 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
Section titled “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(add--volumesonly if you intend to delete data) - Rebuild after config change:
docker compose up --build -d
Znuny console commands in the container
Section titled “Znuny console commands in the container”Official stack
Section titled “Official stack”docker exec -u znuny znuny_daemon /opt/znuny/bin/znuny.Console.pl Listdocker exec -u znuny znuny_daemon /opt/znuny/bin/znuny.Console.pl Maint::Cache::Deletedocker exec -u znuny znuny_daemon /opt/znuny/bin/znuny.Console.pl Maint::Config::RebuildAfter add-on install/remove, restart processes via trigger files:
docker exec -u znuny znuny_daemon touch /persistent/restart-daemon /persistent/restart-httpdCommunity stacks
Section titled “Community stacks”docker compose exec znuny-app bashbin/znuny.Console.pl --helpService names differ (znuny-app, web, znuny). Use docker compose ps.
CLI overview
- 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
- Dev::Tools::Migrate::OTRSToZnuny — migration tooling (check docs for your version)
- Admin::Package::UpgradeAll — upgrade installed packages
Always backup database and volumes first. Test in staging. The official Docker upgrade path is still incomplete — read the znuny-docker README before bumping versions.
Volumes, backup, and restore
Section titled “Volumes, backup, and restore”Official stack
Section titled “Official stack”| Volume | Contents |
|---|---|
ZnunyApp | Shared application tree (/opt/znuny) |
ZnunyPersistent | Config.pm, installed version, restart triggers |
MariaDBVol | MariaDB data files |
source .envdocker exec znuny_db mysqldump -u "$DB_USER" -p"$DB_USER_PASS" "$DB_NAME" | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gzRestore:
source .envdocker exec -i znuny_db mysql -u "$DB_USER" -p"$DB_USER_PASS" "$DB_NAME" < backup.sqlCommunity stacks (Erik-Donath example)
Section titled “Community stacks (Erik-Donath example)”| Volume | Contents |
|---|---|
znuny-var | Attachments, cache, sessions, logs |
znuny-config | Kernel/Config |
znuny-custom | Custom code |
db-data | MariaDB data files |
docker compose exec db mysqldump -u root -p znuny > znuny-backup-$(date +%F).sqljuanluisbaptiste — daily backups under /var/otrs/backups via OTRS_BACKUP_* env vars. See the project README.
Volume archive (stop the stack first):
docker compose downsudo tar -czf znuny-volumes-$(date +%F).tar.gz /var/lib/docker/volumes/docker compose up -dPackages and add-ons in the container
Section titled “Packages and add-ons in the container”Official:
docker exec -u znuny znuny_daemon /opt/znuny/bin/znuny.Console.pl Admin::Package::Install /tmp/my-package.opmdocker exec -u znuny znuny_daemon /opt/znuny/bin/znuny.Console.pl Maint::Config::Rebuilddocker exec -u znuny znuny_daemon touch /persistent/restart-daemon /persistent/restart-httpdCopy the OPM file in first (docker cp) or mount a host directory.
Browse Znuny add-ons on OpenITSMHub — see Znuny add-ons.
Production considerations
Section titled “Production considerations”- Official Docker is experimental — do not treat it as a drop-in replacement for a documented bare-metal install yet.
- Set strong values for
ROOT_PASS,DB_USER_PASS, andZNUNY_ADMIN_PASSbefore first start. - TLS: official
docker-compose.traefik.yml(ZNUNY_DOMAIN,ACME_EMAIL) or your own reverse proxy. - Resources: official defaults are roughly 5 GB RAM across services (daemon 2G, httpd 1G, DB 2G). Plan more for busy staging.
- Mail: disable outbound mail on test systems (
SendmailModule→Kernel::System::Email::DoNotSendEmail). - Monitoring:
docker compose ps, container healthchecks, daemon and httpd logs. - Updates: follow the official README; do not skip backups.
Migrating from OTRS
Section titled “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.
Further reading
Section titled “Further reading”- Docker Compose installation — official stack walkthrough
- Official repo: github.com/znuny/znuny-docker
- Official docs: doc.znuny.org
- Znuny REST API — integrations from your container stack
- OpenITSMHub – Znuny plugins — extensions and packages
- Derive project and service names from your compose file and
docker compose ps
Frequently asked questions
Does Znuny offer an official Docker solution, and what are its characteristics?
The official Znuny Docker solution is provided through the znuny/znuny-docker GitHub repository, which has been maintained by Znuny since 2026. This project includes Dockerfiles and docker-compose.yml files, with images published on ghcr.io/znuny/znuny-docker. While it offers a convenient way to run Znuny in isolated containers, the setup is still marked as "experimental" in the README. This means users should exercise caution with upgrades, as they might require manual intervention. For production environments requiring bare-metal stability, Znuny generally recommends following the traditional installation guides available on doc.znuny.org. The Docker stack is particularly useful for demos, test systems, and staging environments due to its consistent runtime and simplified lifecycle management.
Quellen:
How do I execute Znuny console commands within the official Docker environment?
To execute Znuny console commands within the official Docker stack, you typically use the docker exec command from your host system. The znuny-daemon service is the appropriate container for these operations, as it handles background tasks and includes the znuny.Console.pl script. You need to specify the user as znuny to ensure correct permissions. For example, to rebuild the system configuration, you would run: docker exec -u znuny znuny_daemon /opt/znuny/bin/znuny.Console.pl Maint::Config::Rebuild. If you are using a community-maintained Docker stack, the command might differ, often using docker compose exec [service_name] ... on their respective application service. Always ensure you are targeting the correct service and user for your specific Docker setup.
Quellen:
What are the advantages of using Docker for Znuny test, demo, or staging systems?
Yes, Docker is highly suitable for Znuny test, demo, and staging systems due to its ability to provide isolated, consistent environments. Docker Compose simplifies the process of spinning up these systems quickly, ensuring that the runtime environment is identical across different hosts. This consistency helps in replicating issues and validating changes before they are deployed to production. For a full staging workflow, you might copy anonymized production data, disable mail functionality, and apply hardening measures. Additionally, Docker facilitates integration with other containerized services, such as OpenTicketAI, which can run as an additional on-premise container and interact with Znuny via its REST API. This makes Docker an excellent choice for developing and testing new features or integrations.
Quellen:
What is the architecture of the official Znuny Docker Compose stack?
The official Znuny Docker Compose stack is designed with a service-oriented architecture, splitting roles into distinct containers. The primary services include znuny-httpd (handling Apache and the install/upgrade lifecycle), znuny-daemon (dedicated to Znuny daemon tasks and scheduled jobs, replacing traditional Linux cron), and znuny-db (a MariaDB container, which can be skipped if an external database is used via docker-compose.external-db.yml). There's also a znuny-base image that serves as a shared foundation, containing Debian, Perl modules, and the Znuny tarball. Persistence is managed through shared volumes like ZnunyApp for /opt/znuny, ZnunyPersistent for Config.pm and version files, and MariaDBVol for the database. Essential .env variables like ROOT_PASS, DB_USER_PASS, and ZNUNY_ADMIN_PASS are required for initial setup, which automatically runs install.sh without a web installer.
Quellen:
How does the official Znuny Docker installation differ from a classic bare-metal setup?
The official Znuny Docker installation significantly differs from a classic bare-metal setup in several key areas. For setup, Docker involves cloning the znuny/znuny-docker repository, configuring a .env file, and running docker compose up, whereas classic installation requires manual setup of Apache, MariaDB/PostgreSQL, and Perl modules on a Linux host. Configuration in Docker primarily relies on .env variables and volume mappings, with optional Traefik overrides, while classic setups involve host packages, direct Config.pm edits, and SysConfig. Persistence in Docker is managed through named volumes (ZnunyApp, ZnunyPersistent, MariaDBVol), providing clear separation, unlike classic installations where data resides in filesystem paths on the server. Updates in Docker are handled by pulling new image tags and running an experimental upgrade.sh entrypoint, contrasting with classic package or tarball upgrades followed by console migrations. Finally, background jobs are managed by a dedicated znuny-daemon container in Docker, eliminating the need for Cron.sh or systemd configurations on the host.
Quellen:
What are the initial steps to quickly set up Znuny using the official Docker Compose stack?
To quickly get started with the official Znuny Docker Compose stack, first ensure Docker is installed on your system; for example, on Ubuntu, you would use apt to install docker.io and docker-compose-v2. Next, clone the official znuny/znuny-docker repository from GitHub. After cloning, copy the .env.example file to .env and set the three required passwords: ROOT_PASS, DB_USER_PASS, and ZNUNY_ADMIN_PASS. Once configured, start the stack by navigating to the repository directory and running docker compose up -d --build. The --build flag compiles images from Dockerfiles; you can omit it if you prefer to pull pre-built images from GHCR. You can monitor the services with docker compose ps and view logs with docker compose logs -f znuny-httpd. Finally, open your web browser to http://<host>:<external_port>/znuny/ (default port 80) and log in as the admin user using the ZNUNY_ADMIN_PASS you set. Remember that the database hostname within the Docker stack is znuny-db, not localhost.
Quellen: