Installing Znuny with Docker Compose

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

Experimental official Docker

The official stack is under active development. Upgrades may need manual steps. For production architecture, still follow doc.znuny.org or a vendor-supported deployment unless you accept that risk.

Choose a Docker stack

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.

System requirements

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

Step 1: Install Docker, Docker Compose, and Git

• Ubuntu
• Debian

On Windows or macOS, install Docker Desktop.

docker --version
docker compose version

Step 2: Clone the official project

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

Review docker-compose.yml, dockerfiles/, and .env.example before starting.

Step 3: Create .env

cp .env.example .env

Set 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

Step 4: Start the stack

Build locally (downloads the Znuny tarball; default version in the Dockerfile is 7.3.1):

sudo docker compose up -d --build

Or pull official images:

CONTAINER_REGISTRY=ghcr.io/znuny/znuny-docker
ZNUNY_IMAGE_TAG=stable

sudo docker compose up -d

Pin a release at build time:

sudo docker compose build --build-arg ZNUNY_VERSION=7.3.1 znuny-base
sudo docker compose up -d --build

ZNUNY_VERSION also accepts nightly and lts-nightly.

Check health:

sudo docker compose ps
sudo 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).

Step 5: Open Znuny

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.

HTTPS (Traefik) and external database

# TLS with Let's Encrypt
sudo docker compose -f docker-compose.yml -f docker-compose.traefik.yml up -d --build

Set ZNUNY_DOMAIN and ACME_EMAIL in .env.

# Existing MariaDB/MySQL
sudo docker compose -f docker-compose.yml -f docker-compose.external-db.yml up -d --build

Set 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.

After installation

Console commands

sudo docker exec -u znuny znuny_daemon /opt/znuny/bin/znuny.Console.pl List
sudo docker exec -u znuny znuny_daemon /opt/znuny/bin/znuny.Console.pl Maint::Cache::Delete

Persisted data

Volume	Contents
ZnunyApp	Application files
ZnunyPersistent	Config.pm, version, restart triggers
MariaDBVol	Database files

Back up before upgrades — see Znuny Docker operations.

Firewall

Open external_port (default 80) or terminate TLS with Traefik / another reverse proxy.

Updating Znuny

1. Back up MariaDBVol, ZnunyApp, and ZnunyPersistent.
2. Read the official README — the upgrade process is still incomplete.
3. Local build: docker compose build --build-arg ZNUNY_VERSION=<new> znuny-base then docker compose up -d --build.
4. Pre-built: set 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.

Troubleshooting

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-httpd
sudo docker compose logs -f znuny-daemon
sudo docker compose logs -f znuny-db
sudo docker compose down              # keeps volumes
sudo docker compose down --volumes    # deletes data

Community stacks (alternatives)

Use these when the official stack does not fit.

Erik-Donath (web installer)

sudo git clone https://github.com/Erik-Donath/znuny-docker.git /opt/znuny-docker-community
cd /opt/znuny-docker-community
# replace default passwords in docker-compose.yaml
sudo docker compose up --build -d

Open http://<host>:8080/znuny/installer.pl. Database host is db, not localhost. Services are typically znuny-app and db.

juanluisbaptiste (6.x LTS)

See juanluisbaptiste/docker-otrs for SMTP relay and automated backups.

Next steps

• Znuny Docker operations — console commands, packages, backups
• Staging system — safe test environment
• Znuny REST API
• Official installation docs — bare-metal installs
• znuny-docker README — architecture, env vars, CI

Frequently asked questions

Does Znuny ship an official Docker Compose stack?

Yes. Since 2026 Znuny publishes github.com/znuny/znuny-docker with docker-compose.yml and images on ghcr.io. The project still calls the stack experimental.

Do I need the web installer on the official stack?

No. install.sh configures the database from .env on first start. Use ZNUNY_ADMIN_PASS to log in. Community stacks such as Erik-Donath still use installer.pl and database host db.