search

FAIRmat-NFDI / nomad-distro-template

An example repository for creating a nomad distribution with custom plugins.
Apache License 2.0
7 stars 2 forks source link

Version 2 release notes #30

Closed hampusnasstrom closed 1 month ago

hampusnasstrom commented 1 month ago

We need to add some release notes for version 2 of the distro template. Let's collect some ideas in this issue.

blueraft commented 1 month ago

  1. Dependency Management Overhaul:

    • In v2, all dependencies are resolved upfront and installed in a single step. This prevents overwriting existing versions or installing conflicting packages with the original nomad installation.
    • You now have full control over plugins by inspecting and managing them through the pyproject.toml file, making it easier to disable or exclude specific plugins that were previously part of the original setup.

  2. Jupyter Image Integration:

    • We now build a Jupyter image alongside the Nomad Oasis image. This means that all your plugins and the Nomad package are available in the Jupyter environment, offering a unified experience across both images.

  3. Breaking Change: Transition from plugins.txt to pyproject.toml:

    • In v2, we've moved away from using the plugins.txt file. All plugin dependencies are now listed in the pyproject.toml file for better control and flexibility. [add migration steps here]
hampusnasstrom commented 1 month ago

Migration steps:

When moving from the first to the second version of the distribution image you can choose to keep your docker-compose.yaml:

git checkout --ours docker-compose.yaml

You can choose whether to keep your README.md but we recommend updating it as it contains the updated instructions for how to use the distribution repository:

git checkout --theirs README.md

The plugins are now listed in the pyproject.toml instead of the plugins.txt and can be added there with uv and the plugins.txt removed:

uv add --optional plugins -r plugins.txt --no-sync
rm plugins.txt

The nomad.yaml is now moved to the configs directory. We have added the newly generated jupyter image to the north config. If you have an existing jupyter config you can choose to change the image to the one listed in the new nomad.yaml in the configs directory. If you don't have an existing north config you can copy the whole config block. After you have updated the north config in your existing nomad.yaml you can copy it into the configs directory:

mv nomad.yaml configs/nomad.yaml

Finally, the new recommendation is to either git clone the distribution repository or to curl the whole repository so the nomad-oasis.zip can also be removed:

rm nomad-oasis.zip
hampusnasstrom commented 1 month ago

Maybe I add something about following the instructions in the README first

hampusnasstrom commented 1 month ago

Something like:

To migrate from version 1 to version 2 you can follow the general instructions in the template README.

For the merge conflicts you can choose to keep your docker-compose.yaml: ...

blueraft commented 1 month ago

I think you can copy paste the migration section from README here, otherwise to migrate you have to move back and forth between the two documents

blueraft commented 1 month ago

This is done