v2.2.0

What's Changed

Migration to Temporal for NOMAD v1.4.0 Processing

The Docker Compose setup has been updated to support Temporal-based workflows.
By default, the docker-compose.yaml now runs four worker replicas. Adjust this number based on your server capacity. Refer to the README section on configuring worker replicas and resource limits for guidance.

You can monitor resource usage with:

docker stats

and check CPU and memory capacity using:

lscpu && free -h

Use these commands to tune your worker replica count for optimal performance.

---

Infrastructure for NOMAD Actions

NOMAD v1.4.0 introduces NOMAD Actions, a powerful new framework that lets plugin authors build durable, fault-tolerant, and reproducible workflows powered by Temporal. With Actions, you can orchestrate complex computations directly within NOMAD while maintaining full control over execution and recovery.

See the documentation for details: How to Define an Action

In this template, the build steps for cpuworker and gpuworker images are commented out by default. To enable Actions, follow the Enabling NOMAD Actions guide after adding a plugin that includes an ActionEntryPoint.

---

Secret Management

NOMAD v1.4.0 enforces stricter API secret handling. The system now raises an error if no API secret is set.
Use the provided script to generate a secure secret and store it in the .env file (which is gitignored):

scripts/generate-env.sh

---

New Test for App Entry Points

A new test file, test_app_entry_points.py, has been added to validate that all app entry points are defined correctly.
Previously, misconfigured entry points could cause an app to crash when opened in the browser.
With this test, such issues are now detected early in the development pipeline.

---

Updating from the Template

To merge updates from the latest template release:

git remote add template https://github.com/FAIRmat-NFDI/nomad-distro-template
git fetch template
git merge v2.2.0 --allow-unrelated-histories

Resolve merge conflicts as needed. At minimum, take the following files from the template (“theirs”):

git checkout --theirs Dockerfile
git checkout --theirs .github/workflows/docker-publish.yml

For docker-compose.yaml, accept the template version and then update image URLs as required.
The .github/workflows/initialize.yml workflow can update image URLs automatically:

git checkout --theirs docker-compose.yaml

If desired, keep your existing dependency lock file:

git checkout --ours uv.lock

---

These updates align the distribution with NOMAD v1.4.0’s Temporal-based infrastructure and security improvements.

Full Changelog: v2.1.0...v2.2.0

v2.1.0

What's Changed

Automated Unit and Example Upload Tests in CI

By default, all unit tests from every plugin are executed to ensure system stability and catch potential issues early. These tests validate core functionality and help maintain consistency across different plugins.

In addition to unit tests, the pipeline also verifies that all example uploads can be processed correctly. This ensures that any generated entries do not contain error messages, providing confidence that data flows through the system as expected.

For example upload tests, the CI uses the image built in the Build Image step. It then runs the Docker container and starts up the application to confirm that it functions correctly. This approach ensures that if the pipeline passes, the app is more likely to run smoothly in a Dockerized environment on a server, not just locally.

If you need to disable tests for specific plugins, update the PLUGIN_TESTS_PLUGINS_TO_SKIP variable in .github/workflows/docker-publish.yml by adding the plugin names to the existing list.

Set Up Regular Package Updates with Dependabot

Dependabot is already configured in the repository’s CI setup, but you need to enable it manually in the repository settings.

To enable Dependabot, go to Settings > Code security and analysis in your GitHub repository. From there, turn on Dependabot alerts and version updates. Once enabled, Dependabot will automatically check for dependency updates and create pull requests when new versions are available.

This automated process helps ensure that your dependencies stay up to date, improving security and reducing the risk of vulnerabilities.

Customizing Documentation

By default, documentation is built using the nomad-docs repository. However, if you'd like to customize the documentation for your Oasis instance, you can easily do so.

• First, fork the nomad-docs repository.
• Make your desired changes in your fork.
• Update the NOMAD_DOCS_REPO variable in the .github/workflows/docker-publish.yml file to point to the URL of your forked repository.

This setup ensures that your custom documentation is used when building your Oasis.

Updating the distribution from the template

   git remote add template https://github.com/FAIRmat-NFDI/nomad-distro-template
   git fetch template
   git merge v2.1.0 --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

You can choose to keep your docker-compose.yamland lock file uv.lock:

   git checkout --ours docker-compose.yaml
   git checkout --ours uv.lock

New Contributors

• @RubelMozumder made their first contribution in #98

Full Changelog: v2.1.0...v2.2.0

Version 2.0.0

What's Changed

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, Transitioning 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.

• To migrate from version 1 to version 2 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-distro-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
  

  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
  

  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
  

  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.

  Once the "Template Repository Initialization" workflow has completed you will find a new updated nomad.yaml in the configs directory. We have added the newly generated jupyter image to the north config there. 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
  

Pull Requests

• Added instructions for if initialize workflow fails to run by @hampusnasstrom in #18
• Update to the new distro mechanism by @blueraft in #23
• Revert image name change by @blueraft in #26
• Disable prerelease by @blueraft in #27
• Combine READMEs and add migration instructions by @hampusnasstrom in #29
• Install using apt get by @blueraft in #32
• 33 add jupyter dependencies by @hampusnasstrom in #34

New Contributors

• @blueraft made their first contribution in #23

Full Changelog: v1.0.3...v2.0.0

Version 1.0.3

What's Changed

• Added information on package access rights by @hampusnasstrom in #15

Full Changelog: v1.0.2...v1.0.3

Version 1.0.2

What's Changed

• Remove cosign from docker workflow by @hampusnasstrom in #13
• Update readme with curl instructions by @hampusnasstrom in #10

Full Changelog: v1.0.1...v1.0.2

Version 1.0.1

What's Changed

• 7 image paths in docker composeyaml must be all lower case by @hampusnasstrom in #8

Full Changelog: v1.0.0...v1.0.1

Version 1.0.0

What's Changed

• 1 make into template by @hampusnasstrom in #2
• Move files to top level and update README by @hampusnasstrom in #4
• Update template_README.md by @hampusnasstrom in #6

New Contributors

• @hampusnasstrom made their first contribution in #2

Full Changelog: https://github.com/FAIRmat-NFDI/nomad-distribution-template/commits/v1.0.0