From 5a76d036f10d61c03023e58eeaea944b9459c7e7 Mon Sep 17 00:00:00 2001
From: Min RK <benjaminrk@gmail.com>
Date: Mon, 30 Jul 2018 16:08:47 +0200
Subject: [PATCH] docs for setting up HTTPS

---
 docs/howto/https.rst | 79 ++++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst       |  4 +++
 2 files changed, 83 insertions(+)
 create mode 100644 docs/howto/https.rst

diff --git a/docs/howto/https.rst b/docs/howto/https.rst
new file mode 100644
index 0000000..5609a42
--- /dev/null
+++ b/docs/howto/https.rst
@@ -0,0 +1,79 @@
+.. _howto/https:
+
+============
+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.
+
+
+.. _letsencrypt:
+
+Automatic HTTPS with Let's Encrypt
+==================================
+
+To enable HTTPS via letsencrypt::
+
+    sudo -E tljh-config set https.enabled true
+    sudo -E tljh-config set https.letsencrypt.email you@example.com
+    sudo -E 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.
+
+Once you have loaded this, your config should look like::
+
+    sudo -E tljh-config show
+
+
+.. sourcecode:: yaml
+
+    https:
+      enabled: true
+      letsencrypt:
+        email: you@example.com
+        domains:
+        - yourhub.yourdomain.edu
+
+Finally, you can reload the proxy to load the new configuration::
+
+    sudo -E 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.
+
+.. _manual_https:
+
+Manual HTTPS with existing key and certificate
+==============================================
+
+You may already have an SSL key and certificate.
+If so, you can tell your deployment to use these files::
+
+    sudo -E tljh-config set https.enabled true
+    sudo -E tljh-config set https.tls.key /etc/mycerts/mydomain.key
+    sudo -E tljh-config set https.tls.cert /etc/mycerts/mydomain.cert
+
+
+Once you have loaded this, your config should look like::
+
+    sudo -E tljh-config show
+
+
+.. sourcecode:: yaml
+
+    https:
+      enabled: true
+      tls:
+        key: /etc/mycerts/mydomain.key
+        cert: /etc/mycerts/mydomain.cert
+
+Finally, you can reload the proxy to load the new configuration::
+
+    sudo -E tljh-config reload proxy
+
+and now access your Hub securely at https://yourhub.yourdomain.edu.
diff --git a/docs/index.rst b/docs/index.rst
index 0196d31..be72879 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -35,6 +35,9 @@ Ubuntu 18.04. We have a bunch of tutorials to get you started.
   You should use this if your cloud provider does not already have a direct tutorial,
   or if you have experience setting up servers.
 
+Once you are ready to run your server for real,
+it's a good idea to proceed directly to :doc:`howto/https`.
+
 Tutorials
 =========
 
@@ -53,6 +56,7 @@ How-To guides answer the question 'How do I...?' for a lot of topics.
 .. toctree::
    :titlesonly:
 
+   howto/https
    howto/user-environment
    howto/admin-users
    howto/notebook-interfaces