crosscompass/ihaskell-notebook repository overview

⁠ihaskell-notebook

A Community Jupyter Docker Stacks⁠ image. Provides the Jupyter IHaskell⁠ kernel in a Docker image which composes well with other Jupyter Docker Stacks. Images are published at DockerHub crosscompass/ihaskell-notebook⁠.

docker run the latest image right now with the following shell command, then open http://localhost:8888⁠ to try out the Jupyter notebook. Your current working directory on your host computer will be mounted at Home / pwd in JupyterLab.

docker run --rm -p 8888:8888 -v $PWD:/home/jovyan/pwd --name ihaskell_notebook crosscompass/ihaskell-notebook:latest jupyter lab --LabApp.token=''

Or with podman:

podman run --privileged --userns=keep-id --rm -p 8888:8888 -v $PWD:/home/jovyan/pwd --name ihaskell_notebook crosscompass/ihaskell-notebook:latest jupyter lab --LabApp.token=''

This image includes:

• JupyterLab 2⁠
• IHaskell⁠ Jupyter kernel
• Haskell libraries for instances of IHaskell.Display⁠
  • ihaskell-aeson for Aeson⁠ JSON display
  • ihaskell-blaze for Blaze⁠ HTML display
  • ihaskell-gnuplot for gnuplot⁠ display
  • ihaskell-juicypixels for JuicyPixels⁠ image display
  • ihaskell-graphviz for Graphviz⁠ display
  • ihaskell-diagrams for diagrams⁠ display
  • ihaskell-charts for Chart⁠ display
  • ihaskell-hatex for HaTeX⁠ LaTeX display
  • DougBurke/ihaskell-hvega⁠ for Vega/Vega-Lite rendering, natively supported by JupyterLab⁠
• Haskell Stack⁠ package manager, with Glasgow Haskell Compiler⁠.

To ensure that this image composes well with any authentication and storage configuration (for example SystemUserSpawner⁠) or notebook directory structure, we try to avoid installing anything in the Docker image in /home/jovyan.

This image is made with JupyterLab in mind, but it works well for classic notebooks.

Example notebooks are collected together in the container at /home/jovyan/ihaskell_examples.

⁠IHaskell.Display

Some libraries for instances of IHaskell.Display⁠ are pre-installed in the JupyterLab container.

The installed libraries mostly come from mostly from IHaskell/ihaskell-display⁠, and are installed if they appeared to be working at the time the JupyterLab Docker image was built. You can try to install the other IHaskell/ihaskell-display libraries, and they will be built from the /opt/IHaskell source in the container.

stack install ihaskell-magic

See the Stack global project /opt/stack/global-project/stack.yaml for information about the /opt/IHaskell source in the container.

You can see which libraries are installed by running ghc-pkg:

stack exec ghc-pkg -- list | grep ihaskell
    ihaskell-0.9.1.0
    ihaskell-aeson-0.3.0.1
    ihaskell-blaze-0.3.0.1
    ihaskell-gnuplot-0.1.0.1
    ihaskell-hvega-0.2.0.0
    ihaskell-juicypixels-1.1.0.1
    ...

⁠Stack global project

The ihaskell executable, the ihaskell library, the ghc-parser library, and the ipython-kernel library are built and installed at the level of the Stack global project⁠ in /opt/stack/global-project. This design choice was discussed in IHaskell issue #715⁠.

This means that the ihaskell environment is available for all users in any directory mounted in the Docker container, so you can save and run .ipynb notebook files in any directory, which is one of the main advantage of this IHaskell Docker image. The present working directory (PWD) of a Jupyter notebook is the always the directory in which the notebook is saved.

The Stack global project resolver is determined by the IHaskell project resolver, and all included Haskell libraries are built using that Stack resolver.

You can install libraries with stack install. For example, if you encounter a notebook error like:

<interactive>:1:1: error:
   Could not find module ‘Numeric.LinearAlgebra’
   Use -v to see a list of the files searched for.

Then you can install the missing package from the terminal in your container:

stack install hmatrix

Or, in a notebook, you can use the GHCi-style shell commands⁠:

:!stack install hmatrix

And then ⭮ restart your IHaskell kernel.

You can use this technique to create a list of package dependencies at the top of a notebook:

:!stack install hmatrix
import Numeric.LinearAlgebra
ident 3

(3><3)
 [ 1.0, 0.0, 0.0
 , 0.0, 1.0, 0.0
 , 0.0, 0.0, 1.0 ]

Sadly, this doesn't work quite as frictionlessly as we would like. The first time you run the notebook, the packages will be installed, but then the kernel not load them. You must ⭮ restart the kernel to load the newly-installed packages.

⁠Local Stack Projects

You can run a IHaskell .ipynb in a Stack project PWD which has a stack.yaml.

You should copy the entire contents of the container's Stack global project /opt/stack/global-project/stack.yaml into the local project's stack.yaml as a starting point. That will give you the same resolver as the global project IHaskell installation, and it will also allow you to install libraries from IHaskell and IHaskell/ihaskell-display. You can add extra-deps to your local project stack.yaml for packages which are not in the Stack resolver.

You probably shouldn't run a IHaskell .ipynb in a PWD with a stack.yaml that has a resolver different from the resolver in /opt/stack/global-project/stack.yaml.

After your stack.yaml is configured, run :! stack build and then ⭮ restart your IHaskell kernel.

⁠System GHC

The GHC version specified by the IHaskell Stack resolver is also installed in the container at the system level, that is, on the executable PATH.

⁠Building the Dockerfile locally

make build

⁠Composition with Docker Stacks

Rebase the IHaskell Dockerfile on top of another Jupyter Docker Stack image, for example the scipy-notebook:

docker build --build-arg BASE_CONTAINER=jupyter/scipy-notebook --rm --force-rm -t ihaskell_scipy_notebook:latest .

⁠References, Links, Credits

IHaskell on Hackage⁠

IHaskell on Stackage⁠

IHaskell Wiki with Exemplary IHaskell Notebooks⁠

When Is Haskell More Useful Than R Or Python In Data Science?⁠ by Tikhon Jelvis⁠

datahaskell.org⁠

Learn You a Haskell for Great Good, Jupyter adaptation⁠

This Docker image was made at Cross Compass⁠ in Tokyo.