diff --git a/docs/images/providers/jetstream/add-deployment-script-dialog.png b/docs/images/providers/jetstream/add-deployment-script-dialog.png new file mode 100644 index 0000000..cf797c4 Binary files /dev/null and b/docs/images/providers/jetstream/add-deployment-script-dialog.png differ diff --git a/docs/images/providers/jetstream/create-script-dialog.png b/docs/images/providers/jetstream/create-script-dialog.png new file mode 100644 index 0000000..3439f71 Binary files /dev/null and b/docs/images/providers/jetstream/create-script-dialog.png differ diff --git a/docs/images/providers/jetstream/deployment-in-progress.png b/docs/images/providers/jetstream/deployment-in-progress.png new file mode 100644 index 0000000..2b826ad Binary files /dev/null and b/docs/images/providers/jetstream/deployment-in-progress.png differ diff --git a/docs/images/providers/jetstream/launch-instance-dialog.png b/docs/images/providers/jetstream/launch-instance-dialog.png new file mode 100644 index 0000000..45cd795 Binary files /dev/null and b/docs/images/providers/jetstream/launch-instance-dialog.png differ diff --git a/docs/images/providers/jetstream/launch-instance-first-button.png b/docs/images/providers/jetstream/launch-instance-first-button.png new file mode 100644 index 0000000..a469106 Binary files /dev/null and b/docs/images/providers/jetstream/launch-instance-first-button.png differ diff --git a/docs/images/providers/jetstream/launch-instance-second-button.png b/docs/images/providers/jetstream/launch-instance-second-button.png new file mode 100644 index 0000000..f05cbbd Binary files /dev/null and b/docs/images/providers/jetstream/launch-instance-second-button.png differ diff --git a/docs/images/providers/jetstream/launching-spinner.png b/docs/images/providers/jetstream/launching-spinner.png new file mode 100644 index 0000000..adcdefe Binary files /dev/null and b/docs/images/providers/jetstream/launching-spinner.png differ diff --git a/docs/images/providers/jetstream/select-image.png b/docs/images/providers/jetstream/select-image.png new file mode 100644 index 0000000..f7e223c Binary files /dev/null and b/docs/images/providers/jetstream/select-image.png differ diff --git a/docs/index.rst b/docs/index.rst index 946898d..e7da07c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,6 +29,7 @@ started! :titlesonly: tutorials/digitalocean + tutorials/jetstream Guides ====== diff --git a/docs/tutorials/jetstream.rst b/docs/tutorials/jetstream.rst new file mode 100644 index 0000000..9d99a2e --- /dev/null +++ b/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 `_. + +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 `_.. 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 + ```` 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 + +#. 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 `_ from `conda-forge `_. + + .. 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.