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.
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
| Stack | Best for | Znuny versions | First login |
|---|---|---|---|
| znuny/znuny-docker (official) | Split httpd + daemon + MariaDB | 7.3.x (build arg ZNUNY_VERSION) | Auto-install; admin password from .env |
| Erik-Donath/znuny-docker | Web installer workflow | 7.1+ | http://<host>:8080/znuny/installer.pl |
| juanluisbaptiste/docker-otrs | Built-in backups, SMTP relay | 6.x LTS | Pre-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.
| Component | Minimum | Recommended (staging) |
|---|---|---|
| CPU | 2 cores | 4+ cores |
| RAM | 4 GB | 8 GB or more (official defaults reserve ~5 GB across services) |
| Disk | 20 GB free | 40 GB+ (SSD) |
| Docker | 20.10 | latest |
| Docker Compose | v2 | latest |
| Git | 2.17 | latest |
On Windows or macOS, install Docker Desktop.
docker --versiondocker compose versionsudo git clone https://github.com/znuny/znuny-docker.git /opt/znuny-dockercd /opt/znuny-dockerReview docker-compose.yml, dockerfiles/, and .env.example before starting.
.envcp .env.example .envSet 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:
| Variable | Default | Purpose |
|---|---|---|
external_port | 80 | Host HTTP port |
DB_HOST | znuny-db | Database hostname inside the stack |
ZNUNY_IMAGE_TAG | latest | Tag when pulling pre-built images |
CONTAINER_REGISTRY | znuny | Use ghcr.io/znuny/znuny-docker to pull instead of build |
DEFAULT_INTERFACE | agent | Default UI: agent or customer |
Build locally (downloads the Znuny tarball; default version in the Dockerfile is 7.3.1):
sudo docker compose up -d --buildOr pull official images:
CONTAINER_REGISTRY=ghcr.io/znuny/znuny-dockerZNUNY_IMAGE_TAG=stablesudo docker compose up -dPin a release at build time:
sudo docker compose build --build-arg ZNUNY_VERSION=7.3.1 znuny-basesudo docker compose up -d --buildZNUNY_VERSION also accepts nightly and lts-nightly.
Check health:
sudo docker compose pssudo docker compose logs -f znuny-httpd| Service | Container | Role |
|---|---|---|
znuny-httpd | znuny_httpd | Apache, first-boot install |
znuny-daemon | znuny_daemon | Background jobs |
znuny-db | znuny_db | MariaDB |
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.
# TLS with Let's Encryptsudo docker compose -f docker-compose.yml -f docker-compose.traefik.yml up -d --buildSet ZNUNY_DOMAIN and ACME_EMAIL in .env.
# Existing MariaDB/MySQLsudo docker compose -f docker-compose.yml -f docker-compose.external-db.yml up -d --buildSet 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.
sudo docker exec -u znuny znuny_daemon /opt/znuny/bin/znuny.Console.pl Listsudo docker exec -u znuny znuny_daemon /opt/znuny/bin/znuny.Console.pl Maint::Cache::Delete| Volume | Contents |
|---|---|
ZnunyApp | Application files |
ZnunyPersistent | Config.pm, version, restart triggers |
MariaDBVol | Database files |
Back up before upgrades — see Znuny Docker operations.
Open external_port (default 80) or terminate TLS with Traefik / another reverse proxy.
MariaDBVol, ZnunyApp, and ZnunyPersistent.docker compose build --build-arg ZNUNY_VERSION=<new> znuny-base then docker compose up -d --build.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
sudo docker compose logs -f znuny-httpdsudo docker compose logs -f znuny-daemonsudo docker compose logs -f znuny-dbsudo docker compose down # keeps volumessudo docker compose down --volumes # deletes dataUse these when the official stack does not fit.
sudo git clone https://github.com/Erik-Donath/znuny-docker.git /opt/znuny-docker-communitycd /opt/znuny-docker-community# replace default passwords in docker-compose.yamlsudo docker compose up --build -dOpen 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.
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:
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:
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:
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:
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:
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: