diff --git a/docs/images/providers/google/boot-disk-button.png b/docs/images/providers/google/boot-disk-button.png new file mode 100644 index 0000000..ef646be Binary files /dev/null and b/docs/images/providers/google/boot-disk-button.png differ diff --git a/docs/images/providers/google/boot-disk-size.png b/docs/images/providers/google/boot-disk-size.png new file mode 100644 index 0000000..670f722 Binary files /dev/null and b/docs/images/providers/google/boot-disk-size.png differ diff --git a/docs/images/providers/google/boot-disk-ubuntu.png b/docs/images/providers/google/boot-disk-ubuntu.png new file mode 100644 index 0000000..0a4683b Binary files /dev/null and b/docs/images/providers/google/boot-disk-ubuntu.png differ diff --git a/docs/images/providers/google/create-vm-button.png b/docs/images/providers/google/create-vm-button.png new file mode 100644 index 0000000..dacab3f Binary files /dev/null and b/docs/images/providers/google/create-vm-button.png differ diff --git a/docs/images/providers/google/create-vm-first.png b/docs/images/providers/google/create-vm-first.png new file mode 100644 index 0000000..36bf979 Binary files /dev/null and b/docs/images/providers/google/create-vm-first.png differ diff --git a/docs/images/providers/google/enable-billing.png b/docs/images/providers/google/enable-billing.png new file mode 100644 index 0000000..2400046 Binary files /dev/null and b/docs/images/providers/google/enable-billing.png differ diff --git a/docs/images/providers/google/firewall.png b/docs/images/providers/google/firewall.png new file mode 100644 index 0000000..bc425a8 Binary files /dev/null and b/docs/images/providers/google/firewall.png differ diff --git a/docs/images/providers/google/left-menu-button.png b/docs/images/providers/google/left-menu-button.png new file mode 100644 index 0000000..86129e8 Binary files /dev/null and b/docs/images/providers/google/left-menu-button.png differ diff --git a/docs/images/providers/google/machine-type-advanced.png b/docs/images/providers/google/machine-type-advanced.png new file mode 100644 index 0000000..9b626ec Binary files /dev/null and b/docs/images/providers/google/machine-type-advanced.png differ diff --git a/docs/images/providers/google/machine-type-basic.png b/docs/images/providers/google/machine-type-basic.png new file mode 100644 index 0000000..1e351e3 Binary files /dev/null and b/docs/images/providers/google/machine-type-basic.png differ diff --git a/docs/images/providers/google/management-button.png b/docs/images/providers/google/management-button.png new file mode 100644 index 0000000..19d9ba6 Binary files /dev/null and b/docs/images/providers/google/management-button.png differ diff --git a/docs/images/providers/google/no-service-account.png b/docs/images/providers/google/no-service-account.png new file mode 100644 index 0000000..00bed94 Binary files /dev/null and b/docs/images/providers/google/no-service-account.png differ diff --git a/docs/images/providers/google/startup-script.png b/docs/images/providers/google/startup-script.png new file mode 100644 index 0000000..14a52a1 Binary files /dev/null and b/docs/images/providers/google/startup-script.png differ diff --git a/docs/images/providers/google/vm-created.png b/docs/images/providers/google/vm-created.png new file mode 100644 index 0000000..3424876 Binary files /dev/null and b/docs/images/providers/google/vm-created.png differ diff --git a/docs/images/providers/google/vm-creating.png b/docs/images/providers/google/vm-creating.png new file mode 100644 index 0000000..547c7dd Binary files /dev/null and b/docs/images/providers/google/vm-creating.png differ diff --git a/docs/images/providers/google/vm-instances-menu.png b/docs/images/providers/google/vm-instances-menu.png new file mode 100644 index 0000000..9f45851 Binary files /dev/null and b/docs/images/providers/google/vm-instances-menu.png differ diff --git a/docs/tutorials/google.rst b/docs/tutorials/google.rst new file mode 100644 index 0000000..476174b --- /dev/null +++ b/docs/tutorials/google.rst @@ -0,0 +1,264 @@ +.. _tutorial_quickstart_google: + +Tutorial: JupyterHub on Google Cloud +==================================== + +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 +`Google Cloud `_. + +Prerequisites +------------- + +#. A Google Cloud account. You might use the free credits for trying it out! + +Step 1: Installing The Littlest JupyterHub +------------------------------------------ + +Let's create the server on which we can run JupyterHub. + +#. Log in to `Google Cloud Console `_ with + your Google Account. + +#. Open the navigation menu by clicking the button with three lines on the top + left corner of the page. + + .. image:: ../images/providers/google/left-menu-button.png + :alt: Button to open the menu + + This opens a menu with all the cloud products Google Cloud offers. + +#. Under **Compute Engine**, select **VM Instances**. + + .. image:: ../images/providers/google/vm-instances-menu.png + :alt: Navigation Menu -> Compute Engine -> VM Instances + +#. If you are using Google Cloud for the first time, you might have to + enable billing. Google will present a screen asking you to enable billing + to proceed. Click the **Enable Billing** button and follow any prompts + that appear. + + .. image:: ../images/providers/google/enable-billing.png + :alt: Enable billing if needed. + + It might take a few minutes for your account to be set up. + +#. Once Compute Engine is ready, click the **Create** button to start + creating the server that'll run TLJH. + + .. image:: ../images/providers/google/create-vm-first.png + :alt: Create VM page when using it for the first time. + + If you already have VMs running in your project, the screen will look + different. But you can find the **Create** button still! + +#. This shows you a page titled **Create an instance**. This lets you customize + the kind of server you want, the resources it will have & what it'll be called. + +#. Under **Name**, give it a memorable name that identifies what purpose this + JupyterHub will be used for. + +#. **Region** specifies the physical location where this server will be hosted. + Generally, pick something close to where most of your users are. Note that + it might increase the cost of your server in some cases! + +#. For **Zone**, pick any of the options. Leaving the default as is is fine. + +#. Under **Machine** type, select the amount of CPU / RAM / GPU you want for your + server. + + You can select a preset combination in the default **basic view**. + + .. image:: ../images/providers/google/machine-type-basic.png + :alt: Select a preset VM type + + If you want to add **GPUs**, you should click the **Customize** button & + use the **Advanced View**. You need to request `a quota increase `_ + before you can use GPUs. + + .. image:: ../images/providers/google/machine-type-advanced.png + :alt: Select a customized VM size + +#. Under **Boot Disk**, click the **Change** button. This lets us change the + operating system and the size of your disk. + + .. image:: ../images/providers/google/boot-disk-button.png + :alt: Changing Boot Disk & disk size + + This should open a **Boot disk** popup. + +#. Select **Ubuntu 18.04 LTS** from the list of operating system images. + + .. image:: ../images/providers/google/boot-disk-ubuntu.png + :alt: Selecting Ubuntu 18.04 for OS + +#. You can also change the **type** and **size** of your disk at the bottom + of this popup. + + .. image:: ../images/providers/google/boot-disk-size.png + :alt: Selecting Boot disk type & size + + **Standard persistent disk** type gives you a slower but cheaper disk, similar + to a hard drive. **SSD persistent disk** gives you a faster but more expensive + disk, similar to an SSD. + + In Google Cloud, the higher your disk **size** the faster your disk is. The + default (10GB) is pretty low, so you might want to increase it. + +#. Click the **Select** button to dismiss the Boot disk popup and go back to the + Create an instance screen. + +#. Under **Identity and API access**, select **No service account** for the + **Service account** field. This prevents your JupyterHub users from automatically + accessing other cloud services, increasing security. + + .. image:: ../images/providers/google/no-service-account.png + :alt: Disable service accounts for the server + +#. Under **Firewall**, check both **Allow HTTP Traffic** and **Allow HTTPS Traffic** + checkboxes. + + .. image:: ../images/providers/google/firewall.png + :alt: Allow HTTP & HTTPS traffic to your server + +#. Click the **Management, disks, networking, SSH keys** link to expand more + options. + + .. image:: ../images/providers/google/management-button.png + :alt: Expand management options by clicking link. + + This displays a lot of advanced options, but we'll be only using one of them. + +#. Copy the text below, and paste it into the **Starup script** 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 + + .. image:: ../images/providers/google/startup-script.png + :alt: Install JupyterHub with the Startup script textbox + +#. Click the **Create** button at the bottom to start your server! + + .. image:: ../images/providers/google/create-vm-button.png + :alt: Launch an Instance / Advanced Options dialog box + +#. We'll be sent to the **VM instances** page, where we can see that our server + is being created. + + .. image:: ../images/providers/google/vm-creating.png + :alt: Spinner with vm creating + +#. In a few seconds your server will be created, and you can see the **External IP** + used to access it. + + .. image:: ../images/providers/google/vm-created.png + :alt: VM created, external 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 **External 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: Adding 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. + + **Note**: These users will be added as UNIX users on the underlying + Jetstream instance, too, and admin users will have ``sudo`` privileges. + (The user will be created the first time the user's server is started, + e.g. upon first login.) + +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 + +#. For example, try installing `gdal `_ from `conda-forge `_. + + .. code-block:: bash + + sudo -E conda install -y -c conda-forge gdal + + The ``sudo -E`` is very important! + +#. Alternatively, try installing `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 need to restart their notebook's +kernel to make the new libraries available. + +See :ref:`user_environment` for more information.