Deploying on Vercel and Netlify

Vercel and Netfliy are popular hosted platforms for deploying static website.

They make it easy and convenient to host static websites from existing git repositories, and make them widely available via their CDN.

Netlify

To deploy your own JupyterLite on Netlify, you can start from the JupyterLite Demo by generating a new repository from the template.

Then add a runtime.txt file with 3.7 as the content to specify Python 3.7 as dependency.

Finally specify jupyter lite build --contents content --output-dir dist as the “Build Command”, and dist as “Published Directory”:

You might also want to specify the --debug flag to get extra log messages:

Vercel

Just like Netlify, Vercel can connect to an existing git repository and seamlessly deploy static files on push and PR events (previews).

Here the configuration is very similar to Netlify. You can specify the same jupyter lite build --contents content --output-dir dist build command and configure dist as the published directory.

Using micromamba to create the build environment

The build environments of hosted platforms like Netlify and Vercel generally allow for limited control on the Python version installed on the build machine.

This was the case for a while when their build image only included Python 3.6 while JupyterLite requires Python 3.7+. This can be limiting in some cases, especially when you want to have more control on the build.

Fortunately it is possible to run arbitrary bash scripts, which provides a convenient escape hatch.

Specify the Python packages in a requirements-deploy.txt file with additional dependencies if needed:

jupyterlab~=3.4
jupyterlite-core
jupyterlite-pyodide-kernel

Then create a new deploy.sh file with the following content:

#!/bin/bash

yum install wget -y

wget -qO- https://micro.mamba.pm/api/micromamba/linux-64/latest | tar -xvj bin/micromamba

export PATH="$PWD/bin:$PATH"
export MAMBA_ROOT_PREFIX="$PWD/micromamba"

# Initialize Micromamba shell
./bin/micromamba shell init -s bash --no-modify-profile -p $MAMBA_ROOT_PREFIX

# Source Micromamba environment directly
eval "$(./bin/micromamba shell hook -s bash)"

# Activate the Micromamba environment
micromamba create -n jupyterenv python=3.11 -c conda-forge -y
micromamba activate jupyterenv

# install the dependencies
python -m pip install -r requirements-deploy.txt

# build the JupyterLite site
jupyter lite --version
jupyter lite build --contents content --output-dir dist

Micromamba creates a new self-contained environment, which makes it very convenient to install any required package without being limited by the build image.

Then configure the build command and output directory, for example on Vercel:

You might also want to specify the --debug flag to get extra log messages:

jupyter lite build --debug

Configuring HTTP headers

Starting with JupyterLite 0.4.0, it is possible to have more reliable file system access from the kernel via the use of synchronous communication with the kernel over the SharedArrayBuffer browser feature. See the Contents guide for more information.

However this requires setting two HTTP headers for the SharedArrayBuffer to be enabled on the page.

Adding the headers to Netlify

Create a netlify.toml file at the root of the repo with the following content:

[[headers]]
for = "/*"
  [headers.values]
    Cross-Origin-Opener-Policy = "same-origin"
    Cross-Origin-Embedder-Policy = "require-corp"

Adding the headers to Vercel

Create a vercel.json file at the root of the repo with the following content:

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Cross-Origin-Embedder-Policy",
          "value": "require-corp"
        },
        {
          "key": "Cross-Origin-Opener-Policy",
          "value": "same-origin"
        }
      ]
    }
  ]
}