How to install plugins into a NOMAD Oasis¶
Plugins allow the customization of a NOMAD deployment in terms of which apps, normalizers, parsers and schema packages are available. In the following we will show to how to install plugins into a NOMAD Oasis.
Option 1: Mount the plugin code¶
The NOMAD docker image adds the folder /app/plugins
to the PYTHONPATH
. This means that you can mount your code into the /app/plugins
directory via the volumes section of the app
and worker
services in your docker-compose.yaml
.
For example, you can do this by adding an extension to the docker-compose.yaml
, e.g. a file called docker-compose.plugins.yaml
. Assuming you have cloned three plugins into the Oasis folder as ./nomad-schema-plugin-example
, ./nomad-parser-plugin-example
and ./nomad-normalizer-plugin-example
,
your docker-compose.plugins.yaml
should look like this:
services:
worker:
volumes:
- ./nomad-schema-plugin-example/nomadschemaexample:/app/plugins/nomadschemaexample
- ./nomad-parser-plugin-example/nomadparserexample:/app/plugins/nomadparserexample
- ./nomad-normalizer-plugin-example/nomadparserexample:/app/plugins/nomadparserexample
app:
volumes:
- ./nomad-schema-plugin-example/nomadschemaexample:/app/plugins/nomadschemaexample
- ./nomad-parser-plugin-example/nomadparserexample:/app/plugins/nomadparserexample
- ./nomad-normalizer-plugin-example/nomadparserexample:/app/plugins/nomadparserexample
You have to tell docker that there are now two compose files. This can be done via the COMPOSE_FILE
environment variable. This is how you can start the Oasis with the plugins:
Here is a complete Oasis setup nomad-oasis-with-plugins.zip. Simply download, extract, and start like any other Oasis:
unzip nomad-oasis-with-plugins.zip
cd nomad-oasis-with-plugins
sudo chown -R 1000 .volumes
sudo chown -R 1000 nomad-schema-plugin-example
sudo chown -R 1000 nomad-parser-plugin-example
sudo chown -R 1000 nomad-normalizer-plugin-example
export COMPOSE_FILE=docker-compose.yaml:docker-compose.plugins.yaml
docker compose pull
docker compose up -d
curl localhost/nomad-oasis/alive
Attention
It is important to set up the correct user rights for your volumes and
plugins. Our default docker-compose
setup uses the user 1000
in group
1000
to run the services, this is the reason for the chown
commands
above that ensure that the processes have access to the data stored in
volumes and in the plugins. If you use another user/group to run the docker
services, update the commands accordingly.
Read the Oasis install guide for more details.
Option 2: Create a derived Docker image with plugin installed via pip
¶
Instead of mounting the code into an existing image, you can also create a new, derived image which has your plugin installed as a pip
package. For this you will to create a new Dockerfile
, which runs the installation step. The basic idea is that your Dockerfile looks something like this:
FROM gitlab-registry.mpcdf.mpg.de/nomad-lab/nomad-fair:latest
RUN pip install build
COPY \
nomadschemaexample \
tests \
README.md \
LICENSE \
pyproject.toml \
.
RUN python -m build --sdist
RUN pip install dist/nomad-schema-plugin-example-*.tar.gz
The image can then be build like this:
Depending on how your plugin code is distributed, you have several options for the actual install steps:
-
Plugin published in PyPI:
-
Plugin code available in GitHub:
-
Plugin published in MPCDF GitLab registry:
-
Copy plugin code from host machine: