zhangyiss/the-littlest-jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/the-littlest-jupyterhub.git synced 2025-12-18 21:54:05 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #328 from yuvipanda/https-fixes

Browse Source 
Cleanup HTTPS documentation
This commit is contained in:
Yuvi Panda
2019-05-28 13:09:05 -07:00
committed by GitHub
parent dd6e4edd6d 9f776c2fcb
commit abb3e151a3
2 changed files with 46 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/howto/admin/https.rst
View File

@@ -5,31 +5,46 @@ Enable HTTPS
============ ============
Every JupyterHub deployment should 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 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:: To enable HTTPS via letsencrypt::
sudo tljh-config set https.enabled true sudo tljh-config set https.enabled true
sudo tljh-config set https.letsencrypt.email you@example.com sudo tljh-config set https.letsencrypt.email you@example.com
sudo tljh-config add-item https.letsencrypt.domains yourhub.yourdomain.edu 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:: Once you have loaded this, your config should look like::
sudo tljh-config show sudo tljh-config show
.. sourcecode:: yaml .. sourcecode:: yaml
https: https:
@@ -43,10 +58,15 @@ Finally, you can reload the proxy to load the new configuration::
sudo tljh-config reload proxy 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. At this point, the proxy should negotiate with Let's Encrypt to set up a
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. 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 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 sudo tljh-config reload proxy
and now access your Hub securely at https://yourhub.yourdomain.edu. 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.

16
docs/troubleshooting/logs.rst
View File

@@ -44,18 +44,20 @@ logs is a great first step.
This command displays logs from JupyterHub itself. See :ref:`journalctl_tips` This command displays logs from JupyterHub itself. See :ref:`journalctl_tips`
for tips on navigating the logs. for tips on navigating the logs.
Configurable HTTP Proxy Logs .. _troubleshooting/logs/traefik:
============================
Configurable HTTP Proxy redirects traffic to JupyterHub / user notebook servers Traefik Proxy Logs
as necessary & handles HTTPS. It usually is the least problematic of the components, ==================
but things do go wrong sometimes!
`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 .. 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. for tips on navigating the logs.
User Server Logs User Server Logs