nomad-north-jupyter 0.2.4

An example for Jupyter NORTH tool (Jupyter docker image).

NORTH Jupyter tool

nomad-north-jupyter is a NOMAD plugin that provides an entry point for using a JupyterLab environment in NORTH (NOMAD Remote Tools Hub).

Quickstart

This plugin is available in PyPI under the name nomad-north-jupyter. To install this plugin into a NOMAD Oasis, add the following to your pyproject.toml:

[project.optional-dependencies]
plugins = [
  "nomad-north-jupyter",
  ...
]

By adding this plugin, the jupyter NORTH tool will become available in the NORTH tools registry of the NOMAD Oasis.

By default this plugin is configured to use a generic Jupyter environment, but you can build your own custom image for your Oasis and switch to it using the nomad.yaml configuration file:

plugins:
  entry_points:
    options:
      nomad_north_jupyter.north_tools.jupyter:
        north_tool:
          image: <your-docker-image-path>

Plugin overview

The jupyter NORTH tool instance provided by this plugin, offers a containerized JupyterLab environment for interactive analysis. The plugin contains the NORTH tool configuration and the nomad-north-jupyter image for a Jupyter-based tool in the NORTH (NOMAD Oasis Remote Tools Hub) environment.

In the following sections, we will cover:**

1. Adding the nomad-north-jupyter plugin to NOMAD

   • Adding the nomad-north-jupyter plugin in your NOMAD Oasis
   • Adding nomad-north-jupyter plugin in your local NOMAD installation
   • Reconfigure existing NORTH tool entry point

2. A note on publishing

3. Adding nomad-north-jupyter image directly in a NOMAD Oasis (not recommended)

4. Using nomad-north-jupyter as a base image for custom NORTH tools

   • Package management
   • Port and user configuration
   • Fixing permissions

5. Building and testing the Docker image locally

6. Documentation

7. Main contributors

Adding the nomad-north-jupyter plugin to NOMAD

Currently, NOMAD has two distinct flavors (NOMAD Oasis and NOMAD development environment) that are relevant depending on your role as an user.

Adding the nomad-north-jupyter plugin in your NOMAD Oasis

If you work with the nomad-distro-template, the nomad-north-jupyter plugin is installed by default. This facilitates NOMAD to autonomously discover and integrate the NORTHTool via NorthToolEntryPoint defined in the plugin. The tool will automatically be available in the NORTH tools registry of the NOMAD Oasis environment. Learn more about how this plugin is integrated in the nomad-distro-template documentation.

Adding nomad-north-jupyter plugin in your local NOMAD installation

We recommend using the dedicated nomad-distro-dev to facilitate NOMAD plugin development. To add nomad-north-jupyter to your local development environment, add it as a dependency in pyproject.toml. NOMAD will automatically discover the NORTHToolEntryPoint instance jupyter defined in nomad-north-jupyter. To replace or modify the NORTH tool configuration (for instance, changing the image or image version), you can adjust the entry point configuration in your nomad.yaml file.

Reconfigure existing NORTH tool entry point

As outlined above, the image shipped with nomad-north-jupyter by default is a generic slim Jupyter container that may be too simplistic for your use case. In that case, you can change to a different image to use in the container. A NORTHTool entry point can be reconfigured via the nomad.yaml configuration file of your NOMAD Oasis instance (you can learn more about this reconfiguration and the merge strategy in the NOMAD docs). Hence, if you have the nomad-north-jupyter plugin installed, you can do so by adjusting the entry point configuration in your nomad.yaml file:

plugins:
  entry_points:
    options:
      nomad_north_jupyter.north_tools:jupyter:
        north_tool:
          image: ghcr.io/fairmat-nfdi/nomad-north-jupyter:<another_tag>
          display_name: "renamed jupyter tool"

A note on publishing

In our Python package publishing workflow, before building the package, we update the image tag in the NORTHTool entry point to the latest release version of the image (e.g., v0.1.5), and then publish the package to PyPI.

However, the updated image tag in NORTHTool is not pushed back to the GitHub repository. Therefore, the image tag in the GitHub repository always remains set to main, even when you check out a specific release tag. For this reason, we recommend installing the plugin from PyPI, where the entry point always contains the correct image tag corresponding to the release.

If you download a ZIP file of a specific release from GitHub, the image tag in the entry point will still be set to main, which is not correct. In that case, you can either manually update the image tag in the entry point to the correct release version (e.g., v0.1.5), or install the plugin directly from PyPI.

Adding nomad-north-jupyter image directly in an Oasis (not recommended)

[!WARNING] We strongly recommend integrating nomad-north-jupyter into NOMAD as a plugin. The following approach is only recommended if you have an existing NOMAD Oasis instance that you do not want to rebuild, but still want to add the Jupyter image to the running NORTH service.

If you cannot use the plugin approach, you can add the nomad-north-jupyter image to your NORTH service by editing the nomad.yaml file in a nomad-distro-template instance. Define the corresponding NORTH tool in nomad.yaml as shown below (see the full NORTH tool configuration in the NOMAD documentation):

# Not a recommended way
north:
  jupyterhub_crypt_key: "978bfb2e13a8448a253c629d8dd84ffsd587f30e635b753153960930cad9d36d"
  tools:
    options:
      jupyter:
        image: ghcr.io/fairmat-nfdi/nomad-north-jupyter:latest
        description: "### **Jupyter Notebook**: The Classic Notebook Interface"
        file_extensions:
          - ipynb
        icon: jupyter_logo.svg
        image_pull_policy: Always
        maintainer:
          - email: [e-mail]
            name: NOMAD Authors
        mount_path: /home/jovyan
        path_prefix: lab/tree
        privileged: false
        short_description: ""
        with_path: true

Building and testing the Docker image locally

Build the Docker image locally:

docker build -f src/nomad_north_jupyter/north_tools/jupyter_north_tool/Dockerfile \
    -t ghcr.io/fairmat-nfdi/nomad-north-jupyter:latest .

Test the image:

docker run -p 8888:8888 ghcr.io/fairmat-nfdi/nomad-north-jupyter:latest

Access JupyterLab at http://localhost:8888.

Using nomad-north-jupyter as a base image for custom NORTH tools

The nomad-north-jupyter image from this plugin provides the default base image for Dockerfile which is used as a basis to define custom Jupyter NORTH tools.

This image is designed to be used as a base for custom NOMAD NORTH Jupyter tools. When extending this image in your plugin's Dockerfile created from cookiecutter-nomad-plugin, keep the following in mind:

Package management

Both uv and pip are available as package managers in the image. Both install and uninstall packages in the Conda environment, so you can use either one of them to manage your Python dependencies.

Example using uv:

RUN uv pip install numpy pandas scipy

Example using pip:

RUN pip install --no-cache-dir matplotlib seaborn

Port and user configuration

Like other Jupyter notebook images, port 8888 is exposed for JupyterLab access. The default user is ${NB_USER} (usually jovyan), and you should switch to this user when installing packages or copying files to ensure proper permissions.

Fixing permissions

After customizing the base image (e.g., installing additional packages or adding files), you may need to fix file permissions to avoid permission issues when running the container. Add the following lines at the end of your Dockerfile after all customizations:

COPY --chown=${NB_USER}:${NB_GID} . ${HOME}/${PLUGIN_NAME}
RUN fix-permissions "/home/${NB_USER}" \
    && fix-permissions "${CONDA_DIR}"

Documentation

For comprehensive documentation on creating and managing NORTH tools, including detailed information on topics such as:

• Entry point configuration and NORTHTool API
• Docker image structure and best practices
• Dependency management

See the NOMAD NORTH Tools documentation.

[!NOTE] This NOMAD plugin was generated with Cookiecutter along with @nomad's cookiecutter-nomad-plugin template.

Main contributors

Name	E-mail
NOMAD Authors	[e-mail]