From 10e60ab2263dcf07c19a9b9c5dd7b94c1f313d3f Mon Sep 17 00:00:00 2001 From: yuvipanda Date: Sat, 18 May 2019 14:19:42 -0700 Subject: [PATCH 1/3] Cleanup HTTPS documentation - Wrap some lines - Normalize reference anchors to conform to hierarchy - Mention that the certificates will be renewed - Strengthen suggestion to use Let's Encrypt Fixes #305 --- docs/howto/admin/https.rst | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/howto/admin/https.rst b/docs/howto/admin/https.rst index 63f102a..e525840 100644 --- a/docs/howto/admin/https.rst +++ b/docs/howto/admin/https.rst @@ -5,14 +5,17 @@ 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 `_, -or setting it up :ref:`manually ` with your own TLS key and certificate. -If you don't know how to do that, -then :ref:`Let's Encrypt ` 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 `_, or setting it up +:ref:`manually ` 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 ` +method. -.. _letsencrypt: +.. _howto/admin/https/letsencrypt: Automatic HTTPS with Let's Encrypt ================================== @@ -23,7 +26,8 @@ To enable HTTPS via letsencrypt:: 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:: @@ -43,10 +47,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. -.. _manual_https: +These certificates are valid for 3 months. The proxy will automatically +renew them for you before they expire. + +.. _howto/admin/https/manual: Manual HTTPS with existing key and certificate ============================================== From a569417dad883469c03ac95ec2d3c2081a4cbc8d Mon Sep 17 00:00:00 2001 From: yuvipanda Date: Sat, 18 May 2019 17:46:06 -0700 Subject: [PATCH 2/3] Document that you need a domain name before HTTPS Also note that Let's Encrypt doesn't work in private networks. Fixes #217 --- docs/howto/admin/https.rst | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/howto/admin/https.rst b/docs/howto/admin/https.rst index e525840..853a109 100644 --- a/docs/howto/admin/https.rst +++ b/docs/howto/admin/https.rst @@ -15,11 +15,23 @@ certificate. Unless you have a strong reason to use the manual method, you should use the :ref:`Let's Encrypt ` method. +.. 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 `. + To enable HTTPS via letsencrypt:: sudo tljh-config set https.enabled true @@ -33,7 +45,6 @@ Once you have loaded this, your config should look like:: sudo tljh-config show - .. sourcecode:: yaml https: From 9f776c2fcb84f1fe24f9907874e6f3b114faaa85 Mon Sep 17 00:00:00 2001 From: yuvipanda Date: Mon, 20 May 2019 09:44:31 -0700 Subject: [PATCH 3/3] Add bit more info on troubleshooting HTTPS We no longer use CHP, so add section on getting logs from traefik instead --- docs/howto/admin/https.rst | 6 ++++++ docs/troubleshooting/logs.rst | 16 +++++++++------- 2 files changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/howto/admin/https.rst b/docs/howto/admin/https.rst index 853a109..f126391 100644 --- a/docs/howto/admin/https.rst +++ b/docs/howto/admin/https.rst @@ -97,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 ` might help. diff --git a/docs/troubleshooting/logs.rst b/docs/troubleshooting/logs.rst index d81d812..017b68d 100644 --- a/docs/troubleshooting/logs.rst +++ b/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 `_ 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