This is an distribution image of a NOMAD Oasis provided by FAIRmat. Below are instructions for how to deploy this distribution and how to customize it through adding plugins.
Below are instructions for how to deploy this NOMAD Oasis distribution for a new Oasis and for an existing Oasis. For further questions, consult the official documentation.
-
Make sure you have docker installed. Docker nowadays comes with
docker composebuilt in. Prior, you needed to install the stand-alone docker-compose. -
Clone the repository or download the repository as a zip file.
git clone https://github.com/fabianschoeppach/nomad-UNITOV-image.git
cd nomad-UNITOV-imageor
curl-L -o nomad-UNITOV-image.zip "https://github.com/fabianschoeppach/nomad-UNITOV-image/archive/main.zip"
unzip nomad-UNITOV-image.zip
cd nomad-UNITOV-image- On Linux only, recursively change the owner of the
.volumesdirectory to the nomad user (1000)
sudo chown -R 1000 .volumes- Pull the images specified in the
docker-compose.yaml
docker compose pull- And run it with docker compose in detached (--detach or -d) mode
docker compose up -d- Optionally you can now test that NOMAD is running with
curl localhost/nomad-oasis/alive
- Finally, open http://localhost/nomad-oasis in your browser to start using your new NOMAD Oasis.
Whenever you want to update your image you first need to shut down NOMAD using docker compose down. Afterwards you can pull the updates and simply restart the oasis:
docker compose down
docker compose pull
docker compose up -dTo run NORTH (the NOMAD Remote Tools Hub), the hub container needs to run docker and
the container has to be run under the docker group. You need to replace the default group
id 991 in the docker-compose.yaml's hub section with your systems docker group id.
Run id if you are a docker user, or getent group | grep docker to find your
systems docker gid. The user id 1000 is used as the nomad user inside all containers.
You can find more details on setting up and maintaining an Oasis in the NOMAD docs here: nomad-lab.eu/prod/v1/docs/oasis/install.html
If you already have an Oasis running you only need to change the image being pulled in
your docker-compose.yaml with ghcr.io/fabianschoeppach/nomad-UNITOV-image:main for the services
worker, app, north, and logtransfer.
If you want to use the nomad.yaml from this repository you also need to comment out
the inclusion of the nomad.yaml under the volumes key of those services in the
docker-compose.yaml.
volumes:
# - ./configs/nomad.yaml:/app/nomad.yamlTo run the new image you can follow steps 5. and 6. above.
To add a new plugin to the docker image you should add it to the plugins table in the pyproject.toml file.
Here you can put either plugins distributed to PyPI, e.g.
[project.optional-dependencies]
plugins = [
"nomad-material-processing>=1.0.0",
]or plugins in a git repository with either the commit hash
[project.optional-dependencies]
plugins = [
"nomad-measurements @ git+https://github.com/FAIRmat-NFDI/nomad-measurements.git@71b7e8c9bb376ce9e8610aba9a20be0b5bce6775",
]or with a tag
[project.optional-dependencies]
plugins = [
"nomad-measurements @ git+https://github.com/FAIRmat-NFDI/[email protected]"
]To add a plugin in a subdirectory of a git repository you can use the subdirectory option, e.g.
[project.optional-dependencies]
plugins = [
"ikz_pld_plugin @ git+https://github.com/FAIRmat-NFDI/AreaA-data_modeling_and_schemas.git@30fc90843428d1b36a1d222874803abae8b1cb42#subdirectory=PVD/PLD/jeremy_ikz/ikz_pld_plugin"
]Once the changes have been committed to the main branch, the new image will automatically be generated.
In 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.
This image has been added to the 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"
The 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:
docker pull ghcr.io/fairmat-nfdi/nomad-distribution-template/jupyter:main
If 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:
[project.optional-dependencies]
jupyter = [
"voila",
"ipyaggrid",
"ipysheet",
"ipydatagrid",
"jupyter-flex",
]In 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:
git remote add template https://github.com/FAIRmat-NFDI/nomad-distribution-template
git fetch template
git merge template/main --allow-unrelated-histories
Most 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":
git checkout --theirs Dockerfile
git checkout --theirs .github/workflows/docker-publish.yml
For detailed instructions on how to resolve the merge conflicts between different version we refer you to the latest template release notes.
Once the merge conflicts are resolved you should add the changes and commit them
git add -A
git commit -m "Updated to new distribution version"
Ideally 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.
I get an Error response from daemon: Head "https://ghcr.io/v2/fabianschoeppach/nomad-UNITOV-image/manifests/main": unauthorized
when trying to pull my docker image.
Most likely you have not made the package public or provided a personal access token (PAT). You can read how to make your package public in the GitHub docs here or how to configure a PAT (if you want to keep the distribution private) in the GitHub docs here.
Funding for this work has been provided by the European Union as part of the SolMates project (Project Nr. 101122288).
