Fixes #696 - Overhaul webserver configuration documentation#870
Merged
Conversation
Restructure getting-started/configure-webserver.rst around one linear flow per webserver (Nginx, Apache 2) instead of five parallel tabs at the certificate step. What changed: - Certbot consolidated as the recommended happy path, pointing to the upstream instructions per supported distro (Ubuntu, Debian, openSUSE / SLES, CentOS / RHEL). - acme.sh retained as an alternative under Let's Encrypt, trimmed. - Self-signed certificate section removed. - 'I don't need that' tab removed. - Mozilla SSL config generator mention dropped (downstream tooling, widely known). - Apache 'enable the site' step demoted to a normal step with per distro sub-tabs. The previous '(Optional)' label was misleading on Debian / Ubuntu / openSUSE. - dhparam hint folded into the Nginx and Apache steps inline (no longer a separate include file). - Mozilla SSL config generator include dropped. - CSRF proxy hints moved to a Troubleshooting section at the bottom of the page, split into a Nginx variant and an Apache 2 variant behind tabs. Files: - getting-started/configure-webserver.rst: rewritten (427 -> 320 lines). - getting-started/include-csrf-hints.rst: removed. - getting-started/include-dhparam-webserver.rst: removed. - getting-started/include-ssl-config-generator-webserver.rst: removed. The Nginx acme dynamic module was investigated as a candidate for replacing Certbot. It is not available in any Zammad-supported distro's package repositories (Ubuntu, Debian, openSUSE / SLES, RHEL / CentOS), so a section promoting it would not be honest on these distros. The module could be covered in a future 'Advanced' note once a distro ships it; for now Certbot remains the recommended path. Refs zammad/zammad#696
Includes two user tweaks plus two follow-ups that close gaps the tweaks created. User-applied tweaks (preserved): - Docker Compose / Kubernetes note: added a colon after the bold label, split it onto its own line so the bold-headed one-liner reads more cleanly, and reflowed the link text to stay under the 80-char line limit. - Moved the 'If you just installed Zammad' sentence and the getting-started-wizard image out from under Troubleshooting and up under Adjust the Webserver Configuration, where the wizard actually appears. Follow-ups (closes gaps from the user tweaks): - Inserted a purpose-first intro paragraph before the existing intros: 'Configure your webserver to reverse-proxy the Zammad application server. The page covers obtaining an SSL certificate, adjusting the sample configuration for Nginx or Apache 2 and reloading the webserver to apply the changes.' The original intro only mentioned where to find the sample files; it did not tell the reader what this page walks them through. - Updated the in-page references from the Nginx and Apache tabs (`Troubleshooting`_) to a named :ref: target (``Troubleshooting section <configure_webserver_troubleshooting>``). The previous inline link relied on a `.. _Troubleshooting:` label that the user-applied tweak deleted; without these reference fixes the two references would render as broken internal cross-references.
Two user-applied tweaks (in the page-intro paragraphs): 1. The purpose-first sentence now reads 'Nginx and Apache 2' instead of 'Nginx or Apache 2' — 'and' is the correct conjunction since the page covers both webservers together. 2. The 'sample configuration files' sentence was rewritten for readability: 'current' dropped (redundant with 'you can find'), 'contrib/' wrapped as 'the contrib/ directory of your Zammad installation' (adds 'directory' for natural prose), and the package-installation clause tightened to a single sentence instead of two short ones. Two follow-up tweaks in the same commit (grammar / readability): 3. 'During a package installation of Zammad, it automatically tries to install a configuration file to your Nginx.' moved 'automatically' to before 'install' (replaces 'automatically tries', which is a near-contradiction in terms — if the action is automatic, the agent isn't really trying). 4. The Certbot 'Once installed, request a certificate' phrase changed 'with either nginx or apache' to 'with nginx or apache'. The parallel construction 'replace A with either X or Y and B with Z' over-paired the conjunction; the bare 'replace A with X or Y and B with Z' parses unambiguously when the reader reads across to the second 'with'.
acme.sh no longer uses Let's Encrypt by default (the project's default CA switched to ZeroSSL in v3.0.7); without an explicit `--set-default-ca --server letsencrypt` call, the certificate issued by `acme.sh --issue` will be a ZeroSSL cert. Browsers trust ZeroSSL but a reader copy-pasting the command from this page and pointing Zammad at a non-Let's-Encrypt cert will see unrelated behaviour depending on which trust stores their clients have. The trimmed 2b acme.sh tab (commit 761bad4) had dropped this warning; restoring it now. Note placed at the top of the acme.sh tab so the reader sees the CA-setup step before they reach `--issue` or `--install-cert`.
ArtifactsProduced during runtime |
YetAnotherGerrit
requested changes
Jul 16, 2026
This is a single consolidated commit that captures all the review-driven changes to the page, including: - Replace the 4-parallel-tab certificate step with one 'happy-path' flow (Certbot happy path + acme.sh trimmed alternative, plus commercial-CA short-cut and the dropped self-signed). - Fold the wizard sentence + image into a single transition between the happy-path and Troubleshooting. - Restore the acme.sh 'default CA is ZeroSSL' warning as a folded-into-intro note with a real code block, so the reader sees the --set-default-ca step before --issue. - Move CSRF troubleshooting hints from the page-intro note into a Troubleshooting sub-section using 3-space-indented definition blocks. - Cap :doc: link text to the noun 'environment variables page' (no doubled 'environment variables' phrase), with the NGINX_*/ZAMMAD_RAILSSERVER_* names mentioned as inline code in the prose. - Replace the redundant host- or server name note in the page-intro with per-webserver inline instructions that point at the actual sample-config placeholder (example.com for Nginx; localhost for the second ServerName in Apache). - Update the in-page Nginx/Apache tab references to use named :ref: targets (Troubleshooting section) instead of an inline label. - Adjust h3 underline convention (use ^, matching the repo-wide convention used 84 times vs ~ for h4 which appears 5 times). - Clarify the page-intro: name both sample config files per webserver (zammad.conf plain HTTP, zammad_ssl.conf HTTPS), state that the package install automatically copies the non-SSL one, and instruct the user to swap manually for production. - Nginx 'Adjust server name' block: locate both server_name directives (port-80 and port-443 blocks) and adjust example.com in each. - Apache 'Adjust server name' block: enumerate the two ServerName directives, with the first defaulting to example.com and the second to localhost. - Heading and link-text style: 80-char line limit, ASCII hyphens, no Oxford comma, capitalised :ref: link text, title-case Troubleshooting sub-section headings. Refs zammad/zammad#696
YetAnotherGerrit
approved these changes
Jul 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.