Create your first Notebooks instance and run a demo Notebook

Prerequisites

• You have a STACKIT customer account: Create a customer Account
• You have a STACKIT user account: Create a user account
• You have a STACKIT project: Create a project

In this guide, you create a Notebooks instance, write your example Notebook and run it.

Creating a Notebooks instance

Note: Only the Lite version of STACKIT Notebooks is available yet. It can only be requested and booked by opening a support ticket.

Monitoring

To gain insights about the resource consumption, number of (active) users, runtime, etc. of your Notebooks, you can opt-in to export metrics to an already existing STACKIT Observability instance. Note: An Observability instance with the plan “Observability-Monitoring-Basic-EU01” or higher is recommended. If you do plan to not also use it for log aggregation, use the “Monitoring-only” variant.

Writing and running your first Notebook

This guide will walk you through the entire process of creating a simple Notebook, adding it to your Git repository, and running it.

1. Launch your user server

   1. Select “Go to Notebooks”.
   2. Authenticate against the configured Identity Provider.
   3. After successful authentication, you are asked about the server you want to launch. You can choose between “Light” (2 vCPU and 8 GiB RAM) and “Medium” (6 vCPU and 24 GiB RAM).
   4. Selecting “Start” launches the server. It spawns a new Kubernetes Pod with a persistent volume that preserves data between server restarts (including change of server type). The PVC is mounted at /home/jovyan in the Jupyter user pod. This directory is persistent, storing user data like notebooks and files. All other directories in the container (for example, tmp) are volatile and reset on pod restart.

2. Getting to know the Launcher

   Once the server is ready, the JupyterLab “Launcher” shows up. It offers Python3-based Notebooks editing, VS Code editor, and other options. We’ll focus on Notebooks, so choose “Python 3 (ipykernel)”.

3. Edit and save your first Notebook Notebooks are documents combining runnable code with narrative text (markdown, plain-text). The Notebook starts empty with a cursor in a code cell. Enter print("Hello World") and either select the Play button (▶️) or press Control + Enter. The result of the code run will show up just below.

   Now select the “Save” icon or press Control+S. Name the notebook “Getting Started”.

4. Install custom Libraries

   We recommend using mamba to install custom packages, as we also use it for the base image. Note that installed packages are be gone on restart unless installed with the --user flag. However, we do not recommend using the --user flag as then packages are persisted between restarts which might conflict with updates of the notebooks environment.

5. Shut down the server

   The server automatically shuts down after one hour of inactivity. However, you can also manually shut down the server when you are done with your work.

   In File select Hub Control Panel and then the red Stop My Server button. It immediately shuts down the running server and redirect you to server selection page.

   Congratulations, you have successfully authored your first notebook.

Set up Git

It is highly recommended to use Git, as mentioned in the Best Practises section.

To enable Git in your JupyterLab environment, select the Git icon in the left navigation bar of JupyterLab. Select Clone a repository (assuming you already have one) and enter the URL, and credentials. JupyterLab then clones the repository into the attached disk.

Once cloning is done, the Git view allows you to commit files, checkout branches, stage changes, push, etc.

Additional insights with STACKIT Observability

If you have opted-in for monitoring during STACKIT Notebooks setup, detailed metrics about the health and workload of your Notebooks instance is pushed to your STACKIT Observability instance. The instance contains a dashboard named STACKIT Notebooks that contains charts showing the status of JupyterHub itself and detailed metrics about notebook-servers, for example, CPU and memory consumption.