Deploying JupyterLab
Responsibility Disclaimer:
This page is an example; you are responsible for what you deploy and maintain. Expand to read more.
This page is provided for demonstration purposes only. It is not maintained as a supported Scalingo product, reference implementation or tutorial. Scalingo does not guarantee that it works continuously, remains compatible over time, or is suitable for production usage.
This demo may include external dependencies not maintained by Scalingo, customers remain responsible for:
- Validating the code and configuration they deploy against applicable security, compliance and operational requirements before any production use.
- Maintaining the applications and components they control during runtime, including monitoring releases, deploying new versions, monitoring application health and scaling as needed.
This notice does not modify or limit the applicable Agreement or Scalingo’s contractual commitments.
JupyterLab is an open-source web application that allows to create and share documents called notebooks that combine live code, equations, visualizations, and narrative text. Users can run code step by step, inspect outputs instantly, and modify their work dynamically. This makes it ideal for learning, data analysis, or scientific computing.
Planning your Deployment
-
By default, JupyterLab stores notebooks on the local filesystem. Since Scalingo’s filesystem is ephemeral, this is not an option. In this tutorial, the local filesystem is replaced with a Scalingo for PostgreSQL® addon to persist the notebooks. We usually advise to start with a Scalingo for PostgreSQL® Starter 512 addon, and upgrade to a more powerful plan later if need be.
-
To make JupyterLab store notebooks in the PostgreSQL® database, we use a Python module called
pgcontents. This module is a PostgreSQL-backed implementation of IPEP 27, and aims at providing a drop-in replacement for IPython’s standard filesystem-backed storage system. Put in others words,pgcontentsallows to replace all local filesystem storage operations with database-backed storage ones.Leveraging this ensures:
- Notebooks survive application restarts.
- Notebooks benefit from Scalingo’s automated database backups.
- No data loss due to Scalingo’s ephemeral filesystem.
-
Depending on several factors such as the size of your datasets, the complexity of your computations, and the number of notebooks you run at the same time, JupyterLab can consume a lot of RAM. We consequently advise to deploy an L container, and change for a more powerful one later if needed.
-
JupyterLab supports two main authentication mechanisms to secure access to an instance:
- Token authentication: Access is granted to anyone who possesses the valid authentication token.
- Password authentication: Access is protected by a user-defined password, which JupyterLab stores as a hash in its local configuration file.
Given that user-defined passwords are stored on the container’s ephemeral storage, they woud not survive reboots, scaling, etc. As a consequence, we will use token-based authentication exclusively. Password authentication will be fully disabled for this demo.
For more information about JupyterLab authentication mechanisms and security, please refer to the official documentation.
Deploying
Using the Command Line
- Sparse-checkout the
scalingo-labsrepository, and extend it by downloading the directory containing the code for this demo:git clone --sparse https://github.com/Scalingo/scalingo-labs cd scalingo-labs git sparse-checkout set jupyterlab cd jupyterlab - Create a new git repository from the downloaded
jupyerlabdirectory:git init git add . git commit --message "Initialize JupyterLab project" - Create the application on Scalingo:
scalingo create my-jupyter - Provision a Scalingo for PostgreSQL® Starter 512 addon:
scalingo --app my-jupyter addons-add postgresql postgresql-starter-512 - (optional) Instruct the platform to run the
webprocess type in a single L container:scalingo --app my-jupyter scale web:1:L - Set the access token that grants access to JupyterLab:
scalingo --app my-jupyter env-set JUPYTER_TOKEN="$( openssl rand -hex 24 )"In this example, we use
opensslto generate a random secret. Feel free to use another method that suits you best. - Everything’s ready, deploy to Scalingo:
git push scalingo main
Using the Terraform Provider
-
Start by creating a new repository in your SCM, using the files we provide in the dedicated repository subdirectory.
-
Create a variable to store the access token.
variable "access_token" { type = string sensitive = true }
</aside>
- Create the application:
resource "scalingo_app" "my-jupyter" { name = "my-jupyter" stack_id = "scalingo-26" force_https = true environment = { JUPYTER_TOKEN = var.access_token } } - Link the app to your repository:
data "scalingo_scm_integration" "github" { scm_type = "github" } resource "scalingo_scm_repo_link" "default" { auth_integration_uuid = data.scalingo_scm_integration.github.id app = scalingo_app.my-jupyter.id source = "https://github.com/<username>/jupyter-scalingo" branch = "main" } - Provision a Scalingo for PostgreSQL® Starter 512 addon:
resource "scalingo_addon" "my-jupyter-db" { app = scalingo_app.my-jupyter.id provider_id = "postgresql" plan = "postgresql-starter-512" } - (optional) Instruct the platform to run the
webprocess type in a single L container:resource "scalingo_container_type" "web" { app = scalingo_app.my-jupyter.id name = "web" size = "L" amount = 1 } - Create the access token, and run Terraform:
export TF_VAR_access_token="$( openssl rand -hex 24 )" terraform plan terraform applyIn this example, we use
opensslto generate a random secret. Feel free to use another method that suits you best. - Once Terraform is done, your JupyterLab instance is ready to be deployed:
- Head to your dashboard
- Click on your JupyterLab application
- Click on the Deploy tab
- Click on Manual deployment in the left menu
- Click the Trigger deployment button
- After a few seconds, your JupyterLab is finally up and running!
Updating
JupyterLab is a Python application, distributed via its own package called
jupyterlab. Updating to a newer version mainly consists
in updating this package:
-
In your repository, ask
uvto either update:- To the latest version available:
uv sync --upgrade-package jupyterlab - To a specific version:
uv add 'jupyterlab>=<NEW_VERSION>'
- To the latest version available:
-
Commit the update:
git add pyproject.toml uv.lock git commit --message="Upgrade JupyterLab to <NEW_VERSION>"
Using the Command Line
- Make sure you’ve successfully followed the first steps
- Push the changes to Scalingo:
git push scalingo main
Using the Terraform Provider
- Make sure you’ve successfully followed the first steps
- Push the changes to your repository:
git push origin main - Head to your dashboard
- Click on your JupyterLab application
- Click on the Deploy tab
- Click on Manual deployment in the left menu
- Click the Trigger deployment button
- After a few seconds, your updated JupyterLab instance is ready!
Customizing
While JupyterLab supports several environment variables to customize its
behavior, most of its configuration lies in different configuration files, such
as jupyter_server_config.py. These files are written in Python.
To generate a list of all available options, generate a configuration file from a one-off container, and inspect it:
- After a first successful deployment, launch a one-off:
scalingo --app my-jupyter run bash - From the one-off, generate the configuration file:
jupyter lab --generate-config
Environment
The deployment process uses the following environment variable:
-
JUPYTER_TOKENAllows to specify the token that protects the JupyterLab interface.
Defaults to being unset, which falls back to JupyterLab generating a random token itself (not recommended).