Deploying#
Deploying a JupyterLite site requires:
a copy of the JupyterLite site assets
often provided by the
pip
-installable python packagejupyterlite
an option set of configurations for the site and different apps
different options offer trade-offs between reproducibility, build speed, deployment size, and end-user performance, privacy, and security
a local, on-premises, or hosted HTTP server (doesn’t presently work with
file://
URLs)
Warning
Serving some of the kernels requires that your web server supports
serving application/wasm
files with the correct headers
Hint
An HTTPS-capable server is recommended for all but the simplest localhost
cases.
Get an Empty JupyterLite Site#
The minimum deployable site archive contains enough to run all of the default applications, but no content.
Hint
Use of the CLI is optional, but recommended. It offers substantially better integration with other Jupyter tools.
To get the Python CLI and API from PyPI:
python -m pip install --pre jupyterlite
# TODO: mamba install jupyterlite
To build an empty site (just the JupyterLite static assets):
jupyter lite init
Static Site: The Hard Way#
download a release archive from GitHub Releases
download nightly/work-in-progress builds from GitHub actions
clone/fork the [repository] and do a development build
TBD: use
cookiecutter-jupyterlite
TBD:
yarn add @jupyterlite/builder
fromnpmjs.com
Hint
It is recommended to put these files under revision control. See Configuring for what you can configure in your JupyterLite.
Build Tools#
While the JupyterLite CLI will create the correct assets for JupyterLite, it might not be enough to deploy along with the rest of your content.
WebPack#
At present, the core JupyterLite site and apps are not published as reusable packages. At some point in the future, a WebPack plugin might allow for integrating at this level.
sphinx#
Sphinx is the workhorse of documentation of not only the scientific Python documentation community, but also the broader Python ecosystem, and many languages beyond it. It is well adapted to building sites of any size, and tools like myst-nb enable make it very palletable to include executable, and even interactive, content.
JupyterLite assets can be copied to the default static directory in conf.py
, e.g.
docs/_static
with html_static_path
, or replace the entire site
with html_extra_path
html_static_path
#
This search path can be merged several layers deep, such that your theme assets, the “gold master” JupyterLite assets, and any customizations you wish to make are combined.
html_static_path = [
"_static",
"../upstream-jupyterlite",
"../my-jupyterlite" # <- these "win"
]
The composite directory will end up in docs/_build/_static
.
html_extra_path
#
A slightly more aggressive approach is to use html_extra_path
to
simply dump the assets directly into the doc folder. This approach can be used to
deploy a site that launches directly into your JupyterLite.
Adapting the example above:
html_extra_path = ["../upstream-jupyterlite", "../my-jupyterlite"]
Again, the last-written index.html
will “win” and be shown to visitors to /
, which
will immediately redirect to appUrl
as defined in the schema.
Standalone Servers#
Local#
Suitable for local development, many languages provide easy-to-use servers that can serve your JupyterLite locally while you get it working the way you want.
jupyter lite serve
#
The jupyter lite serve
command offers either a web server powered by Python’s built-in
http.server
or tornado
, which is likely to be available if any other Jupyter tools
are installed.
Jupyter#
If you’re already running a [Jupyter Server]-powered app, such as JupyterLab, your files
will be served correctly on e.g. http://localhost:8888/files
.
Python#
http.server#
The http
module in the Python standard library is a suitably-effective server for
local purposes.
python -m http.server -b 127.0.0.1
If you are using a recently-released Python 3.7+, this will correctly serve
application/wasm
files for pyodide.
sphinx-autobuild#
If using Sphinx, sphinx-autobuild provides a convenient way to manage both static content and rich interactive HTML like your JupyterLite.
sphinx-autobuild docs docs/_build
This will regenerate your docs site and automatically refresh any browsers you have open. As your JupyterLite is mostly comprised of static assets, changes will not trigger a refresh by default.
Enabling the -a
flag will allow reloading when static assets change, but at the
price rebuild the whole site when any file changes… this can be improved with the
-j<N>
flag, but is not compatible with all sphinx extensions.
sphinx-autobuild docs docs/_build -aj8
NodeJS#
Most nodejs-based servers will be able to host JupyterLite without any problems. Note,
however, that http-server
does not support the application/wasm
MIME type.
On-Premises#
nginx#
TBD
httpd#
TBD
IIS#
TBD
Hosted#
Binder#
A JupyterLite can be deployed behind jupyter-server-proxy
using any
local server method. This is a good way to preview deployment interactively of
a e.g. Lab extension that can work in both the “full” binder experience, and as a static
preview.
Hint
See the JupyterLite binder configuration for an example.
ReadTheDocs#
The Sphinx deployment approach will work almost transparently with
ReadTheDocs, for the small price of a .readthedocs.yml
file
in the root of your repository.
Hint
See the JupyterLite .readthedocs.yml for an example.
Hint
You might also want to enable the Autobuild Documentation for Pull Requests feature of Read The Docs to automatically get a preview link when opening a new pull request:
Netlify#
Netlify makes it easy and convenient to host static websites from existing git repositories, and make them widely available via their CDN.
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 --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).
Unfortunately, their build image only includes Python 3.6 and JupyterLite requires Python 3.7+.
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.1.0
jupyterlite
Then create a new deploy.sh
file with the following content:
#!/bin/bash
yum install wget
wget -qO- https://micromamba.snakepit.net/api/micromamba/linux-64/latest | tar -xvj bin/micromamba
./bin/micromamba shell init -s bash -p ~/micromamba
source ~/.bashrc
# activate the environment and install a new version of Python
micromamba activate
micromamba install python=3.9 -c conda-forge -y
# install the dependencies
python -m pip install -r requirements-deploy.txt
# build the JupyterLite site
jupyter lite --version
jupyter lite build --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 on Vercel:
You might also want to specify the --debug
flag to get extra log messages:
jupyter lite build --debug
GitHub Pages#
JupyterLite can easily be deployed on GitHub Pages, using the jupyterlite
CLI to add
content and extensions.
Hint
See the JupyterLite Demo for an example. That repository is a GitHub template repository which makes it convenient to generate a new JupyterLite site with a single click.
GitLab Pages#
JupyterLite can easily be deployed on GitLab Pages, using the jupyterlite
CLI and
setting the output_path
to the public
folder in your .gitlab-ci.yml
file.
Suppose that your notebooks are stored in the content
folder; and you don’t require
any additional python dependencies and configuration overrides, the .gitlab-ci.yml
could look like.
image: python
pages:
stage: deploy
before_script:
- python -m pip install jupyterlite
script:
- jupyter lite build --contents content --output-dir public
artifacts:
paths:
- public # mandatory, other folder won't work
only:
- main # the branch you want to publish
Hint
See the gitlab pages template for a more involved example.
Heroku#
TBD