paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-10-24 08:33:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Extend Certbot troubleshooting documentation.

Browse Source 
This should help folks who have problems with Certbot renewal; we had
a couple reported this week which I think were both caused by firewall
issues.
This commit is contained in:
Tim Abbott
2021-11-01 11:31:40 -07:00
parent 634b6ea97b
commit 9bec6bb5eb
2 changed files with 32 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/production/install.md
View File

@@ -63,9 +63,11 @@ If the script gives an error, consult [Troubleshooting](#troubleshooting) below.
suitable for production use, but may be convenient for testing. suitable for production use, but may be convenient for testing.
- `--certbot`: With this option, the Zulip installer automatically - `--certbot`: With this option, the Zulip installer automatically
obtains an SSL certificate for the server [using Certbot][doc-certbot]. obtains an SSL certificate for the server [using
If you'd prefer to acquire an SSL certificate yourself in any other Certbot][doc-certbot], and configures a cron job to renew the
way, it's easy to [provide it to Zulip][doc-ssl-manual]. certificate automatically. If you'd prefer to acquire an SSL
certificate yourself in any other way, it's easy to [provide it to
Zulip][doc-ssl-manual].
You can see the more advanced installer options in our [deployment options][doc-deployment-options] You can see the more advanced installer options in our [deployment options][doc-deployment-options]
documentation. documentation.

32
docs/production/ssl-certificates.md
View File

@@ -107,11 +107,33 @@ the server controls the website at that hostname; and is then given a
certificate. (For details, refer to certificate. (For details, refer to
[Let's Encrypt](https://letsencrypt.org/how-it-works/).) [Let's Encrypt](https://letsencrypt.org/how-it-works/).)
Then it records a flag in `/etc/zulip/zulip.conf` saying Certbot is in ### Renewal
use and should be auto-renewed. A cron job checks that flag, then
checks if any certificates are due for renewal, and if they are (so Let's Encrypt certificates expire after 90 days. Short expiration
approximately once every 60 days), repeats the process of request, periods are good for security, but they also mean that it's important
prove, get a fresh certificate. to automatically renew them to avoid regular maintenance work.
Zulip configures automatic renewal for you. As a result, a Zulip
server configured with Certbot does not require any ongoing work to
maintain a current valid SSL certificate.
Specifically, the `setup-certbot` tool (and by extension, the
installer option) enables the Certbot `auto_renew` property in
`/etc/zulip/zulip.conf`. This, in turn, configures a cron job
(`/etc/cron.d/certbot`) that will renew any Certbot certificates that
are due for renewal. The renewal process repeats the Certbot
proof-of-control process, receives the new certificate from Certbot,
installs the new certificate, and then reloads `nginx`.
#### Troubleshooting
If your Certbot certificate expires, it is usually because of firewall
rules preventing the Certbot renewal process (which is essentially
identical to the initial certificate request process) from
working. You can debug interactively by running the command from the
cron job,
`/home/zulip/deployments/current/scripts/lib/certbot-maybe-renew`, as
`root`.
## Self-signed certificate ## Self-signed certificate