Installing the mosaik-docker JupyterLab extension

Requirements

You will need Python (tested with version >= 3.6) and NodeJS to install the extension. For the extension to work properly, you will also need a working installation of Docker Engine.

Installation (standalone)

The package is available via the official Python Package Index. Install it from the command line:

pip install mosaik-docker-jl
jupyter lab build

Installation (JupyterHub)

JupyterHub distributions (e.g., The Littlest JupyterHub) already come with NodeJS installed. However, Docker Engine still needs to be installed from the JupyterHub administrator terminal using the sudo -E. From there, also the extension needs to be installed:

sudo -E pip install mosaik-docker-jl
sudo -E jupyter lab build

Each new JupyterHub user also has to be explicitly added to the group docker:

tljh-config add-item users.extra_user_groups.docker <user-name>

Troubleshoot

If you are seeing the frontend extension but it is not working, check that the server extension is enabled:

jupyter serverextension list

If the server extension is installed and enabled but you are not seeing the frontend, check the frontend is installed:

jupyter labextension list

If it is installed, try:

jupyter lab clean
jupyter lab build

In case you get error messages similar to the following one:

Check if the user has been added to group docker.

Development

Install

The jlpm command is JupyterLab’s pinned version of yarn that is installed with JupyterLab. You may use yarn or npm in lieu of jlpm below.

# Clone the repo to your local environment
git clone https://github.com/ERIGrid2/mosaik-docker-jl.git
cd mosaik-docker-jl

# Install server extension
pip install -e .
# Register server extension
jupyter serverextension enable --py mosaik_docker_jl

# Install dependencies
jlpm
# Build Typescript source
jlpm build
# Link your development version of the extension with JupyterLab
jupyter labextension link .
# Rebuild Typescript source after making changes
jlpm build
# Rebuild JupyterLab after making any changes
jupyter lab build

You can watch the source directory and run JupyterLab in watch mode to watch for changes in the extension’s source and automatically rebuild the extension and application.

# Watch the source directory in another terminal tab
jlpm watch
# Run jupyterlab in watch mode in one terminal tab
jupyter lab --watch

Uninstall

pip uninstall mosaik-docker-jl
jupyter labextension uninstall mosaik-docker-jl
    jupyter lab build