Merge pull request #328 from yuvipanda/https-fixes

Cleanup HTTPS documentation

docs/howto/admin/https.rst

@@ -5,31 +5,46 @@ Enable HTTPS
 ============
 
 Every JupyterHub deployment should enable HTTPS!
-HTTPS encrypts traffic so that usernames and passwords and other potentially sensitive bits of information are communicated securely.
-The Littlest JupyterHub supports automatically configuring HTTPS via `Let's Encrypt <https://letsencrypt.org>`_,
-or setting it up :ref:`manually <manual_https>` with your own TLS key and certificate.
-If you don't know how to do that,
-then :ref:`Let's Encrypt <letsencrypt>` is probably the right path for you.
 
+HTTPS encrypts traffic so that usernames, passwords and your data are
+communicated securely. sensitive bits of information are communicated
+securely. The Littlest JupyterHub supports automatically configuring HTTPS
+via `Let's Encrypt <https://letsencrypt.org>`_, or setting it up
+:ref:`manually <howto/admin/https/manual>` with your own TLS key and
+certificate. Unless you have a strong reason to use the manual method,
+you should use the :ref:`Let's Encrypt <howto/admin/https/letsencrypt>`
+method.
 
-.. _letsencrypt:
+.. note::
+
+   You *must* have a domain name set up to point to the IP address on
+   which TLJH is accessible before you can set up HTTPS.
+
+.. _howto/admin/https/letsencrypt:
 
 Automatic HTTPS with Let's Encrypt
 ==================================
 
+.. note::
+
+   If the machine you are running on is not reachable from the internet -
+   for example, if it is a machine internal to your organization that
+   is cut off from the internet - you can not use this method. Please
+   set up a DNS entry and HTTPS :ref:`manually <howto/admin/https/manual>`.
+
 To enable HTTPS via letsencrypt::
 
     sudo tljh-config set https.enabled true
     sudo tljh-config set https.letsencrypt.email you@example.com
     sudo tljh-config add-item https.letsencrypt.domains yourhub.yourdomain.edu
 
-where ``you@example.com`` is your email address and ``yourhub.yourdomain.edu`` is the domain where your hub will be running.
+where ``you@example.com`` is your email address and ``yourhub.yourdomain.edu``
+s the domain where your hub will be running.
 
 Once you have loaded this, your config should look like::
 
     sudo tljh-config show
 
-
 .. sourcecode:: yaml
 
     https:
@@ -43,10 +58,15 @@ Finally, you can reload the proxy to load the new configuration::
 
     sudo tljh-config reload proxy
 
-At this point, the proxy should negotiate with Let's Encrypt to set up a trusted HTTPS certificate for you.
-It may take a moment for the proxy to negotiate with Let's Encrypt to get your certificates, after which you can access your Hub securely at https://yourhub.yourdomain.edu.
+At this point, the proxy should negotiate with Let's Encrypt to set up a
+trusted HTTPS certificate for you. It may take a moment for the proxy to
+negotiate with Let's Encrypt to get your certificates, after which you can
+access your Hub securely at https://yourhub.yourdomain.edu.
+
+These certificates are valid for 3 months. The proxy will automatically
+renew them for you before they expire.
 
-.. _manual_https:
+.. _howto/admin/https/manual:
 
 Manual HTTPS with existing key and certificate
 ==============================================
@@ -77,3 +97,9 @@ Finally, you can reload the proxy to load the new configuration::
     sudo tljh-config reload proxy
 
 and now access your Hub securely at https://yourhub.yourdomain.edu.
+
+Troubleshooting
+===============
+
+If you're having trouble with HTTPS, looking at the :ref:`traefik
+proxy logs <troubleshooting/logs/traefik>` might help.

docs/troubleshooting/logs.rst

@@ -44,18 +44,20 @@ logs is a great first step.
 This command displays logs from JupyterHub itself. See :ref:`journalctl_tips`
 for tips on navigating the logs.
 
-Configurable HTTP Proxy Logs
-============================
+.. _troubleshooting/logs/traefik:
 
-Configurable HTTP Proxy redirects traffic to JupyterHub / user notebook servers
-as necessary & handles HTTPS. It usually is the least problematic of the components,
-but things do go wrong sometimes!
+Traefik Proxy Logs
+==================
+
+`traefik <https://traefik.io/>`_ redirects traffic to JupyterHub / user notebook servers
+as necessary & handles HTTPS. Look at this if all you can see in your browser
+is one line cryptic error messages, or if you are having trouble with HTTPS.
 
 .. code-block:: bash
 
-   sudo journalctl -u configurable-http-proxy
+   sudo journalctl -u traefik
 
-This command displays logs from Configurable HTTP Proxy. See :ref:`journalctl_tips`
+This command displays logs from Traefik. See :ref:`journalctl_tips`
 for tips on navigating the logs.
 
 User Server Logs