Deploying your JupyterLite requires:
- an actual HTTP server (doesn't presently work with
file://URLs)
Serving some of the [kernels](./kernels/index.md) requires that your web server supports
serving `application/wasm` files with the correct headers
An HTTPS-capable server is recommended for all but the simplest `localhost` cases.
The minimum deployable site contains enough to run JupyterLab and RetroLab, but no content.
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 jupyterliteTo build an empty site (just the JupyterLite static assets):
jupyter lite init- 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/builderfromnpmjs.com
It is recommended to put these files under revision control. See [Configuring](./configuring.md)
for what you can configure in your JupyterLite.
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.
TBD
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
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.
See the JupyterLite [conf.py] for an example approach, though it's likely a good
deal more complicated than you will need, because it needs to build _itself_ first!
This complexity is managed in [dodo.py].
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 vistors to /, which
will immediately redirect to appUrl as defined in the schema.
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.
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.
The http module in the Python standard library is a suitably-effective server for
local purposes.
python -m http.server -b 127.0.0.1If you are using a recently-released Python 3.7+, this will correctly serve
application/wasm files for pyodide.
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/_buildThis 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 -aj8Most 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.
TBD
TBD
TBD
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.
See the JupyterLite [binder configuration] for an example.
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.
See the JupyterLite [.readthedocs.yml] for an example.
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 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:
TBD
JupyterLite can easily be deployed on GitHub Pages, using the jupyterlite CLI to add
content and extensions.
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.
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
See the [gitlab pages template] for a more involved example.
TBD