diff --git a/docs/images/admin-button.png b/docs/images/admin-button.png new file mode 100644 index 0000000..fc2d592 Binary files /dev/null and b/docs/images/admin-button.png differ diff --git a/docs/images/admin/add-users-button.png b/docs/images/admin/add-users-button.png new file mode 100644 index 0000000..2830847 Binary files /dev/null and b/docs/images/admin/add-users-button.png differ diff --git a/docs/images/admin/add-users-dialog.png b/docs/images/admin/add-users-dialog.png new file mode 100644 index 0000000..82bb7b4 Binary files /dev/null and b/docs/images/admin/add-users-dialog.png differ diff --git a/docs/images/control_panel_button.png b/docs/images/control-panel-button.png similarity index 100% rename from docs/images/control_panel_button.png rename to docs/images/control-panel-button.png diff --git a/docs/index.rst b/docs/index.rst index 091510a..946898d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -28,7 +28,7 @@ started! .. toctree:: :titlesonly: - tutorials/quickstart + tutorials/digitalocean Guides ====== diff --git a/docs/tutorials/digitalocean.rst b/docs/tutorials/digitalocean.rst new file mode 100644 index 0000000..33b6d84 --- /dev/null +++ b/docs/tutorials/digitalocean.rst @@ -0,0 +1,177 @@ +.. _tutorial_quickstart_digitalocean: + +Tutorial: JupyterHub on Digital Ocean +======================================== + +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 +`DigitalOcean `_. + +Pre-requisites +-------------- + +#. A DigitalOcean account with a payment method attached. +#. 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 `DigitalOcean `_. You might need to + attach a credit card or other payment method to your account before you + can proceed with the tutorial. + +#. Click the **Create** button on the top right, and select **Droplets** from + the dropdown menu. DigitalOcean calls servers **droplets**. + + .. image:: images/digitalocean/create-menu.png + :alt: Dropdown menu on clicking 'create' in top right corner + + This takes you to a page titled **Create Droplets** that lets you configure + your server. + +#. Under **Choose an image**, select **18.04 x64** under **Ubuntu**. + + .. image:: images/digitalocean/select-image.png + :alt: Select 18.04 x64 image under Ubuntu + +#. Under **Choose a size**, select the size of the server you want. The default + (4GB RAM, 2CPUs, 20 USD / month) is not a bad start. You can resize your server + later if you need. + +#. Scroll down to **Select additional options**, and select **User data**. + + .. image:: images/digitalocean/additional-options.png + :alt: Turn on User Data in additional options + + This opens up a textbox where you can enter a script that will be run + when the server is created. We will use this to set up The Littlest JupyterHub + on this server. + +#. Copy the text below, and paste it into the user data text box. 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 the **Finalize and create** section, enter a ``hostname`` that descriptively + identifies this server for you. + + .. image:: images/digitalocean/hostname.png + :alt: Select suitable hostname for your server + +#. Click the **Create** button! You will be taken to a different screen, + where you can see progress of your server being created. + + .. image:: images/digitalocean/server-create-wait.png + :alt: Server being created + +#. In a few seconds your server will be created, and you can see the **public IP** + used to access it. + + .. image:: images/digitalocean/server-create-done.png + :alt: Server finished creating, public IP available + +#. The Littlest JupyterHub is now installing in the background on your new server. + It takes around 5-10 minutes for this installation to complete. + +#. Check if the installation is complete by copying the **public ip** + of your server, and trying to access it with a browser. This will fail until + the installation is complete, so be patient. + +#. When the installation is complete, 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 6, 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-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/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. diff --git a/docs/tutorials/images/digitalocean/additional-options.png b/docs/tutorials/images/digitalocean/additional-options.png new file mode 100644 index 0000000..70660a2 Binary files /dev/null and b/docs/tutorials/images/digitalocean/additional-options.png differ diff --git a/docs/tutorials/images/digitalocean/create-menu.png b/docs/tutorials/images/digitalocean/create-menu.png new file mode 100644 index 0000000..9d3f8cd Binary files /dev/null and b/docs/tutorials/images/digitalocean/create-menu.png differ diff --git a/docs/tutorials/images/digitalocean/hostname.png b/docs/tutorials/images/digitalocean/hostname.png new file mode 100644 index 0000000..c815c9c Binary files /dev/null and b/docs/tutorials/images/digitalocean/hostname.png differ diff --git a/docs/tutorials/images/digitalocean/select-image.png b/docs/tutorials/images/digitalocean/select-image.png new file mode 100644 index 0000000..bc6f72d Binary files /dev/null and b/docs/tutorials/images/digitalocean/select-image.png differ diff --git a/docs/tutorials/images/digitalocean/server-create-done.png b/docs/tutorials/images/digitalocean/server-create-done.png new file mode 100644 index 0000000..84cab63 Binary files /dev/null and b/docs/tutorials/images/digitalocean/server-create-done.png differ diff --git a/docs/tutorials/images/digitalocean/server-create-wait.png b/docs/tutorials/images/digitalocean/server-create-wait.png new file mode 100644 index 0000000..03f5b83 Binary files /dev/null and b/docs/tutorials/images/digitalocean/server-create-wait.png differ diff --git a/docs/tutorials/images/first-login.png b/docs/tutorials/images/first-login.png new file mode 100644 index 0000000..74ef357 Binary files /dev/null and b/docs/tutorials/images/first-login.png differ diff --git a/docs/tutorials/quickstart.rst b/docs/tutorials/quickstart.rst index d933735..a89a84d 100644 --- a/docs/tutorials/quickstart.rst +++ b/docs/tutorials/quickstart.rst @@ -93,7 +93,7 @@ with ``sudo -E``. #. If you were already logged in to the web interface as the admin user, you might need to restart your server for your new powers to take effect. - .. image:: ../images/control_panel_button.png + .. image:: ../images/control-panel-button.png :alt: Control Panel button on top right of Notebook interface #. Log in as an admin user and open a Terminal in your Jupyter Notebook.