Metadata-Version: 2.4
Name: nomad-north-jupyter
Version: 0.2.1
Summary: An example for Jupyter NORTH tool (Jupyter docker image).
Author-email: NOMAD Authors <fairmat@physik.hu-berlin.de>
Maintainer-email: NOMAD Authors <fairmat@physik.hu-berlin.de>
License: 
        The MIT License (MIT)
        
        Copyright (c) 2026 NOMAD Authors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
        THE SOFTWARE.
        
Project-URL: Repository, https://github.com/fairmat-nfdi/nomad-north-jupyter
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: nomad-lab>=1.4.1
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: structlog; extra == "dev"
Requires-Dist: mkdocs; extra == "dev"
Requires-Dist: mkdocs-material==8.1.1; extra == "dev"
Requires-Dist: pymdown-extensions; extra == "dev"
Requires-Dist: mkdocs-click; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Dynamic: license-file

# `NORTH` Jupyter tool

`nomad-north-jupyter` is a NOMAD plugin and can be used along with other NOMAD plugins, in [nomad-distro-dev](https://github.com/FAIRmat-NFDI/nomad-distro-dev), [nomad-distro-template](https://github.com/FAIRmat-NFDI/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](https://github.com/FAIRmat-NFDI/nomad-north-jupyter/pkgs/container/nomad-north-jupyter) from this plugin provides the default base image for [Dockerfile](https://github.com/FAIRmat-NFDI/cookiecutter-nomad-plugin/blob/main/%7B%7Bcookiecutter.plugin_name%7D%7D/py_sources/src/north_tools/%7B%7Bcookiecutter.north_tool_name%7D%7D/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](#building-and-testing)
1. [Using `nomad-north-jupyter` as a base image for custom `NORTH` tools](#using-nomad-north-jupyter-as-a-base-image-for-custom-north-tools)
   - [Package management](#package-management)
   - [Port and user configuration](#port-and-user-configuration)
   - [Fixing permissions](#fixing-permissions)
1. [Adding the `nomad-north-jupyter` plugin to NOMAD](#adding-the-nomad-north-jupyter-plugin-to-nomad)
   - [Adding the `nomad-north-jupyter` plugin in your NOMAD Oasis](#adding-the-nomad-north-jupyter-plugin-in-your-nomad-oasis)
   - [Adding `nomad-north-jupyter` plugin in your local NOMAD installation](#adding-nomad-north-jupyter-plugin-in-your-local-nomad-installation)
   - [Reconfigure existing `NORTH` tool entry point](#reconfigure-existing-north-tool-entry-point)
1. [Adding `nomad-north-jupyter` image in a NOMAD Oasis (not recommended)](#adding-nomad-north-jupyter-image-in-a-nomad-oasis-not-recommended)
1. [Documentation](#documentation)
1. [Main contributors](#main-contributors)

## Building and testing

Build the Docker image locally:

```bash
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:

```bash
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](https://github.com/FAIRmat-NFDI/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:**
```dockerfile
RUN uv pip install numpy pandas scipy
```

**Example using pip:**
```dockerfile
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:

```dockerfile
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`](https://github.com/FAIRmat-NFDI/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.

### 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`](https://nomad-lab.eu/prod/v1/docs/reference/config.html#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](https://nomad-lab.eu/prod/v1/docs/reference/config.html#merging-rules) 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:

```yaml
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](https://github.com/FAIRmat-NFDI/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](https://nomad-lab.eu/prod/v1/docs/reference/config.html)):

```yaml
# 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: fairmat@physik.hu-berlin.de
            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](https://fairmat-nfdi.github.io/nomad-docs/howto/plugins/types/north_tools.html).

> [!NOTE]
> This NOMAD plugin was generated with [`Cookiecutter`](https://www.cookiecutter.io/) along with `@nomad`'s [`cookiecutter-nomad-plugin`](https://github.com/FAIRmat-NFDI/cookiecutter-nomad-plugin) template.

## Main contributors

| Name          | E-mail                                                            |
| ------------- | ----------------------------------------------------------------- |
| NOMAD Authors | [fairmat@physik.hu-berlin.de](mailto:fairmat@physik.hu-berlin.de)
