nomad-north-jupyter 0.2.2

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

NORTH Jupyter tool

nomad-north-jupyter is a NOMAD plugin and can be used along with other NOMAD plugins, in nomad-distro-dev, nomad-distro-template, and in NOMAD production instance. Adding it as a plugin will make the jupyter_north_tool available in the NORTH tools registry of the NOMAD Oasis environment.

The plugin contains the NORTH tool configuration and a Docker image for a Jupyter-based tool in the NOMAD NORTH (NOMAD Oasis Remote Tools Hub) environment. 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.

Quick start

The jupyter_north_tool, a NORTH tool instance provided by this plugin, offers a containerized JupyterLab environment for interactive analysis.

In the following sections, we will cover:

1. Building and testing the Docker image locally
2. Using nomad-north-jupyter as a base image for custom NORTH tools
   • Package management
   • Port and user configuration
   • Fixing permissions
3. 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
4. Adding nomad-north-jupyter image in a NOMAD Oasis (not recommended)
5. Documentation
6. Main contributors

Building and testing

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

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}"

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

The plugin nomad-north-jupyter is a default member of the plugin group in NOMAD Oasis. This facilitates NOMAD to autonomously discover and integrate the NORTHTool via NorthToolEntryPoint defined in the plugin. Later, the tool will be available in the NORTH tools registry of the NOMAD Oasis environment.

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

We now 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 NORTHToolEntryPoint instances (e.g., north_tool_entry_point) 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.

Publish note

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.

Reconfigure existing NORTH tool entry point

The image shipped with nomad-north-jupyter is a generic 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:north_tool_entry_point:
        north_tool:
          image: ghcr.io/fairmat-nfdi/nomad-north-jupyter:<another_tag>
          display_name: "renamed jupyter tool"

Adding nomad-north-jupyter image in a NOMAD 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

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]