Add a JetStream tutorial

docs/index.rst

@@ -29,6 +29,7 @@ started!
    :titlesonly:
 
    tutorials/digitalocean
+   tutorials/jetstream
 
 Guides
 ======

docs/tutorials/jetstream.rst

@@ -0,0 +1,200 @@
+.. _tutorial_quickstart_jetstream:
+
+Tutorial: JupyterHub on JetStream
+=================================
+
+Goal
+----
+
+By the end of this tutorial, you should have a JupyterHub with some admin
+users and a user environment with packages you want installed running on
+`JetStream <https://jetstream-cloud.org/>`_.
+
+Pre-requisites
+--------------
+
+#. A JetStream account with an allocation.
+#. Some familiarity with the command line.
+
+Step 1: Installing The Littlest JupyterHub
+------------------------------------------
+
+Let's create the server on which we can run JupyterHub.
+
+#. Log in to `JetStream <https://jetstream-cloud.org/>`_.. You need an allocation
+   to launch instances.
+
+#. Select the **Launch New Instance** option to get going.
+
+   .. image:: ../images/providers/jetstream/launch-instance-first-button.png
+      :alt: Launch new instance button with description.
+
+   This takes you to a page with a list of base images you can choose for your
+   server.
+
+#. Under **Image Search**, search for **Ubuntu 18.04**, and select the
+   **Ubuntu 18.04 Devel and Docker** image.
+
+   .. image:: ../images/providers/jetstream/select-image.png
+      :alt: Select Ubuntu 18.04 x64 image from image list
+
+#. Once selected, you will see more information about this image. Click the
+   **Launch** button on the top right.
+
+   .. image:: ../images/providers/jetstream/launch-instance-second-button.png
+      :alt: Launch selected image with Launch button on top right
+
+#. A dialog titled **Launch an Instance / Basic Options** pops up, with various
+   options for configuring your instance.
+
+   .. image:: ../images/providers/jetstream/launch-instance-dialog.png
+      :alt: Launch an Instance / Basic Options dialog box
+
+   #. Give your server a descriptive **Instance Name**.
+   #. Select an appropriate **Instance Size**.
+   #. If you have multiple allocations, make sure you are 'charging' this server
+      to the correct allocation.
+
+#. Click the **Advanced Options** link in the bottom left of the popup. This
+   lets us configure what the server should do when it starts up. We will use
+   this to install The Littlest JupyterHub.
+
+   A dialog titled **Launch an Instance / Advanced Options** should pop up.
+
+   .. image:: ../images/providers/jetstream/add-deployment-script-dialog.png
+      :alt: Dialog box allowing you to add a new script.
+
+#. Click the **Create New Script** button. This will open up another dialog
+   box!
+
+   .. image:: ../images/providers/jetstream/create-script-dialog.png
+      :alt: Launch an Instance / Advanced Options dialog box
+
+#. Under **Input Type**, select **Raw Text**. This should make a text box titled
+   **Raw Text** visible on the right side of the dialog box.
+   Copy the text below, and paste it into the **Raw Text** textbox. Replace
+   ``<admin-user-name>`` with the name of the first **admin user** for this
+   JupyterHub. This admin user can log in after the JupyterHub is set up, and
+   can configure it to their needs. Remember the username!
+
+   .. code-block:: bash
+
+    #!/bin/bash
+    curl https://raw.githubusercontent.com/yuvipanda/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \
+     | sudo python3 - \
+       --admin <admin-user-name>
+
+#. Under **Execution Strategy Type**, select **Run script on first boot**.
+
+#. Under **Deployment Type**, select **Wait for script to complete**.
+
+#. Click the **Save and Add Script** button on the bottom right. This should hide
+   the dialog box.
+
+#. Click the **Continue to Launch** button on the bottom right. This should put you
+   back in the **Launch an Instance / Basic Options** dialog box again.
+
+#. Click the **Launch Instance** button on the bottom right. This should turn it
+   into a spinner, and your server is getting created!
+
+   .. image:: ../images/providers/jetstream/add-deployment-script-dialog.png
+      :alt: Dialog box allowing you to add a new script.
+
+#. You'll now be shown a dashboard with all your servers and their states. The
+   server you just launched will progress through various stages of set up,
+   and you can see the progress here.
+
+   .. image:: ../images/providers/jetstream/deployment-in-progress.png
+      :alt: Instances dashboard showing deployment in progress.
+
+#. It will take about ten minutes for your server to come up. The status will
+   say **Active** and the progress bar will be a solid green. At this point,
+   your JupyterHub is ready for use!
+
+#. Copy the **IP Address** of your server, and try accessing it from a web
+   browser. It should give you a JupyterHub login page.
+
+   .. image:: ../images/first-login.png
+      :alt: JupyterHub log-in page
+
+#. Login using the **admin user name** you used in step 8, and a password. Use a
+   strong password & note it down somewhere, since this will be the password for
+   the admin user account from now on.
+
+#. Congratulations, you have a running working JupyterHub!
+
+Step 2: Addding more users
+--------------------------
+
+Most administration & configuration of the JupyterHub can be done from the
+web UI directly. Let's add a few users who can log in!
+
+#. Open the **Control Panel** by clicking the control panel button on the top
+   right of your JupyterHub.
+
+   .. image:: ../images/control-panel-button.png
+      :alt: Control panel button in notebook, top right
+
+#. In the control panel, open the **Admin** link in the top left.
+
+   .. image:: ../images/admin/admin-access-button.png
+      :alt: Admin button in control panel, top left
+
+   This opens up the JupyterHub admin page, where you can add / delete users,
+   start / stop peoples' servers and see who is online.
+
+#. Click the **Add Users** button.
+
+   .. image:: ../images/admin/add-users-button.png
+      :alt: Add Users button in the admin page
+
+   A **Add Users** dialog box opens up.
+
+#. Type the names of users you want to add to this JupyterHub in the dialog box,
+   one per line.
+
+   .. image:: ../images/admin/add-users-dialog.png
+      :alt: Adding users with add users dialog
+
+   You can tick the **Admin** checkbox if you want to give admin rights to all
+   these users too.
+
+#. Click the **Add Users** button in the dialog box. Your users are now added
+   to the JupyterHub! When they log in for the first time, they can set their
+   password - and use it to log in again in the future.
+
+Congratulations, you now have a multi user JupyterHub that you can add arbitrary
+users to!
+
+Step 3: Install conda / pip packages for all users
+--------------------------------------------------
+
+The **User Environment** is a conda environment that is shared by all users
+in the JupyterHub. Libraries installed in this environment are immediately
+available to all users. Admin users can install packages in this environment
+with ``sudo -E``.
+
+#. Log in as an admin user and open a Terminal in your Jupyter Notebook.
+
+   .. image:: ../images/notebook/new-terminal-button.png
+      :alt: New Terminal button under New menu
+
+#. Install `gdal <https://anaconda.org/conda-forge/gdal>`_ from `conda-forge <https://conda-forge.org/>`_.
+
+   .. code-block:: bash
+
+      sudo -E conda install -c conda-forge gdal
+
+   The ``sudo -E`` is very important!
+
+#. Install ``there`` with ``pip``
+
+   .. code-block:: bash
+
+      sudo -E pip install there
+
+The packages ``gdal`` and ``there`` are now available to all users in JupyterHub.
+If a user already had a python notebook running, they have to restart their notebook's
+kernel to make the new libraries available.
+
+See :ref:`user_environment` for more information.