cygnusnetworks/znuny repository overview

⁠docker-znuny

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

⁠Images

⁠Tags

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:

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

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

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.