Support automatic Let's Encrypt

docs/source/https.md

@@ -0,0 +1,53 @@
+# Enabling HTTPS
+
+In order to protect the data and passwords transfered over the public network, you should not run JupyterHub without enabling **HTTPS**.
+
+JupyterHub Traefik-Proxy supports **automatically** configuring HTTPS via [Let’s Encrypt](https://letsencrypt.org/docs/), or setting it
+up **manually** with your own key and certificate.
+
+## How-To HTTPS for JupyterHub managed Traefik-Proxy
+1. Via **Let'Encrypt**:
+    * Enable automatic https:
+    ```python
+    c.Proxy.traefik_auto_https=True
+    ```
+    * Configure a HTTPS port. This is where all the traffic coming through the HTTP entrypoint will be redirected to:
+    ```python
+    c.Proxy.traefik_https_port=443
+    ```
+    * Set the email address used for Let's Encrypt registration:
+    ```python
+    c.Proxy.traefik_letsencrypt_email="[email protected]"
+    ```
+    * Set the domain list:
+    ```python
+    c.Proxy.traefik_letsencrypt_domains=["jupyter.test"]
+    ```
+    * Set the the CA server to be used:
+    ```python
+    c.Proxy.traefik_acme_server="https://acme-v02.api.letsencrypt.org/directory"
+    ```
+    <span style="color:green">**Note !**</span>
+
+    **TraefikProxy**, supports only the most common challenge type, i.e. the [HTTP-01 ACME challenge](https://letsencrypt.org/docs/challenge-types/#http-01-challenge).
+    If other challenge type is needed, one could setup the proxy to be externally managed to get access to all the Traefik's configuration options (including the
+    ACME challenge type).
+
+2. **Manually**, by providing your own key and certificate:
+
+    Providing a certificate and key can be done by configuring JupyterHub to enable SSL encryption as specified in [the docs](https://jupyterhub.readthedocs.io/en/stable/getting-started/security-basics.html?highlight=https#enabling-ssl-encryption). Example:
+    ```python
+      c.JupyterHub.ssl_key = '/path/to/my.key'
+      c.JupyterHub.ssl_cert = '/path/to/my.cert'
+    ```
+
+    Traefik will then redirect all HTTP traffic to the HTTPS entrypoint. The default HTTPS entrypoint port is 8843, but can be configured through:
+    ```python
+    c.Proxy.traefik_https_port=443
+    ```
+
+## How-To HTTPS for external Traefik-Proxy
+If the proxy isn't managed by JupyterHub, HTTPS can be enabled through Traefik's static configuration file.
+Checkout Traefik's documentation for:
+* [Setting up ACME (Let's Encrypt) Configuration](https://docs.traefik.io/v1.7/configuration/acme/)
+* [How to redirect HTTP traffic to HTTPS](https://docs.traefik.io/v1.7/user-guide/examples/#http-redirect-on-https)

docs/source/index.rst

@@ -39,11 +39,12 @@ Installation Guide
 Getting Started
 ---------------
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    toml
    etcd
    consul
+   https
 
 API Reference
 -------------

docs/source/toml.md

@@ -69,9 +69,9 @@ c.TraefikTomlProxy.toml_dynamic_config_file="/path/to/dynamic_config_filename.to
 ---
 <span style="color:green">**Note !**</span>
 
-**When JupyterHub starts the proxy**, it writes the static config once, then only edits the routes config file. 
+* **When JupyterHub starts the proxy**, it writes the static config once, then only edits the routes config file.
 
-**When JupyterHub does not start the proxy**, the user is totally responsible for the static config and 
+* **When JupyterHub does not start the proxy**, the user is totally responsible for the static config and
 JupyterHub is responsible exclusively for the routes.
 ---