Skip to content

☁️🚧 Deploy your own JupyterHub using a one-click Azure button

License

Notifications You must be signed in to change notification settings

trallard/TLJH-azure-button

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

79 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

The Littlest JupyterHub deploy to Azure button

NEW ✨✨ The minimum VM Ubuntu version has been updated to 22.4 thanks to @ionicsolutions ✨✨



Deploy your own Littlest JupyterHub using the blue "Deploy to Azure" button above πŸ‘†πŸΌ
This project is licensed under the MIT OSI license.
MIT license badge

What is the Littlest JupyterHub? πŸ€”

A simple JupyterHub distribution for a small (1-100) number of users on a single server. You can find more info about it in the official docs.

Prerequisites πŸ“

You need an Azure account to be able to spin your JupyterHub.

🀩 If you do not have an Azure subscription you can get started with a free Azure subscription with 200 USD

What is in this repo? πŸ”

This repository contains the ARM (Azure Resource Manager) template for the Littlest JupyterHub deployment. This template was created to help you deploy a vanilla Littlest JupyterHub by clicking on the "Deploy to Azure" blue button at the top of this document.

It follows the recommended configuration in the official The Littlest JupyterHub docs but eliminates the deployment friction by predefining some standard settings.

How does the Deploy on Azure button work? πŸ’»

The ARM template contains all the configurations needed to deploy your own Littlest JupyterHub on Azure.

This template follows the configuration detailed in https://the-littlest-jupyterhub.readthedocs.io/en/latest/install/azure.html. But it reduces some friction by eliminating the need to create resources manually using the Azure portal.

Note You still need to remove your resources manually when you are done using them. Otherwise, you will be charged for their use.

Deployment instructions πŸš€

To deploy your TLJH follow these steps:

  1. Create an Azure account (if you need a free one go to πŸ‘‰πŸΌ this link πŸ‘ˆπŸΌ)

  2. Click on the Deploy to Azure button at the top of this README. This will redirect you to the Azure portal login page.

  3. Login to your account.

  4. Fill in the details on the next screen (see details below):

    Azure dashboard - Custom deployment form

    • Subscription: choose the subscription you want to use (e.g. Free Trial)
    • Resource group: this will keep all of our resources together. If you have never created a resource group click on Create new and give it a meaningful name (e.g. jupyter-resources)
    • Location: this is the Azure region where you want all your resources to be (e.g. WestEurope, you can check all the available regions here)
    • Virtual Machine Name: the name for your virtual machine. The default is TLHJ-Ubuntu, but you can choose any name you prefer.
    • Virtual Machine Size: the workload will determine this. You can check the list of available VM sizes on the Azure website. This is a dropdown from version 1.1.0 onwards
    • Admin UserName: this will be the root user and is needed for the management of your TLJH
    • Admin password: choose a secure password for your root user. Note that this is not displayed later on in the outputs for security reasons so make sure to make note of it.
    • OS Disk Type: you have the options Standard HDD (LRS), Standard SSD and Premium SSD (for more details see the docs). The default value is Standard_LRS.
    • Data Disk Size: the size of your Data disk size (for more information visit the docs)
    • Script Location: This is the script that installs the Jupyter server in your VM. By default, it points to the script in this repository corresponding to the vanilla installation of TLJH (scripts/install.sh). Read more in the customising the installer section of this README.

    By default, the template allows network traffic through HTTP and HTTPS.

  5. Once completed, read the terms and conditions and if you are happy with them, go ahead and tick the I agree to the terms and conditions stated above box and click on the Purchase button.

    The deployment will take around 10 minutes - first, all your resources will be deployed, and then THLJ will be installed on your VM.

  6. To check your new Virtual Machine Expand the left-hand panel by clicking on the ">>" button in the top left corner of your dashboard. Find the Virtual Machines tab and click on it.

    azure portal vm

  7. Click on your Virtual Machine, copy the Public IP address and access it through your web browser.

    ip

    Warning This page will be unavailable during the installation of the server. If this happens, be patient, give it a bit longer and refresh the page.

    Once the installation is complete, you will get a login page like the one below:

    login screen
  8. Login using the admin username and password you created before

  9. Congratulations you have a running working JupyterHub πŸŽ‰

πŸ‘©πŸΏβ€πŸ’»βœ¨ You are now ready to add users, install packages and start using your JupyterHub. For instructions on how to do this visit πŸ‘‰πŸΌ the official The Littlest JupyterHub documentation.

Customising the installer ✨

You can customise the installer by adding command line parameters. From v1.1.0 you can now specify a TLJH install script to customise the installation.

For example, if you want to install Python packages in the user environment from a requirements.txt file you can pass the parameter --user-requirements-txt-URL <url-to-requirements.txt> where URL-to-requirements.txt must be a valid URL:

--user-requirements-txt-URL https://raw.githubusercontent.com/data-8/materials-sp18/master/requirements.txt

Note When pointing to a file on GitHub, make sure to use the 'Raw' version. It should point to raw.githubusercontent.com, not github.com.

Let's use as an example the voilΓ -gallery plugin`. First, you will have to create a bash script with the customised JupyterHub installer:

# !/bin/bash

curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \
 | sudo python3 - \
   --plugin git+https://github.com/voila-dashboards/tljh-voila-gallery@master#"egg=tljh-voila-gallery&subdirectory=tljh-voila-gallery"

And update the scriptLocation parameter accordingly when deploying your littlest JupyterHub (in the details form after you log into your Azure account). For the above example:

https://raw.githubusercontent.com/trallard/TLJH-azure-button/feature-plugins/scripts/install_voila.sh

So once the VM is created and the plugins installed you can go to the public IP of your VM. In the case of the VoilΓ  plugin, you will be greeted with this screen instead of the usual TLHJ one:

VoilΓ  screen

Always make sure that the script is publicly available (e.g. public repo, public gist) and that you are pointing to the raw content.

Note For more details on customising your installation visit the main TLJH documentation.

In this repo you will find the following installation scripts:

Architecture 🚧

When you deploy a JupyterHub on Azure (either using the Deploy to Azure button or following the steps from the docs) the following resources are created:

vms

They are all grouped in the same region defined for your Resource group. Also, note that the storage disk created with this template will be of the same type as the OS disk type` you provide on the template.

If you want to learn more about VM types and sizes, including compatibility between the VMS and storage (standard or premium) you can visit the official Azure Linux VM documentation.

Details on how to delete and stop your virtual machine can be found at https://the-littlest-jupyterhub.readthedocs.io/en/latest/howto/providers/azure.html.

If you want to get rid of all the associated resources after you are done with your JupyterHub the easiest way to do it is to delete the resource group altogether (provided you do not have other resources in this group that you might need later).

Deleting your resources πŸ—‘

To delete a resource group from the Azure portal:

  1. Go to Resource groups on the left-hand panel of your Azure Portal.
  2. Click on the resource group that contains your JupyterHub resources.
  3. Click on Delete resource group you will then be asked to confirm the operation. This operation will take between 5 and 10 minutes.

delete group

See the useful tips and commands section for the command to delete using the command line and the Azure CLI.

Additional resources πŸ“–

Here are some links that you might find useful when using the content in this repo.

πŸ“– Azure Resource Manager templates docs

πŸ“– The Littlest JupyterHub docs

πŸ“– VM available regions - Azure docs

πŸ“– Azure VM sizes documentation

πŸ“– Azure VMs disks documentation

πŸ“– Install the Azure CLI

Useful tips and commands πŸ‘

If you are familiar with the command line and have the az cli installed the following commands might come in handy:

  • Finding available VM sizes in a specific location
az vm list-sizes --location <location> --output table
  • View the current size of a VM with:
az vm show --resource-group <resource-group> --name <VirtualMachineName> --query hardwareProfile.vmSize
  • You can resize your VM after it has been deployed if needed
# First check if the desired size is available
az vm list-vm-resize-options --resource-group <resource-group> --name  <VirtualMachineName> --query [].name

# resize the VM
az vm resize --resource-group <resource-group> --name  <VirtualMachineName> --size <desired-size>
  • Stop virtual machine
az vm stop --resource-group <resource-group> --name  <VirtualMachineName>
  • Delete resource group
az group delete --name <resource-group> --no-wait --yes

Issues and contributing πŸ––πŸΌ

Contributions are welcome. Also, if you encounter any issues, please go ahead and create an issue in this repo.

The detailed contribution guidelines can be found at CONTRIBUTING, make sure to have a look first πŸ‘€

About

☁️🚧 Deploy your own JupyterHub using a one-click Azure button

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages