An OCI Jupyter Lab image for statistical analysis with Common Lisp
Example analysis »
Report Bug
·
Request Feature
This repository contains the source for an OCI (devcontainer/docker) image of a Jupyter notebook for statistical analysis.
A prebuilt version of this image can be found at:
ghcr.io/lisp-stat/cl-jupyter
This is the image URL you will use in a devcontainer.json or Docker file.
To run the image you need tooling to run OCI images. These include:
- Docker - Most popular container platform
- Podman - Daemonless, rootless alternative to Docker
- containerd - Industry-standard container runtime
- Lima - Linux VMs on macOS with container support
- Rancher Desktop - Desktop container management
- Colima - Container runtimes on macOS with minimal setup
- VS Code Dev Containers - Development environments in containers
- GitHub Codespaces - Cloud-based
This image is based on a Jupyter Docker Stacks and you can find full documentation on running a jupyter docker stack there. Be certain to use the right image.
docker run -it -p 8888:8888 ghcr.io/lisp-stat/cl-jupyter
# Entered start.sh with args: jupyter lab
# ...
# To access the server, open this file in a browser:
# file:///home/jovyan/.local/share/jupyter/runtime/jpserver-7-open.html
# Or copy and paste one of these URLs:
# http://eca4aa01751c:8888/lab?token=d4ac9278f5f5388e88097a3a8ebbe9401be206cfa0b83099
# http://127.0.0.1:8888/lab?token=d4ac9278f5f5388e88097a3a8ebbe9401be206cfa0b83099
Pressing Ctrl-C twice shuts down the Server but leaves the container intact on disk for later restart or permanent deletion. At the time of this writing (July 2025) the upstream (Jupyter Docker Stacks) images are migrating to Notebook 7 format and you may see warnings. They can be ignored.
A devcontainer.json file for working with CL-Jupyter looks like this:
{
"name": "IPS9",
"image": "ghcr.io/lisp-stat/cl-jupyter",
// Use base images default CMD.
"overrideCommand": false,
// Forward Jupyter port locally, mark required.
"forwardPorts": [8888],
"portsAttributes": {
"8888": {
"label": "Jupyter",
"requireLocalPort": true,
"onAutoForward": "ignore"
}
},
// Configure tool-specific properties.
"customizations": {
// Configure properties specific to VS Code.
"vscode": {
// Set *default* container specific settings.json values on container create.
"settings": {
"python.defaultInterpreterPath": "/opt/conda/bin/python"
},
// Add the IDs of extensions you want installed when the container is created.
"extensions": ["ms-python.python", "ms-toolsai.jupyter"]
}
}
}
To see an example in a production environment (modified from the above for some real-world constraints) see the IPS9 worked examples repository.
To run the image from this respository on Github code spaces you must also build it (otherwise there would be a circular reference, the repository can't both provide the source of the image and use the image). The examples above used the prebuilt image at ghcr.io/lisp-stat/cl-jupyter
and therefore load quickly. If you want to use a cloud based notebook rather than build one, modify your devcontainer.json file to use the image (instead of the individual features that comprise the image) and follow the instructions below. See the examples of Introduction to the Practice of Statistics or the devcontainer example above for working examples of using (rather than building) this image for cloud use.
Building the base image will take some time, so be patient.
Click on the 'Code' button, as if you were going to clone the repo:

and select "Codespaces"

from the Dropdown menu, select ‘Open in Codespaces’. This will open the code in a cloud-based development environment.

Wait for the code space to load. This may take some time. Be sure to wait until the process is complete. When it is finished, you will have a remote VS Code window. If you like you can work with Jupyter notebooks from within, or you can launch Jupyter Lab to edit. To use Jupyter lab, close the VS Code tab and go back to the repository page you were using above. Now refresh the page (just to be sure) and click on the code -> codespaces button again. This time you'll see your active codespaces and be able to select the editor by clicking on the three dots next to the codespace name:

From the Dropdown menu, select ‘Open in JupyterLab’ to start working an analysis in your the JupyterLab environment.

You will briefly see a 'setting up' screen.

And then the Jupyter Lab will open.

To build this image you will need to use the devcontainer cli. Note that this image uses devcontainer features, and therefore cannot be built using standard OCI tools. See pre-building dev container images for more information.
The commands to build this image are:
cd <this directory>
devcontainer build --workspace-folder . --image-name my-cl-jupyter:latest
This builds a local image my-cl-jupyter:latest
you can use. You'll want to replace the --image-name
parameter with your own to avoid confusion.
If you want to tag and push your custom image to a registry for others to use:
docker tag my-cl-jupyter:latest ghcr.io/username/cl-jupyter:latest
docker push ghcr.io/username/cl-jupyter:latest
Or build and push directly to a registry:
devcontainer build --workspace-folder . --image-name ghcr.io/username/cl-jupyter:latest --push
See the open issues for a list of proposed features (and known issues). We will include additional examples in the chapter order of the book
This system is part of the Lisp-Stat project; that should be your first stop for information. Also see the
community page for more information.
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated. Please see CONTRIBUTING for details on the code of conduct, and the process for submitting pull requests.
Distributed under the MS-PL License. See LICENSE for more information.
Project Link: https://github.com/lisp-stat/cl-jupyter-image