### Install GUI Dependencies and Start Server

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/develop/setup.md

Navigate to the `gui` directory, install Node.js dependencies using Yarn, and start the GUI development server.

```shell
cd gui
yarn
yarn start
```

--------------------------------

### Start NOMAD Services Separately

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/oasis/configure.md

For initial setup and debugging, it's recommended to start core services like MongoDB, Elasticsearch, and RabbitMQ first, followed by the app and worker.

```sh
docker compose up -d mongo elastic rabbitmq
docker compose up app worker gui
```

--------------------------------

### Install NOMAD Development Environment

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/develop/setup.md

Run this script to set up the development environment for NOMAD. It handles initial setup and dependency installation.

```shell
./scripts/setup_dev_env.sh
```

--------------------------------

### Parser Load Method Example

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/plugins/types/parsers.md

Demonstrates how the `load` method returns a parser instance, passing entry configuration options like `mainfile_name_re` to the `MatchingParser` constructor for file matching setup.

```python
    def load(self):
        from nomad_example.parsers.myparser import MyParser

        return MyParser(**self.dict())
```

--------------------------------

### Configure Example Upload Entry Point in pyproject.toml

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/plugins/types/example_uploads.md

Add the example upload entry point to the `[project.entry-points.'nomad.plugin']` table in your `pyproject.toml` file. This configuration allows NOMAD to automatically discover and load your example upload.

```toml
[project.entry-points.'nomad.plugin']
myexampleupload = "nomad_example.example_uploads:myexampleupload"
```

--------------------------------

### Run Local Docs Server

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/README.md

Starts the MkDocs local development server using 'uv'. This command installs all necessary requirements in a virtual environment before serving the docs.

```bash
uv run mkdocs serve
```

--------------------------------

### Base Configuration Example

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/reference/config.md

Example of a base configuration file defining plugin entry points.

```yaml
# In the base nomad.yaml
plugins:
  entry_points:
    include:
      - "systemnormalizer:system_normalizer_entry_point"
      - "atomisticparsers:amber_parser_entry_point"
```

--------------------------------

### Install NOMAD Oasis with Multiple Values Files

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/oasis/deploy.md

Use multiple `-f` flags to layer configuration files, allowing later files to override earlier ones. This example shows installing NOMAD Oasis with a base configuration and custom overrides.

```sh
helm install nomad-oasis nomad/default \
  -f kubernetes/values.yaml \
  -f my-overrides.yaml \
  --timeout 15m
```

--------------------------------

### Example Scopes

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/explanation/auth.md

Illustrates concrete examples of authorization scopes, showing how to specify read and write permissions for resources like uploads.

```text
uploads:read
uploads:write
```

--------------------------------

### Dockerfile System Setup and Dependencies

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/plugins/types/north_tools.md

Configures the shell environment, copies the uv package manager, and installs essential system dependencies for the NORTH tool image. It also sets environment variables for user and conda directory.

```Dockerfile
# https://github.com/hadolint/hadolint/wiki/DL4006
# https://github.com/koalaman/shellcheck/wiki/SC3014
SHELL ["/bin/bash", "-o", "pipefail", "-c"]

COPY --from=uv_stage /uv /uvx /bin/

USER root

# Define environment variables
# With pre-existing NB_USER="jovyan" and NB_UID=100, NB_GID=1000
ENV HOME=/home/${NB_USER}
ENV CONDA_DIR=/opt/conda

# Make ARG variables available as environment variables
ARG PLUGIN_NAME

RUN apt-get update \
 && apt-get install --yes --quiet --no-install-recommends \
      libmagic1 \
      file \
      build-essential \
      curl \
      zip \
      unzip \
      git

# By default scipy-notebook:2025-10-20 has node 18

```

--------------------------------

### Install Default Plugins

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/develop/setup.md

Installs default plugins using a requirements file. This step is for managing plugin distributions.

```shell
uv pip install -r requirements-plugins.txt
```

--------------------------------

### Install uv with pip

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/README.md

Installs the 'uv' package manager using pip. This is an alternative installation method.

```bash
pip install uv
```

--------------------------------

### Include Local Files and Folders in Example Uploads

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/plugins/types/example_uploads.md

Specify file or folder names relative to the plugin package installation location to include them in the upload. Use '*' to include folder contents recursively. `UploadResource` can target specific locations within the upload. Multiple resources can be provided as a list.

```python
resources = 'example_uploads/getting_started/README.md'
```

```python
resources = 'example_uploads/getting_started'
```

```python
resources = 'example_uploads/getting_started/*'
```

```python
resources = UploadResource(
    path='example_uploads/getting_started',
    target='upload_subfolder'
)
```

```python
resources = [
    'example_uploads/getting_started/README.md',
    'example_uploads/getting_started/data.txt'
]
```

--------------------------------

### Add Function Docstring Example

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/reference/code_guidelines.md

Example of a multi-line Google-style docstring for a Python function. Includes Args and Returns sections. Start multi-line docstrings on a new line.

```python
def add(a: float, b: float) -> float:
    '''
    Adds two numbers.

    Args:
      a (float): One number.
      b (float): The other number.

    Returns:
      float: The sum of a and b.
    '''

    return a + b
```

--------------------------------

### Download Example CSV using curl

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/tutorial/develop_plugin.md

Use this command to download the example CSV recipe file for the sintering process. Save it in your working directory.

```bash
curl -L -o tests/data/sintering_example.csv "https://raw.githubusercontent.com/FAIRmat-NFDI/AreaA-Examples/main/tutorial13/part3/files/sintering_example.csv"
```

--------------------------------

### Install Jupyter and Required Tools

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/tutorial/upload_publish_api.md

Upgrade pip and install JupyterLab and ipykernel within your activated virtual environment.

```bash
pip install --upgrade pip
pip install jupyterlab ipykernel
```

--------------------------------

### Install Docker on Ubuntu

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/oasis/deploy.md

Use this script to install Docker and Docker Compose on Ubuntu systems. Ensure you have the necessary permissions to execute shell scripts.

```bash
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
```

--------------------------------

### Define Example Upload Entry Point in Python

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/plugins/types/example_uploads.md

Define an instance of `ExampleUploadEntryPoint` or its subclass in `*/example_uploads/__init__.py`. This instance specifies the title, category, description, and resources for your example upload. The `resources` field points to the data files included in the Python package.

```python
from nomad.config.models.plugins import ExampleUploadEntryPoint

myexampleupload = ExampleUploadEntryPoint(
    title = 'My Example Upload',
    category = 'Examples',
    description = 'Description of this example upload.',
    resources=['example_uploads/getting_started/*']
)
```

--------------------------------

### MD Setup Workflow YAML

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/manage/gui/workflows.md

Constructs the main workflow YAML file, defining inputs, outputs, and tasks for an MD setup simulation.

```yaml
"workflow2":
  "name": "MD Setup workflow"
  "inputs":
  - "name": "workflow parameters"
      "section": "../upload/archive/mainfile/Custom_ELN_Entries/workflow_parameters.archive.yaml#/data"
  - "name": "workflow scripts"
      "section": "../upload/archive/mainfile/Custom_ELN_Entries/workflow_scripts.archive.yaml#/data/Files"
  "outputs":
  - "name": "structure file"
      "section": "../upload/archive/mainfile/Custom_ELN_Entries/insert_water.archive.yaml#/data/Files/0/file"
  - "name": "force field file"
      "section": "../upload/archive/mainfile/Custom_ELN_Entries/create_force_field.archive.yaml#/data/Files/0/file"
  "tasks":
  - "m_def": "nomad.datamodel.metainfo.workflow.TaskReference"
      "name": "create box"
      "task": "../upload/archive/mainfile/Custom_ELN_Entries/create_box.archive.yaml#/data"
      "inputs":
      - "name": "workflow parameters"
      "section": "../upload/archive/mainfile/Custom_ELN_Entries/workflow_parameters.archive.yaml#/data"
      - "name": "workflow script 1"
      "section": "../upload/archive/mainfile/Custom_ELN_Entries/workflow_scripts.archive.yaml#/data/Files/0/file"
      "outputs":
      - "name": "initial box"
      "section": "../upload/archive/mainfile/Custom_ELN_Entries/create_box.archive.yaml#/data/Files/0/file"
  - "m_def": "nomad.datamodel.metainfo.workflow.TaskReference"
      "name": "insert water"
      "task": "../upload/archive/mainfile/Custom_ELN_Entries/insert_water.archive.yaml#/data"
      "inputs":
      - "name": "initial box"
      "section": "../upload/archive/mainfile/Custom_ELN_Entries/create_box.archive.yaml#/data/Files/0/file"
      - "name": "workflow script 1"
      "section": "../upload/archive/mainfile/Custom_ELN_Entries/workflow_scripts.archive.yaml#/data/Files/0/file"
      "outputs":
      - "name": "structure file"
      "section": "../upload/archive/mainfile/Custom_ELN_Entries/insert_water.archive.yaml#/data/Files/0/file"
  - "m_def": "nomad.datamodel.metainfo.workflow.TaskReference"
      "name": "create force field"
      "task": "../upload/archive/mainfile/Custom_ELN_Entries/create_force_field.archive.yaml#/data"
      "inputs":
      - "name": "workflow parameters"

```

--------------------------------

### Configure uv and Install Python Dependencies

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/plugins/types/north_tools.md

Sets up uv environment variables for integration with conda and installs Python dependencies from the 'north' group. Copies plugin code and then removes it after installation. Builds JupyterLab and fixes permissions.

```docker
USER ${NB_USER}

# uv env
ENV UV_PROJECT_ENVIRONMENT=${CONDA_DIR} \
    UV_LINK_MODE=copy \
    UV_NO_CACHE=1 \
    # Use python from conda which is default for scipy-notebook
    # so that uv pip and pip both refer to the same python
    # If needed one can create another venv with 'uv venv'
    UV_SYSTEM_PYTHON=1

COPY --chown=${NB_USER}:${NB_GID} . ${HOME}/${PLUGIN_NAME}

WORKDIR ${HOME}/${PLUGIN_NAME}

# https://docs.astral.sh/uv/guides/integration/docker/#intermediate-layers
RUN --mount=type=cache,target=/root/.cache/uv \
    uv pip install . --group north

WORKDIR ${HOME}
RUN rm -rf ${HOME}/${PLUGIN_NAME}

RUN jupyter lab build --dev-build=False --minimize=False && \
    fix-permissions "/home/${NB_USER}" \
    && fix-permissions "${CONDA_DIR}"

WORKDIR ${HOME}

RUN touch ${HOME}/.hushlogin
```

--------------------------------

### Complete Schema Example

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/tutorial/eln/custom_eln_yaml.md

An example of a complete schema definition including sections and quantities.

```yaml
definitions:
  name: Processing of polymer thin-films
  sections:
    Experiment_Information:
      base_sections:
        - nomad.datamodel.data.EntryData
      quantities:
        Name:
          type: str
          default: Experiment title
        Researcher:
          type: str
          default: Name of the researcher who performed the experiment
        Date:
          type: Datetime
        Additional_Notes:
          type: str
```

--------------------------------

### Install Plugin from Git Repository

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/plugins/plugins.md

Installs a plugin directly from a publicly shared Git repository using pip.

```shell
pip install git+https://<repository_url>
```

--------------------------------

### Install metainfo-yaml2py

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/tutorial/develop_plugin.md

Install the necessary package for converting YAML schema files into Python classes.

```shell
pip install metainfoyaml2py
```

--------------------------------

### Install nomad-lab with Optional Dependencies

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/oasis/install.md

Install the `nomad-lab` Python package with additional feature sets using optional dependencies. Use `[infrastructure]` for running the NOMAD infrastructure or `[dev]` for development tools.

```bash
pip install nomad-lab[infrastructure]
```

```bash
pip install nomad-lab[dev]
```

--------------------------------

### Override Configuration Example

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/reference/config.md

Example of an override configuration file to modify plugin entry points. Note that lists are completely replaced.

```yaml
# In override.yaml
plugins:
  entry_points:
    include:
      - "atomisticparsers:amber_parser_entry_point"
```

--------------------------------

### Install Latest Stable nomad-lab from PyPI

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/oasis/install.md

Use this command to install the latest stable version of the `nomad-lab` Python package from PyPI.

```bash
pip install nomad-lab
```

--------------------------------

### Install Node.js and Configurable HTTP Proxy

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/plugins/types/north_tools.md

Installs Node.js version 24+ and the configurable-http-proxy package. Cleans up package manager cache afterwards to reduce image size.

```docker
# But, node > 20 needed for jupyterlab >= 4.4.10
RUN curl -fsSL https://deb.nodesource.com/setup_24.x | bash -

RUN apt-get install nodejs -y \
       && npm install -g configurable-http-proxy@^4.2.0 \
       # clean cache and logs
       && rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* ~/.npm
```

--------------------------------

### Complete ArchiveQuery Example

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/manage/program/archive_query.md

This example demonstrates the complete usage of the ArchiveQuery class. It utilizes the new workflow2 system, which is still under development and may not produce results on the public NOMAD data.

```python
--8 < -- "examples/archive/archive_query.py"
```

--------------------------------

### Install Development Version of nomad-lab from GitLab

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/oasis/install.md

Install a more recent development version of the `nomad-lab` Python package by using the FAIRmat-NFDI GitLab package registry.

```bash
pip install nomad-lab --extra-index-url https://gitlab.mpcdf.mpg.de/api/v4/projects/2187/packages/pypi/simple
```

--------------------------------

### Start Infrastructure and Run Backend Tests

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/develop/setup.md

Start the required infrastructure services (elastic, mongo, rabbitmq) using Docker Compose and then execute the backend tests with pytest. Avoid running workers to prevent task conflicts.

```shell
cd ops/docker-compose/infrastructure
docker compose up -d elastic mongo rabbitmq
cd ../../..
pytest -sv tests
```

--------------------------------

### Create Project Folder and Navigate

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/tutorial/upload_publish_api.md

Use these bash commands to create a new directory for your project and change into it.

```bash
mkdir nomad-api-tutorial
cd nomad-api-tutorial
```

--------------------------------

### Encrypt and Install with helm-secrets Plugin

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/oasis/deploy.md

Securely manage secrets by encrypting them using SOPS and the `helm-secrets` plugin. This example shows encrypting a `secrets.yaml` file and then installing with the encrypted version.

```bash
# Encrypt secrets with SOPS
sops -e secrets.yaml > secrets.enc.yaml

# Install with encrypted secrets
helm secrets install nomad-oasis nomad/default -f values.yaml -f secrets://secrets.enc.yaml
```

--------------------------------

### Create Python Virtual Environment

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/tutorial/upload_publish_api.md

Set up a dedicated Python virtual environment for the tutorial. Choose the command appropriate for your operating system.

```bash
python3 -m venv nomad-env
```

```powershell
python -m venv nomad-env
```

--------------------------------

### Start Jupyter Lab

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/tutorial/upload_publish_api.md

Launch Jupyter Lab to create or open a notebook and select the newly registered kernel.

```bash
jupyter lab
```

--------------------------------

### Install Python 3.11 on macOS

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/README.md

Installs Python 3.11 using Homebrew on macOS. Ensure Homebrew is installed first.

```bash
brew install python@3.11
```

--------------------------------

### Build Docker Image with Custom Arguments

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/plugins/types/north_tools.md

Example of building a Docker image with specific build arguments for plugin name, Jupyter tag, and uv version.

```bash
docker build -f src/foobar/north_tools/my_tool/Dockerfile \
  --build-arg PLUGIN_NAME=foobar \
  --build-arg JUPYTER_TAG=2025-10-20 \
  --build-arg UV_VERSION=0.9 \
  -t ghcr.io/myusername/foobar:latest .
```

--------------------------------

### Install cruft

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/tutorial/develop_plugin.md

Install the cruft tool, preferably using pipx for better isolation. Alternatively, install it in your Python user directory.

```sh
# pipx is strongly recommended.
pipx install cruft
```

```sh
# If pipx is not an option,
# you can install cruft in your Python user directory.
python -m pip install --user cruft
```

--------------------------------

### Install uv with pipx

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/README.md

Installs the 'uv' package manager using pipx. Pipx is recommended for installing Python applications in isolated environments.

```bash
pipx install uv
```

--------------------------------

### Install uv - Standalone (macOS/Linux)

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/README.md

Installs the 'uv' package manager using a curl script on macOS and Linux. Ensure you have curl installed.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Install uv - Standalone (Windows)

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/README.md

Installs the 'uv' package manager using a PowerShell script on Windows. This command bypasses the execution policy for the installation.

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Download Example Data File

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/tutorial/develop_plugin.md

Use `curl` to download a sample archive file from a remote repository to your local test directory.

```sh
curl -L -o tests/data/test_sintering.archive.yaml "https://raw.githubusercontent.com/FAIRmat-NFDI/AreaA-Examples/main/tutorial13/part3/files/test_sintering.archive.yaml"
```

--------------------------------

### Response with File Information and Pagination

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/manage/program/graph_api.md

This is an example response showing file details, including the file path and size, along with pagination information. The 'mainfile' token provides access to specific file attributes like 'path' and 'size'.

```json
{
   "search":{
      "m_response":{
         "include":[ "*" ],
         "query":{
            "owner":"all",
            "query":{ "upload_create_time":{ "gt":"2025-01-01" } },
            "pagination":{
               "page_size":1,
               "order":"asc"
            },
            "aggregations":{}
         },
         "pagination":{
            "page_size":1,
            "order_by":"entry_id",
            "order":"asc",
            "page_after_value":null,
            "page":null,
            "page_offset":null,
            "total":37,
            "next_page_after_value":"-L073PFe_PxW90kci4UwxMgUO20O",
            "page_url":null,
            "next_page_url":null,
            "prev_page_url":null,
            "first_page_url":null
         }
      },
      "-L073PFe_PxW90kci4UwxMgUO20O":{
         "entry":{
            "entry_create_time":"2025-06-23T16:34:50.684000",
            "mainfile":{
               "OUTCAR_K_nm_5":{
                  "m_response":{
                     "directive":"plain",
                     "include":[ "*" ],
                     "pagination":{
                        "page":1,
                        "page_size":10,
                        "order":"asc",
                        "total":1
                     }
                  },
                  "path":"OUTCAR_K_nm_5",
                  "size":47862593,
                  "m_is":"File"
               }
            }
         }
      }
   }
}
```

--------------------------------

### Configure App Columns with Search Quantities

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/plugins/types/apps.md

This example demonstrates how to configure the results table to display a new column using a loaded search quantity. The specific quantity and schema are referenced.

```python
--8<-- "examples/plugins/columns.py"
```

--------------------------------

### Example Plugin Repository Layout

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/plugins/types/actions.md

This outlines the typical file structure for a NOMAD plugin that includes an action.

```txt
nomad-example
   ├── src
   │   ├── nomad_example
   │   │   ├── __init__.py
   │   │   ├── actions
   │   │   │   ├── __init__.py
   │   │   │   ├── myaction
   │   │   │   │   ├── __init__.py
   │   │   │   │   ├── activities.py
   │   │   │   │   ├── workflows.py
   │   │   │   │   ├── models.py
   ├── LICENSE.txt
   ├── README.md
   └── pyproject.toml
```

--------------------------------

### Wipe NOMAD Installation

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/oasis/administer.md

Completely wipe the NOMAD installation. This is a destructive operation and requires confirmation.

```bash
nomad admin reset --i-am-really-sure
```

--------------------------------

### Generate Docs Artifacts and Build Site

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/develop/setup.md

Run these commands to generate static files for serving documentation and the NOMAD distribution. Ensure you have the necessary infrastructure running before proceeding.

```shell
./scripts/generate_docs_artifacts.sh
rm -rf site && mkdocs build && mv site nomad/app/static/docs
```

--------------------------------

### Parser Entry Point Resource Loading

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/explanation/plugin_system.md

Implement the `load` method in a plugin entry point to return the actual resource instance. This example loads a `MyParser` instance.

```python
class MyParserEntryPoint(ParserEntryPoint):

    def load(self):
        from nomad_example.parsers.myparser import MyParser

        return MyParser(**self.dict())
```

--------------------------------

### Update uv

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/README.md

Updates the 'uv' package manager to the latest version when installed via the standalone installer.

```bash
uv self update
```

--------------------------------

### Initialize EntryArchive with NOMAD Python Library

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/manage/program/api.md

Demonstrates the initial import for using the NOMAD Python library to work with archive data. This is the starting point for leveraging schema classes for code-completion and data resolution.

```python
from nomad.datamodel import EntryArchive
```

--------------------------------

### Start All NOMAD Services

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/oasis/configure.md

Once core services are running, you can start all NOMAD services, including NORTH, with a single command. Note that starting tools in NORTH for the first time may require pulling images and could take longer.

```sh
docker compose up -d
```

--------------------------------

### Collect First 100 Formulas with Pagination

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/manage/program/api.md

A complete example demonstrating how to collect the first 100 formulas from entries matching a specific query by paginating through the results.

```python
--8<-- "examples/docs/api/pagination.py"
```

--------------------------------

### Configure Schema Package Entry Point in pyproject.toml

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/plugins/types/schema_packages.md

Register your schema package entry point in the `pyproject.toml` file under the `[project.entry-points.'nomad.plugin']` table for automatic detection by NOMAD.

```toml
[project.entry-points.'nomad.plugin']
mypackage = "nomad_example.schema_packages:mypackage"
```

--------------------------------

### Install Configurable HTTP Proxy Globally

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/develop/setup.md

Install the `configurable-http-proxy` Node.js package globally using npm, which is a dependency for JupyterHub.

```shell
npm install -g configurable-http-proxy
```

--------------------------------

### Install Python 3.11 on Debian Linux

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/README.md

Installs Python 3.11 using the apt package manager on Debian-based Linux distributions.

```bash
sudo apt install python3.11
```

--------------------------------

### Using `update_entry` to Process a File

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/develop/normalizing.md

Demonstrates how to use the `update_entry` context manager to create or update a file named 'mainfile.json' and trigger its immediate processing. This method should be used with caution due to potential risks like infinite loops and racing conditions.

```python
with context.update_entry('mainfile.json', process=True) as content_dict:
    # do something with content
    content_dict['key'] = 'value'
    ...
```

--------------------------------

### Fetch File Information using mainfile token

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/manage/program/graph_api.md

This example demonstrates a GraphQL query to fetch file information, specifically using the 'mainfile' token within an entry. The query filters entries by creation time and requests specific file details.

```APIDOC
## Fetch File Information using mainfile token

### Description
This query fetches file information for entries created after a specific date. It uses the `mainfile` token to access details about the primary file within each entry.

### Method
POST

### Endpoint
/graphql

### Request Body
```json
{
   "search":{
      "m_request":{
         "query":{
            "owner":"all",
            "query":{ "upload_create_time":{ "gt":"2025-01-01" } },
            "pagination":{ "page_size":1 }
         }
      },
      "*":{
         "entry":{
            "entry_create_time":{ "m_request":{ "directive":"plain" } },
            "mainfile":{ "m_request":{ "directive":"plain" } }
         }
      }
   }
}
```

### Response
#### Success Response (200)
Returns a JSON object containing search results, including entry details and main file information such as path and size.

#### Response Example
```json
{
   "search":{
      "m_response":{
         "include":[ "*" ],
         "query":{
            "owner":"all",
            "query":{ "upload_create_time":{ "gt":"2025-01-01" } },
            "pagination":{
               "page_size":1,
               "order":"asc"
            },
            "aggregations":{}
         },
         "pagination":{
            "page_size":1,
            "order_by":"entry_id",
            "order":"asc",
            "page_after_value":null,
            "page":null,
            "page_offset":null,
            "total":37,
            "next_page_after_value":"-L073PFe_PxW90kci4UwxMgUO20O",
            "page_url":null,
            "next_page_url":null,
            "prev_page_url":null,
            "first_page_url":null
         }
      },
      "-L073PFe_PxW90kci4UwxMgUO20O":{
         "entry":{
            "entry_create_time":"2025-06-23T16:34:50.684000",
            "mainfile":{
               "OUTCAR_K_nm_5":{
                  "m_response":{
                     "directive":"plain",
                     "include":[ "*" ],
                     "pagination":{
                        "page":1,
                        "page_size":10,
                        "order":"asc",
                        "total":1
                     }
                  },
                  "path":"OUTCAR_K_nm_5",
                  "size":47862593,
                  "m_is":"File"
               }
            }
         }
      }
   }
}
```

### Notes
- The file information listing is always paginated.
- This is particularly useful when listing files in an upload, as there can be many files.
```

--------------------------------

### Query Entries with Pagination

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/manage/program/api.md

Example of querying entries and paginating results to retrieve a specific number of entries. Demonstrates setting page size and using 'page_after_value' for subsequent requests.

```python
response = requests.post(
    f'{base_url}/entries/query',
    json={
        'query': {
            'results.material.elements': {
                'all': ['Ti', 'O']
            }
        },
        'pagination': {
            'page_size': 10
        }
    }
)
```

```json
{
    "page_size": 10,
    "order_by": "entry_id",
    "order": "asc",
    "total": 17957,
    "next_page_after_value": "--SZVYOxA2jTu_L-mSxefSQFmeyF"
}
```

```python
response = requests.post(
    f'{base_url}/entries/query',
    json={
        'query': {
            'results.material.elements': {
                'all': ['Ti', 'O']
            }
        },
        'pagination': {
            'page_size': 10,
            'page_after_value': '--SZVYOxA2jTu_L-mSxefSQFmeyF'
        }
    }
)
```

--------------------------------

### Example Upload Metadata Response

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/manage/program/graph-api/basics.md

This is an example of the JSON response when fetching metadata for a specific upload using a standard REST endpoint.

```json
{
  "uploads":{
    "example_upload_id":{
      "process_running":true,
      "current_process":"process_upload",
      "process_status":"WAITING_FOR_RESULT",
      "last_status_message":"Waiting for results (level 0)",
      "complete_time":"2025-05-27T10:03:54.115000",
      "upload_id":"example_upload_id",
      "upload_name":"Free energy simulation",
      "upload_create_time":"2025-05-27T10:03:35.048000",
      "published":false,
      "with_embargo":false,
      "embargo_length":0,
      "license":"CC BY 4.0"
    }
  }
}
```

--------------------------------

### Install NOMAD Utility Workflows and Python Dotenv

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/tutorial/upload_publish_api.md

Install the necessary Python packages for interacting with the NOMAD API and loading environment variables.

```bash
!pip install --upgrade pip
!pip install "nomad-utility-workflows[vis]>=0.2.0"
!pip install python-dotenv
```

--------------------------------

### Verify Python Magic Library Installation

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/develop/setup.md

Confirm that the Python magic library is correctly installed by attempting to import it within a Python interpreter.

```python
python -c "import magic"
```

--------------------------------

### Defining a Plugin Entry Point in pyproject.toml

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/plugins/plugins.md

This TOML snippet shows how to define a plugin entry point in the `pyproject.toml` file. It maps a name (e.g., `myparser`) to the Python object that implements the entry point.

```toml
[project.entry-points.'nomad.plugin']
myparser = "nomad_example.parsers:myparser"
```

--------------------------------

### Generate UUID Docstring Example

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/reference/code_guidelines.md

Example of a single-line Google-style docstring for a Python function that generates a UUID. Ensure single quotes and padding.

```python
def generate_uuid() -> str:
    '''Generates a base64 encoded Version 4 unique identifier. '''

    return base64.encode(uuid4())
```

--------------------------------

### Instantiate and Populate Schema

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/plugins/types/schema_packages.md

Instantiate the defined schema classes (Simulation and System) and populate their quantities and subsections. Use append to add subsections to a repeating subsection.

```python
simulation = Simulation()
system = System()
system.n_atoms = 3
system.atom_labels = ['H', 'H', 'O']
simulation.system.append(system)
```

--------------------------------

### Build and Copy Documentation

Source: https://github.com/fairmat-nfdi/nomad-docs/blob/develop/docs/howto/develop/setup.md

Builds the NOMAD documentation artifacts and copies them to the static directory for the GUI.

```shell
sh scripts/generate_docs_artifacts.sh
mkdocs build
mkdir -p nomad/app/static/docs
cp -r site/* nomad/app/static/docs
```