docker-znuny

Debian-based Znuny LTS Docker images built from the official source tarball.

Not an official Znuny GmbH image. This is community packaging by CygnusNetworks. Znuny itself remains AGPL-3.0; see License.

Images

Registry	Image
GitHub Container Registry	ghcr.io/cygnusnetworks/docker-znuny
Docker Hub	docker.io/cygnusnetworks/znuny

Tags

Tag	Meaning
6.5.22 (example)	Exact Znuny LTS patch version (reproducible pin)
6.5	Latest built patch on the 6.5 LTS line
stable	Current LTS image (same as newest 6.5.x we publish)
latest	Alias of stable (Docker convention)

Naming note: Znuny’s product line also has a “Stable” track (7.x) separate from LTS 6.5. Our image tag stable means current LTS image, not Znuny 7.

New LTS 6.5.x releases are detected automatically (see Update policy).

What’s inside

• Base: debian:trixie-slim
• Znuny from download.znuny.org (SHA-256 verified at build)
• Apache 2 + mod_perl (prefork MPM)
• supervisord (Apache + cron)
• Znuny daemon + cron jobs started by the entrypoint
• Healthcheck against /otrs/index.pl

Quick start

docker pull ghcr.io/cygnusnetworks/docker-znuny:stable
# or: docker pull cygnusnetworks/znuny:stable

Minimal stack (MariaDB + Znuny):

cd examples
cp Config.pm.example Config.pm
# edit Config.pm if needed
docker compose up -d

Open http://localhost:8080/otrs/installer.pl for a fresh database, or point Config.pm at an existing Znuny/OTRS database.

Volume design

Unlike images that put the entire /opt/otrs/Kernel tree in a named volume (which makes image upgrades ineffective), application code stays in the image. Mount only local state:

Path	Required	Purpose
/opt/otrs/Kernel/Config.pm	yes	DB credentials and site config
/opt/otrs/Custom	no	Local code overrides
/opt/otrs/var/article	only with ArticleStorageFS	Article files on disk

Example:

docker run -d --name znuny \
  -p 8080:80 \
  -v "$PWD/Config.pm:/opt/otrs/Kernel/Config.pm:ro" \
  ghcr.io/cygnusnetworks/docker-znuny:6.5.22

Environment variables

Variable	Default	Description
ZNUNY_SKIP_REBUILD	unset	Set to 1 to skip package reinstall, config rebuild, and cache delete
ZNUNY_SKIP_DAEMON	unset	Set to 1 to skip cron install and Znuny daemon start

Passing a command bypasses boot entirely:

docker run --rm -it \
  -v "$PWD/Config.pm:/opt/otrs/Kernel/Config.pm:ro" \
  ghcr.io/cygnusnetworks/docker-znuny:stable \
  bash

Entrypoint behaviour

On normal start the entrypoint:

1. Runs otrs.SetPermissions.pl
2. Waits for the database (Maint::Database::Check, up to ~5 minutes)
3. Unless ZNUNY_SKIP_REBUILD=1:
   • Admin::Package::ReinstallAll (restores OPM package files after container recreate)
   • Maint::Config::Rebuild
   • Maint::Cache::Delete
4. Unless ZNUNY_SKIP_DAEMON=1: installs cron jobs and starts otrs.Daemon.pl
5. exec supervisord (Apache + cron)

OPM packages

Installed package files live in the container filesystem and are lost when the container is recreated. Package metadata remains in the database. The entrypoint runs Admin::Package::ReinstallAll on boot so files are restored from the package repository.

Reverse proxy / SSO

Apache is configured to map X-Forwarded-User to REMOTE_USER for Kernel::System::Auth::HTTPBasicAuth (and similar SSO frontends):

SetEnvIf X-Forwarded-User "(.*)" REMOTE_USER=$1

Terminate TLS and authentication at your reverse proxy, then forward the authenticated username in X-Forwarded-User.

Optional build-time patches

Place unified diffs under patches/<ZNUNY_VERSION>/ (e.g. patches/6.5.22/01-foo.patch). They are applied with patch -p1 during the image build. The published images ship without custom patches.

Build locally

docker build \
  --build-arg ZNUNY_VERSION=6.5.22 \
  -t znuny:6.5.22 \
  .

Requirements at build time: network access to download.znuny.org for the tarball and .sha256 checksum.

Update policy

Trigger	Behaviour
Push to main	Rebuilds the configured default LTS version
Daily schedule (watch-lts.yml)	Detects new rel-6_5_* / rel-7_3_* tags on znuny/Znuny; builds if the image tag is missing
workflow_dispatch	Manual build for a given version

Successful builds create a GitHub Release whose tag matches the exact Znuny version (e.g. 6.5.22). Rebuilds of an existing version leave the release as-is. The production series (6.5) is marked as the latest GitHub release; other series (e.g. 7.x) publish releases without taking the “latest” flag.

CI secrets (org or repo): DOCKER_USERNAME, DOCKER_TOKEN for Docker Hub. GHCR uses the built-in GITHUB_TOKEN.

Floating tags 6.5, stable, and latest are updated when a build is marked as the current LTS line head.

Security notes

• Upstream tarball integrity is checked via official .sha256 files
• No secrets are baked into the image; use a mounted Config.pm or secrets
• Znuny historically runs as user otrs with Apache; the image follows that model
• Prefer pinning to an exact version (6.5.x) in production

Related links

• Znuny project
• Znuny source
• Downloads
• Documentation

License

• This repository (Dockerfiles, scripts, docs): MIT
• Znuny software inside the image: AGPL-3.0
• Debian packages retain their respective licenses

Disclaimer

This project is not affiliated with or endorsed by Znuny GmbH. Use at your own risk. Always test upgrades in a non-production environment.