docs: Update documentation to recommend certbot.

docs/production/customize.md

@@ -21,16 +21,34 @@ su zulip -c /home/zulip/deployments/current/scripts/restart-server
 
 ## Specific settings
 
+### Domain and Email settings
+
+`EXTERNAL_HOST`: the user-accessible domain name for your Zulip
+installation (i.e., what users will type in their web browser). This
+should of course match the DNS name you configured to point to your
+server and for which you configured SSL certificates.  If you passed
+`--hostname` to the installer, this will be prefilled with that value.
+
+`ZULIP_ADMINISTRATOR`: the email address of the person or team
+maintaining this installation and who will get support and error
+emails.  If you passed `--email` to the installer, this will be
+prefilled with that value.
+
 ### Authentication Backends
 
-`AUTHENTICATION_BACKENDS` is a list of enabled authentication mechanisms. By
+`AUTHENTICATION_BACKENDS`: Zulip supports a wide range of popular
-default the email backend is enabled.
+options for authenticating users to your server, including Google
+Auth, GitHub Auth, LDAP, REMOTE_USER, and more.  Note, however, that
+the default (email) backend must be used when creating a new
+organization.
 
-If you want an additional or different authentication backend, you will need to
+If you want an additional or different authentication backend, you
-uncomment one or more and then do any additional configuration required for
+will need to uncomment one or more and then do any additional
-that backend as documented in the `settings.py` file. See
+configuration required for that backend as documented in the
-the [section on Authentication](../production/authentication-methods.html) for more detail on the available
+`settings.py` file. See the
-authentication backends and how to configure them.
+[section on Authentication](../production/authentication-methods.html) for more
+detail on the available authentication backends and how to configure
+them.
 
 ### Mobile and desktop apps
 

docs/production/install.md

@@ -14,21 +14,10 @@ you need:
   production installation.
 * At least 2GB RAM and 10 GB disk space (4GB and 2 CPUs recommended for 100+ users).
 * A DNS name, an SSL certificate, and credentials for sending email.
+  For most users, you can just use our handy `--certbot` option to
+  generate the SSL certificate.
 
-## Step 1: Install SSL Certificates
+## Step 1: Download the latest release
-
-Zulip runs over `https` only, and requires SSL certificates in order to
-work. It looks for the certificates in `/etc/ssl/private/zulip.key`
-and `/etc/ssl/certs/zulip.combined-chain.crt`.  Note that Zulip uses
-`nginx` as its webserver and thus [expects a chained certificate
-bundle](http://nginx.org/en/docs/http/configuring_https_servers.html).
-
-If you need an SSL certificate, see [our SSL certificate
-documentation](ssl-certificates.html).  If you already have an SSL
-certificate, just install (or symlink) it into place at the above
-paths, and move on to the next step.
-
-## Step 2: Download and install latest release
 
 Download and unpack [the latest built server
 tarball](https://www.zulip.org/dist/releases/zulip-server-latest.tar.gz)
@@ -43,14 +32,20 @@ tar -xf zulip-server-latest.tar.gz
 If you'd like to verify the download, we
 [publish the sha256sums of our release tarballs](https://www.zulip.org/dist/releases/SHA256SUMS.txt).
 
-Then, run the Zulip install script:
+## Step 2: Install Zulip
+
+Most users will want Zulip to automatically obtain an SSL certificate
+for their server using [Certbot](https://certbot.eff.org/).  In that
+case, you can run the installer as follows:
+
 ```
-sudo -s  # If not already root
+sudo -i  # If not already root
-./zulip-server-*/scripts/setup/install
+./zulip-server-*/scripts/setup/install --certbot \
+    --email=username@example.com --hostname=zulip.example.com
 ```
 
-This may take a while to run, since it will install a large number of
+This will take a while to run, since it will install a large number of
-dependencies.
+dependencies from the pypi and npm repositories.
 
 The Zulip install script is designed to be idempotent, so if it fails,
 you can just rerun it after correcting the issue that caused it to
@@ -58,6 +53,8 @@ fail.  Also note that it automatically logs a transcript to
 `/var/log/zulip/install.log`; please include a copy of that file in
 any bug reports.
 
+#### What the installer does
+
 The install script does several things:
 * Creates `zulip` user, which the various Zulip servers will run as,
 * Creates `/home/zulip/deployments/`, which the Zulip code for this
@@ -70,20 +67,18 @@ symbolic link to it.
 * Configures the various third-party services Zulip uses, including
 Postgres, RabbitMQ, Memcached and Redis.
 
-## Step 3: Configure Zulip
+#### Providing your own SSL certificate
 
-Configure the Zulip server instance by editing `/etc/zulip/settings.py` and
+If you'd like to use an SSL certificate that you obtained not using
-providing values for the mandatory settings, which are all found under the
+Certbot way (e.g. issued by your corporate certificate authority),
-heading `### MANDATORY SETTINGS`.  These settings include:
+[our ssl certificate documentation](ssl-certificates.html) covers what
+you need to do.
 
-- `EXTERNAL_HOST`: the user-accessible domain name for your
+## Step 3: Configure outgoing email
-  Zulip installation (i.e., what users will type in their web
-  browser). This should of course match the DNS name you configured to
-  point to your server and for which you configured SSL certificates.
 
-- `ZULIP_ADMINISTRATOR`: the email address of the person or team
+Configure the Zulip server instance by editing
-  maintaining this installation and who will get support and error
+`/etc/zulip/settings.py` to enable your server's ability to send
-  emails.
+outgoing emails:
 
 - `EMAIL_HOST`, `EMAIL_HOST_USER`: credentials for an outgoing email
   (aka "SMTP") server that Zulip can use to send emails.  See

docs/production/requirements.md

@@ -66,18 +66,22 @@ save yourself the work of upgrading in a few months.
 #### Domain name
 
 You should already have a domain name available for your Zulip
-production instance. In order to generate valid SSL certificates with Let's
+production instance. In order to generate valid SSL certificates with
-Encrypt, and to enable other services such as Google Authentication, you'll
+Certbot, and to enable other services such as Google Authentication,
-need to update the domain's A record to point to your production server.
+you'll need to update the domain's A record to point to your
+production server.
 
 ## Credentials needed
 
 #### SSL Certificate
 
 * An SSL certificate for the host you're putting this on (e.g.,
-  zulip.example.com).  If you don't have an SSL solution already, read
+  zulip.example.com).  Unless you have your own certificate authority,
-  about [getting an SSL certificate for free](ssl-certificates.html) using
+  you should be able to just use the `--certbot` option in the Zulip
-  Let's Encrypt.
+  installer to automatically generate one for free using
+  [Certbot](https://certbot.eff.org/).  Additional options are
+  documented in our
+  [SSL certificate documentation](ssl-certificates.html).
 
 #### Outgoing email
 

docs/production/ssl-certificates.md

@@ -1,10 +1,23 @@
-# SSL Certificates
+# Installing SSL Certificates
 
 To keep your communications secure, Zulip runs over HTTPS only.
-You'll need an SSL/TLS certificate.  Fortunately, as of 2017 new
+You'll need an SSL/TLS certificate.
-options can make getting and maintaining a genuine,
+
-trusted-by-browsers certificate no longer the chore (nor expense)
+Fortunately, as of 2017 new options can make getting and maintaining a
-that it used to be.
+genuine, trusted-by-browsers certificate no longer the chore (nor
+expense) that it used to be.
+
+## Manual install
+
+Zulip looks for SSL certificate files in `/etc/ssl/private/zulip.key`
+and `/etc/ssl/certs/zulip.combined-chain.crt`.  Because Zulip uses
+`nginx` as its web server, it [expects a chained certificate
+bundle](http://nginx.org/en/docs/http/configuring_https_servers.html).
+
+If you already have an SSL certificate, just install (or symlink) it
+into place at the above paths.
+
+If not, read on.
 
 ## Using Certbot / Let's Encrypt