Installing on Azure

Goal

By the end of this tutorial, you should have a JupyterHub with some admin users and a user environment with packages you want to be installed running on Microsoft Azure.

This tutorial leads you step-by-step for you to manually deploy your own JupyterHub on Azure cloud.

Note

✨ The Deploy to Azure button project allows you to deploy your own JupyterHub with minimal manual configuration steps. The deploy to Azure button allows you to have a vanilla configuration in just one-click and by assigning some variables.

Check it out at https://github.com/trallard/TLJH-azure-button.

Prerequisites

  • A Microsoft Azure account.
  • To get started you can get a free account which includes 150 dollars worth of Azure credits (get a free account here)

These instructions cover how to set up a Virtual Machine on Microsoft Azure. For subsequent information about creating your JupyterHub and configuring it, see The Littlest JupyterHub guide.

Step 1: Installing The Littlest JupyterHub

We start by creating the Virtual Machine in which we can run TLJH (The Littlest JupyterHub).

  1. Go to Azure portal and login with your Azure account.
  2. Expand the left-hand panel by clicking on the “>>” button on the top left corner of your dashboard. Find the Virtual Machines tab and click on it.
Virtual machines on Azure portal
  1. Click + add to create a new Virtual Machine

    Add a new virtual machine

#. Select Create VM from Marketplace in the next screen. A new screen with all the options for Virtual Machines in Azure will displayed.

Create VM from the marketplace
  1. Choose an Ubuntu server for your VM:
    • Click Ubuntu Server 18.04 LTS.
    • Make sure Resource Manager is selected in the next screen and click Create
    Ubuntu VM
  2. Customise the Virtual Machine basics:
    • Subscription. Choose the “Free Trial” if this is what you’re using. Otherwise, choose a different plan. This is the billing account that will be charged.
    • Resource group. Resource groups let you keep your Azure tools/resources together in an availability region (e.g. WestEurope). If you already have one you’d like to use it select that resource.

    Note

    If you have never created a Resource Group, click on Create new

    Create a new resource group
    • Name. Use a descriptive name for your virtual machine (note that you cannot use spaces or special characters).
    • Region. Choose a location near where you expect your users to be located.
    • Availability options. Choose “No infrastructure redundancy required”.
    • Image. Make sure “Ubuntu Server 18.04 LTS” is selected (from the previous step).
    • Authentication type. Change authentication type to “password”.
    • Username. Choose a memorable username, this will be your “root” user, and you’ll need it later on.
    • Password. Type in a password, this will be used later for admin access so make sure it is something memorable.
    Add password to VM
    • Login with Azure Active Directory. Choose “Off” (usually the default)
    • Inbound port rules. Leave the defaults for now, and we will update these later on in the Network configuration step.
  3. Before clicking on “Next” we need to select the RAM size for the image.
    • For this we need to make sure we have enough RAM to accommodate your users. For example, if each user needs 2GB of RAM, and you have 10 total users, you need at least 20GB of RAM on the machine. It’s also good to have a few GB of “buffer” RAM beyond what you think you’ll need.
    • Click on Change size (see image below)
    Choose vm size

    Note

    For more information about estimating memory, CPU and disk needs check The memory section in the TLJH documentation

    • Select a suitable image (to check available images and prices in your region click on this link).
  4. Disks (Storage):
    • Disk options: select the OS disk type there are options for SDD and HDD. SSD persistent disk gives you a faster but more expensive disk than HDD.
    • Data disk. Click on create and attach a new disk. Select an appropriate type and size and click ok.
    • Click “Next”.
    Create and attach disk Choose a disk size
  5. Networking
    • Virtual network. Leave the default values selected.
    • Subnet. Leave the default values selected.
    • Public IP address.Leave the default values selected. This will make your server accessible from a browser.
    • Network Security Group. Choose “Basic”
    • Public inbound ports. Check HTTP, HTTPS, and SSH.
    Choose networking ports
  6. Management
    • Monitoring
      • Boot diagnostics. Choose “On”.
      • OS guest diagnostics. Choose “Off”.
      • Diagnostics storage account. Leave as the default.
    • Auto-Shutdown
      • Enable auto-shutdown. Choose “Off”.
    • Backup
      • Backup. Choose “Off”.
    • System assigned managed identity Select “Off”
    Choose VM Backup
  7. Advanced settings
    • Extensions. Make sure there are no extensions listed

    • Cloud init. We are going to use this section to install TLJH directly into our Virtual Machine. Copy the code snippet below:

      #!/bin/bash
      curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \
        | sudo python3 - \
          --admin <admin-user-name>
      

      where the username is the root username you chose for your Virtual Machine.

      Install TLJH

    Note

    See What does the installer do? if you want to understand exactly what the installer is doing. Customizing the Installer documents other options that can be passed to the installer.

  8. Check the summary and confirm the creation of your Virtual Machine.

  9. Check that the creation of your Virtual Machine worked.
    • Wait for the virtual machine to be created. This might take about 5-10 minutes.
    • After completion, you should see a similar screen to the one below:
    Deployed VM
  10. Note that the Littlest JupyterHub should be installing in the background on your new server.

    It takes around 5-10 minutes for this installation to complete.

  11. Click on the Go to resource button
    Go to VM
  12. Check if the installation is completed by copying the Public IP address of your virtual machine, and trying to access it with a browser.

    Public IP address

    Note that accessing the JupyterHub will fail until the installation is complete, so be patient.

  13. When the installation is complete, it should give you a JupyterHub login page.

    JupyterHub log-in page
  14. 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.

  15. 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!

  1. Open the Control Panel by clicking the control panel button on the top right of your JupyterHub.

    Control panel button in notebook, top right
  2. In the control panel, open the Admin link in the top left.

    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.

  3. Click the Add Users button.

    Add Users button in the admin page

    A Add Users dialog box opens up.

  4. Type the names of users you want to add to this JupyterHub in the dialog box, one per line.

    Adding users with add users dialog

    You can tick the Admin checkbox if you want to give admin rights to all these users too.

  5. 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.

  1. Log in as an admin user and open a Terminal in your Jupyter Notebook.

    New Terminal button under New menu
  2. Install gdal from conda-forge.

    sudo -E conda install -c conda-forge gdal
    

    The sudo -E is very important!

  3. Install there with pip

    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 Install conda, pip or apt packages for more information.