Document addon packages in custom Zammad Docker images

[mikebenner]

Addon code copied into a running Docker container is lost when that container is replaced and is unavailable to the other application services. Zammad 7.2 already supports building addon packages into a custom image, but the Docker installation and update guides do not explain that workflow.

This adds a guide for staging .zpm packages in a release source checkout, building the image with COMMIT_SHA, selecting the same image for all Zammad Compose services, and letting init register packages and run migrations. It distinguishes code in the image from package metadata in PostgreSQL and uploaded files in the storage volume, and covers addon updates, Zammad upgrades and staged removals. The installation and update pages link to it.

Validation: the complete English HTML documentation builds with Sphinx warnings treated as errors. Commands and behavior were cross-checked against the 7.2.0 Dockerfile, current container entrypoint/package tasks, and official Compose image configuration. Existing application CI covers staged package installation and removal. I have not locally built the example image or run a container recreation/upgrade cycle because this account cannot access the Docker daemon.

This documents existing functionality; it does not change container installation safeguards or promise compatibility for third-party addons.

[mikebenner]

Review evidence for base 8758f1639635a6b31d9d5a07b48b5340be3fa230, head 13770e4dfb4ae995b2d8fd2779d4aea086f02c65:

• Lead self-review: complete English Sphinx HTML build passes with warnings treated as errors; diff check passes. Build args, release support, image selection, init/migration order and staging behavior were cross-checked against application and Compose sources.
• Independent user-requested review: Codex GPT-6 Astra at medium reviewed the full original diff and public text, then one affected repair round. Final verdict: READY at this exact head.
• Both findings were confirmed and fixed: removal keeps services stopped until down migrations finish and a clean replacement image is selected; older staged versions are prohibited because registration skipping does not prevent their code from being unpacked. The clean removal build uses a fresh source checkout to avoid leftover unpacked files.
• Ready for maintainer review. Existing application CI covers install/removal; it does not directly test recreation or an image upgrade. No local Docker image build or runtime cycle was executed because this account lacks Docker daemon access. Third-party addon compatibility remains the package maintainer's responsibility.

[ralf401]

Hi @mikebenner

thanks a lot for your effort. However, our idea was to not document this because it is intended to be used just internally. Sure, you could also build your own images with add-ons, but this approach is much more complicated than forking the Zammad repo and building a custom image from there. Maybe you can shed some light about your use-case?

Thanks and happy hacking!

[mikebenner]

I have forked the repo, but my goal was to be able to simply use the application as close to the vanilla install as possible. So ideally I would like to not maintain my own fork. I have opened 3 PRs on the main repo. Related to O365 GCC-High support and Telnyx integration on par with the Twilio integration. I looked into prior issues and saw that similar changes had been declined because they might be difficult to test or maintain. This documentation PR was more to hedge my bets in case those PRs were declined, I wanted to make sure that going the add-on path was supported when running the app as a docker container. The GCC-High support being native is more important than Telnyx for my organization. I can move my services back to Twilio if there is a reason you are not interested in supporting Telnyx.

[ralf401]

We have do discuss it internally and will get back to you. Be aware that this may take a few weeks because of other prioritized topics.