{"id":27857761,"url":"https://github.com/pycroscopy/nomad","last_synced_at":"2026-02-13T12:07:13.002Z","repository":{"id":270738843,"uuid":"911318967","full_name":"pycroscopy/nomad","owner":"pycroscopy","description":"Nomad for pycroscopy","archived":false,"fork":false,"pushed_at":"2025-01-02T20:47:16.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-04T13:57:55.365Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pycroscopy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-02T18:29:19.000Z","updated_at":"2025-01-02T20:12:24.000Z","dependencies_parsed_at":"2025-01-02T19:30:24.778Z","dependency_job_id":"8ec3c567-eac3-4a3d-a197-4c0a7af1e6d6","html_url":"https://github.com/pycroscopy/nomad","commit_stats":null,"previous_names":["pycroscopy/nomad"],"tags_count":0,"template":false,"template_full_name":"FAIRmat-NFDI/nomad-distro-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pycroscopy%2Fnomad","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pycroscopy%2Fnomad/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pycroscopy%2Fnomad/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pycroscopy%2Fnomad/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pycroscopy","download_url":"https://codeload.github.com/pycroscopy/nomad/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252344599,"owners_count":21732979,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-04T13:57:57.908Z","updated_at":"2026-02-13T12:07:07.960Z","avatar_url":"https://github.com/pycroscopy.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"![docker image](https://github.com/pycroscopy/nomad/actions/workflows/docker-publish.yml/badge.svg)\n\n\n# pycroscopy's NOMAD Oasis Distribution\n\nThis is the NOMAD Oasis distribution of pycroscopy.\nBelow are instructions for how to [deploy this distribution](#deploying-the-distribution)\nand how to customize it through [adding plugins](#adding-a-plugin).\n\n\u003e [!IMPORTANT]\n\u003e Depending on the settings of the owner of this repository, the distributed image might\n\u003e be private and require authentication to pull.\n\u003e If you want to keep the image private you need to configure and use a personal access\n\u003e token (PAT) according to the instructions in the GitHub docs [here](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic).\n\u003e If you want to make the image public (recommended), you should make sure that your\n\u003e organization settings allow public packages and make this package public after building it.\n\u003e You can read more about this in the GitHub docs [here](https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility).\n\n\u003e [!TIP]\n\u003e In order for others to find and learn from your distribution we in FAIRmat would\n\u003e greatly appreciate it if you would add the topic `nomad-distribution` by clicking the\n\u003e ⚙️ next to \"About\" on the main GitHub page for this repository.\n\nIn this README you will find instructions for:\n1. [Deploying the distribution](#deploying-the-distribution)\n2. [Adding a plugin](#adding-a-plugin)\n3. [Using the jupyter image](#the-jupyter-image)\n4. [Updating the distribution from the template](#updating-the-distribution-from-the-template)\n5. [Solving common issues](#faqtrouble-shooting)\n\n## Deploying the distribution\n\nBelow are instructions for how to deploy this NOMAD Oasis distribution\n[for a new Oasis](#for-a-new-oasis) and [for an existing Oasis](#for-an-existing-oasis)\n\n### For a new Oasis\n\n1. Make sure you have [docker](https://docs.docker.com/engine/install/) installed.\n   Docker nowadays comes with `docker compose` built in. Prior, you needed to\n   install the stand-alone [docker-compose](https://docs.docker.com/compose/install/).\n\n2. Clone the repository or download the repository as a zip file.\n\n    ```sh\n    git clone https://github.com/pycroscopy/nomad.git\n    cd nomad\n    ```\n\n    or\n\n    ```sh\n    curl-L -o nomad.zip \"https://github.com/pycroscopy/nomad/archive/main.zip\"\n    unzip nomad.zip\n    cd nomad\n    ```\n\n3. _On Linux only,_ recursively change the owner of the `.volumes` directory to the nomad user (1000)\n\n    ```sh\n    sudo chown -R 1000 .volumes\n    ```\n\n4. Pull the images specified in the `docker-compose.yaml`\n\n    Note that the image needs to be public or you need to provide a PAT (see \"Important\" note above).\n\n    ```sh\n    docker compose pull\n    ```\n\n5. And run it with docker compose in detached (--detach or -d) mode\n\n    ```sh\n    docker compose up -d\n    ```\n\n6. Optionally you can now test that NOMAD is running with\n\n    ```\n    curl localhost/nomad-oasis/alive\n    ```\n\n7. Finally, open [http://localhost/nomad-oasis](http://localhost/nomad-oasis) in your browser to start using your new NOMAD Oasis.\n\n#### Updating the image\n1. Whenever you update your image you need to shut down NOMAD using\n\n    ```sh\n    docker compose down\n    ```\n\n    and then repeat steps 4. and 5. above.\n   \n2. You can remove unused images to free up space by running\n\n    ```sh\n    docker image prune -a\n    ```\n\n#### NOMAD Remote Tools Hub (NORTH)\n\nTo run NORTH (the NOMAD Remote Tools Hub), the `hub` container needs to run docker and\nthe container has to be run under the docker group. You need to replace the default group\nid `991` in the `docker-compose.yaml`'s `hub` section with your systems docker group id.\nRun `id` if you are a docker user, or `getent group | grep docker` to find your\nsystems docker gid. The user id 1000 is used as the nomad user inside all containers.\n\nPlease see the [Jupyter image](#the-jupyter-image) section below for more information on the jupyter NORTH image being generated in this repository.\n\nYou can find more details on setting up and maintaining an Oasis in the NOMAD docs here:\n[nomad-lab.eu/prod/v1/docs/oasis/install.html](https://nomad-lab.eu/prod/v1/docs/oasis/install.html)\n\n### For an existing Oasis\n\nIf you already have an Oasis running you only need to change the image being pulled in\nyour `docker-compose.yaml` with `ghcr.io/pycroscopy/nomad:main` for the services\n`worker`, `app`, `north`, and `logtransfer`.\n\nIf you want to use the `nomad.yaml` from this repository you also need to comment out\nthe inclusion of the `nomad.yaml` under the volumes key of those services in the\n`docker-compose.yaml`.\n\n```yaml\nvolumes:\n  # - ./configs/nomad.yaml:/app/nomad.yaml\n```\n\nTo run the new image you can follow steps 5. and 6. [above](#for-a-new-oasis).\n\n## Adding a plugin\n\nTo add a new plugin to the docker image you should add it to the plugins table in the [`pyproject.toml`](pyproject.toml) file.\n\nHere you can put either plugins distributed to PyPI, e.g.\n\n```toml\n[project.optional-dependencies]\nplugins = [\n  \"nomad-material-processing\u003e=1.0.0\",\n]\n```\n\nor plugins in a git repository with either the commit hash\n\n```toml\n[project.optional-dependencies]\nplugins = [\n  \"nomad-measurements @ git+https://github.com/FAIRmat-NFDI/nomad-measurements.git@71b7e8c9bb376ce9e8610aba9a20be0b5bce6775\",\n]\n```\n\nor with a tag\n\n```toml\n[project.optional-dependencies]\nplugins = [\n  \"nomad-measurements @ git+https://github.com/FAIRmat-NFDI/nomad-measurements.git@v0.0.4\"\n]\n```\n\nTo add a plugin in a subdirectory of a git repository you can use the `subdirectory` option, e.g.\n\n```toml\n[project.optional-dependencies]\nplugins = [\n  \"ikz_pld_plugin @ git+https://github.com/FAIRmat-NFDI/AreaA-data_modeling_and_schemas.git@30fc90843428d1b36a1d222874803abae8b1cb42#subdirectory=PVD/PLD/jeremy_ikz/ikz_pld_plugin\"\n]\n```\n\nOnce the changes have been committed to the main branch, the new image will automatically\nbe generated.\n\n## The Jupyter image\n\nIn addition to the Docker image for running the oasis, this repository also builds a custom NORTH image for running a jupyter hub with the installed plugins.\nThis image has been added to the [`configs/nomad.yaml`](configs/nomad.yaml) during the initialization of this repository and should therefore already be available in your Oasis under \"Analyze / NOMAD Remote Tools Hub / jupyter\"\n\nThe image is quite large and might cause a timeout the first time it is run. In order to avoid this you can pre pull the image with:\n\n```\ndocker pull ghcr.io/pycroscopy/nomad/jupyter:main\n```\n\nIf you want additional python packages to be available to all users in the jupyter hub you can add those to the jupyter table in the [`pyproject.toml`](pyproject.toml):\n\n```toml\n[project.optional-dependencies]\njupyter = [\n  \"voila\",\n  \"ipyaggrid\",\n  \"ipysheet\",\n  \"ipydatagrid\",\n  \"jupyter-flex\",\n]\n```\n\n\n## Updating the distribution from the template\n\nIn order to update an existing distribution with any potential changes in the template you can add a new `git remote` for the template and merge with that one while allowing for unrelated histories:\n\n```\ngit remote add template https://github.com/FAIRmat-NFDI/nomad-distro-template\ngit fetch template\ngit merge template/main --allow-unrelated-histories\n```\n\nMost likely this will result in some merge conflicts which will need to be resolved. At the very least the `Dockerfile` and GitHub workflows should be taken from \"theirs\":\n\n```\ngit checkout --theirs Dockerfile\ngit checkout --theirs .github/workflows/docker-publish.yml\n```\n\nFor detailed instructions on how to resolve the merge conflicts between different version we refer you to the latest template release [notes](https://github.com/FAIRmat-NFDI/nomad-distro-template/releases/latest)\n\nOnce the merge conflicts are resolved you should add the changes and commit them\n\n```\ngit add -A\ngit commit -m \"Updated to new distribution version\"\n```\n\nIdeally all workflows should be triggered automatically but you might need to run the initialization one manually by navigating to the \"Actions\" tab at the top, clicking \"Template Repository Initialization\" on the left side, and triggering it by clicking \"Run workflow\" under the \"Run workflow\" button on the right.\n\n## FAQ/Trouble shooting\n\n_I get an_ `Error response from daemon: Head \"https://ghcr.io/v2/pycroscopy/nomad/manifests/main\": unauthorized`\n_when trying to pull my docker image._\n\nMost likely you have not made the package public or provided a personal access token (PAT).\nYou can read how to make your package public in the GitHub docs [here](https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility)\nor how to configure a PAT (if you want to keep the distribution private) in the GitHub\ndocs [here](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpycroscopy%2Fnomad","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpycroscopy%2Fnomad","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpycroscopy%2Fnomad/lists"}