feat: Modify the Block Node build for dynamic plugins #2011

mustafauzunn · 2026-01-07T12:29:35Z

Reviewer Notes

Adjust the block node build to run a bare-bone OCI image
Introduce a mechanism to add selected plugins to a bare-bones image

Related Issue(s)

Fixes #1657 #1442

Signed-off-by: Mustafa Uzun <[email protected]>

ata-nas

This is a great addition. I leave some comments, mostly questions to verify.

ata-nas · 2026-01-13T08:02:22Z

block-node/app/docker/docker-compose.yml

+    environment:
+        PLUGINS: ""


Q: by default, for local development, will we include all plugins?

We have 3 possibilities for local development:

To use it with core plugins only and if we want to add additional ones

To use it with all plugins configured through gradle by using the image we use for e2e tests which contains all plugins

To use it with all plugins and just list all of the plugins in docker-compose

My main question is what will happen, by default, when I execute ./gradlew startDockerContainer? Will I get a block node with all plugins? It should, in my mind, be so, in order to have the absolute easiest time while developing.

The base image, the one that is published, should have no plugins at all; zero (0); not even "core" plugins.

It makes sense, however, to have the startDockerContainer task depend on a testing-only task (e.g. buildTestImage) that uses compose to create a temporary image that includes everything.

This implies that the list of plugins in this YAML file should not be empty (assuming this list is what gets loaded into the lib location by the compose task).

block-node/app/docker/Dockerfile

ata-nas · 2026-01-13T08:05:43Z

block-node/app/docker/download-and-load-plugins.sh

+  done
+fi
+
+exec "${BN_WORKDIR}/app-${VERSION}/bin/app"


exec "${BN_WORKDIR}/app-${VERSION}/bin/app" should probably be outside of the script, as this starts the app itself. In general, I think also the name of the script is not very fitting. I wonder, should we have the download-plugins script, which only downloads the plugins and have the starting of the app separate? Just thinking out loud.

We can move the execution part from the script to Dockerfile as it was initially. And the Dockerfile entrypoint could be
ENTRYPOINT ["/bin/bash", "-c", "${BN_WORKDIR}/download-and-load-plugins.sh && ${BN_WORKDIR}/app-${VERSION}/bin/app || sleep 30d"]

Up to you, I could go either way. Just thinking that it would probably be a better option.

The docker image should not, in my opinion, include the plugin loading.
Plugins should be read on startup by the application (not a script), based on configuration, from a well defined bind mount/volume mount location.
The user of the image (i.e. operator) is then responsible for downloading and installing plugins to the defined location.

ata-nas · 2026-01-13T08:06:34Z

block-node/app/docker/download-and-load-plugins.sh

+if [ -n "${PLUGINS:-}" ]; then
+  echo "$PLUGINS" | tr ',' '\n' | while read -r plugin; do
+    curl -L -o "${BN_WORKDIR}/app-${VERSION}/lib/${plugin}.jar" \
+      "https://repo1.maven.org/maven2/org/hiero/block-node/${plugin}/0.25.0-rc1/${plugin}-0.25.0-rc1.jar"


"https://repo1.maven.org/maven2/org/hiero/block-node/${plugin}/0.25.0-rc1/${plugin}-0.25.0-rc1.jar"

These versions should be dynamic. Also, for readability, we could interpolate the string into a variable and then use that variable in the curl.

We will change 0.25.0-rc1 to ${VERSION} when versions align as mentioned in the comment. The reason for hardcoding now is because we don't have plugins published for 0.26 which is the current VERSION in the repo

Noted, we could link this to a GH issue.

We will only ever align on release branches, for main we have a catch-22 problem, we need to think this over, one proposal is to use the jars from the build instead. another is to see where are the SNAPSHOT if they exist at all in Maven and use the different address or method of getting them.

ata-nas · 2026-01-13T08:12:32Z

block-node/app/build.gradle.kts

    runtimeOnly("org.hiero.block.node.messaging")
    runtimeOnly("org.hiero.block.node.health")
-    runtimeOnly("org.hiero.block.node.stream.publisher")
-    runtimeOnly("org.hiero.block.node.stream.subscriber")
-    runtimeOnly("org.hiero.block.node.verification")
-    runtimeOnly("org.hiero.block.node.blocks.files.historic")
-    runtimeOnly("org.hiero.block.node.blocks.files.recent")
    runtimeOnly("org.hiero.block.node.access.service")
    runtimeOnly("org.hiero.block.node.server.status")


Are the remaining plugins in the mainModuleInfo considered "core"? I would think that server status and access service are probably optional? Really the only "core" plugins are messaging and health, as the app itself is an HealthFacility and messaging must be loaded in order to startup the app. Personally, I think if a plugin's absence does not in any way hinder the ability to startup the app, it should probably be considered "optional". That, however, is indeed only technically speaking. I do see an argument saying that health and access could be considered "core" design wise. Not sure about this.

I agree with both of the ideas. We can discuss it with the team in this thread and decide which plugins should be considered core

My opinion:
No plugins should be considered "core". All plugins (including messaging, health, status, etc...) should be loaded at runtime from a folder that is filled in by the deployment process (not the build process).
We made these plugins so we could replace them if desired, but continuing to include them in the base (i.e. "barebones") image prevents that replacement.
The base image really shouldn't have anything other than the app module and non-pluggable modules (e.g. helidon, config, metrics).

ata-nas · 2026-01-13T08:13:40Z

block-node/app/docker/download-and-load-plugins.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+# Change 0.25.0-rc1 to ${VERSION} when versions align


This comment suggests that a change needs to be made.

We will change 0.25.0-rc1 to ${VERSION} when versions align as mentioned in the comment. The reason for hardcoding now is because we don't have plugins published for 0.26 which is the current VERSION in the repo

Rather than hardcode, perhaps accept the version as a script parameter and pass that in?

When we do a release, we do the publish of the OCI images and plugins in parallel, after this change, we need to publish OCI image only if the plugins were sucessfully published to maven, so subsequent tasks don't fail, that will require changes in https://github.com/hiero-ledger/hiero-block-node/blob/main/.github/workflows/release-push-image.yaml to make the release consistent and that chart test won't fail:

For local build using snapshot versions, we should get them from build rather than maven, that or maybe maven someplace is storing the -SNAPSHOT versions, and overwriting it with every publish (which happens on each commit to main)

see the latest as example: https://github.com/hiero-ledger/hiero-block-node/actions/runs/20973106476

ata-nas · 2026-01-13T08:22:23Z

charts/block-node-server/values-overrides/minimal.yaml

Q: What is the user story behind "minimal"? I do not see the backfill plugin, which is the only difference with lfh. But do we really ned the historic plugin for a "minimal" install? Answering the user story question will bring more clarity.

minimal I understand as the minimum resource-demanding set of plugins and functional block node

Correct, Minimal is about resources, not plugins.
All current plugins are needed for minimal as it's a configuration for development and testing.

codecov · 2026-01-13T12:07:19Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@             Coverage Diff              @@
##               main    #2011      +/-   ##
============================================
- Coverage     78.99%   78.86%   -0.14%     
+ Complexity     1241     1234       -7     
============================================
  Files           130      130              
  Lines          5952     5952              
  Branches        646      646              
============================================
- Hits           4702     4694       -8     
- Misses          955      960       +5     
- Partials        295      298       +3

see 8 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

jsync-swirlds · 2026-01-13T16:14:33Z

block-node/app/docker/Dockerfile

 # Install Java
 COPY --from=java-builder ${JAVA_HOME}/ ${JAVA_HOME}/
+# COPY bash script to container
+COPY download-and-load-plugins.sh ${BN_WORKDIR}/download-and-load-plugins.sh


I don't think this belongs in the application container.
Downloading and loading plugins should happen exclusively outside of the main application container.

jsync-swirlds · 2026-01-13T16:15:13Z

block-node/app/docker/Dockerfile


 # RUN the bin script for starting the server
-ENTRYPOINT ["/bin/bash", "-c", "${BN_WORKDIR}/app-${VERSION}/bin/app || sleep 30d"]
+ENTRYPOINT ["/bin/bash", "-c", "${BN_WORKDIR}/download-and-load-plugins.sh || sleep 30d"]


This seems off. The Application OCI image should launch the app, not a download process.

The intent of the base image setup is to have an image with no plugins at all. Then the deployment process (helm chart or otherwise) loads the plugins to an externally mounded volume (e.g. bind-mount or similar) that corresponds to the application lib folder inside the image.

jsync-swirlds · 2026-01-13T16:19:43Z

charts/block-node-server/values-overrides/all-plugins.yaml

@@ -0,0 +1,3 @@
+blockNode:
+    config:
+        PLUGINS: "stream-publisher,stream-subscriber,verification,blocks-file-historic,blocks-file-recent,backfill,s3-archive"


missing: messaging, status, health, block-access-service.

jsync-swirlds · 2026-01-13T16:23:21Z

charts/block-node-server/values-overrides/rfh.yaml

@@ -0,0 +1,3 @@
+blockNode:
+    config:
+        PLUGINS: "stream-publisher,stream-subscriber,verification,blocks-file-historic,blocks-file-recent,backfill,s3-archive"


Missing: messaging, status, health, block-access-service.
Remove: blocks-file-historic, stream-subscriber
Open question: Do we require blocks-file-recent, or can we remove that as well?

jsync-swirlds · 2026-01-13T16:23:36Z

charts/block-node-server/values.yaml

    # key: value
    JAVA_TOOL_OPTIONS: "-Djava.util.logging.config.file=/opt/hiero/block-node/logs/config/logging.properties"
    JAVA_OPTS: '-Xms16G -Xmx16G -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath="/tmp/dump.hprof"'
+    PLUGINS: ""


Missing: messaging, status, health, block-access-service.

jsync-swirlds · 2026-01-13T16:23:52Z

charts/block-node-server/values-overrides/minimal.yaml

@@ -0,0 +1,3 @@
+blockNode:
+    config:
+        PLUGINS: "stream-publisher,stream-subscriber,verification,blocks-file-historic,blocks-file-recent"


Missing: messaging, status, health, block-access-service.

jsync-swirlds · 2026-01-13T16:24:14Z

charts/block-node-server/values-overrides/lfh.yaml

@@ -0,0 +1,3 @@
+blockNode:
+    config:
+        PLUGINS: "stream-publisher,stream-subscriber,verification,blocks-file-historic,blocks-file-recent,backfill"


Missing: messaging, status, health, block-access-service.

jsync-swirlds · 2026-01-13T18:45:11Z

block-node/app/build.gradle.kts

+    mainModuleInfo {
+        runtimeOnly("org.hiero.block.node.archive.s3cloud")
+        runtimeOnly("org.hiero.block.node.stream.publisher")
+        runtimeOnly("org.hiero.block.node.stream.subscriber")
+        runtimeOnly("org.hiero.block.node.verification")
+        runtimeOnly("org.hiero.block.node.blocks.files.historic")
+        runtimeOnly("org.hiero.block.node.blocks.files.recent")
+        runtimeOnly("org.hiero.block.node.backfill")
+    }


Is this truly required?
The module runtime requirements should be dynamically discovered by Java based on the jars present in the lib folder (otherwise how would we add new plugins without changing the build process?)...

AlfredoG87

Looking good, just a few nits, a couple suggestions, and a blocking issue: the version thing.

👍

AlfredoG87 · 2026-01-14T06:39:16Z

block-node/app/docker/download-and-load-plugins.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+# Change 0.25.0-rc1 to ${VERSION} when versions align


For local build using snapshot versions, we should get them from build rather than maven, that or maybe maven someplace is storing the -SNAPSHOT versions, and overwriting it with every publish (which happens on each commit to main)

see the latest as example: https://github.com/hiero-ledger/hiero-block-node/actions/runs/20973106476

AlfredoG87 · 2026-01-14T06:40:23Z

block-node/app/docker/download-and-load-plugins.sh

@@ -0,0 +1,11 @@
+#!/bin/bash


Missing set -e for fail-fast behavior. If curl fails to download a plugin, the script continues and starts the app with missing dependencies.
#!/bin/bash

Suggested change

#!/bin/bash

#!/bin/bash

set -e

AlfredoG87 · 2026-01-14T06:42:28Z

block-node/app/docker/download-and-load-plugins.sh

+if [ -n "${PLUGINS:-}" ]; then
+  echo "$PLUGINS" | tr ',' '\n' | while read -r plugin; do
+    curl -L -o "${BN_WORKDIR}/app-${VERSION}/lib/${plugin}.jar" \
+      "https://repo1.maven.org/maven2/org/hiero/block-node/${plugin}/0.25.0-rc1/${plugin}-0.25.0-rc1.jar"


We will only ever align on release branches, for main we have a catch-22 problem, we need to think this over, one proposal is to use the jars from the build instead. another is to see where are the SNAPSHOT if they exist at all in Maven and use the different address or method of getting them.

AlfredoG87 · 2026-01-14T06:42:57Z

block-node/app/docker/download-and-load-plugins.sh

+  echo "$PLUGINS" | tr ',' '\n' | while read -r plugin; do
+    curl -L -o "${BN_WORKDIR}/app-${VERSION}/lib/${plugin}.jar" \
+      "https://repo1.maven.org/maven2/org/hiero/block-node/${plugin}/0.25.0-rc1/${plugin}-0.25.0-rc1.jar"
+  done


No verification of downloaded artifacts. Issue #1442 mentions "SHA-512 hash verification" as a potential requirement. At minimum, consider checking curl exit status and file existence

AlfredoG87 · 2026-01-14T06:43:23Z

block-node/app/docker/download-and-load-plugins.sh

+# Change 0.25.0-rc1 to ${VERSION} when versions align
+if [ -n "${PLUGINS:-}" ]; then
+  echo "$PLUGINS" | tr ',' '\n' | while read -r plugin; do
+    curl -L -o "${BN_WORKDIR}/app-${VERSION}/lib/${plugin}.jar" \


Using -fL instead of just -L would make curl fail on HTTP errors (4xx/5xx) rather than saving error pages as jar files.

AlfredoG87 · 2026-01-14T06:43:53Z

block-node/app/docker/Dockerfile


 # Install Java
 COPY --from=java-builder ${JAVA_HOME}/ ${JAVA_HOME}/
+# COPY bash script to container


nit: The comment "COPY bash script to container" is redundant—the COPY command is self-explanatory

AlfredoG87 · 2026-01-14T06:45:41Z

charts/block-node-server/values-overrides/minimal.yaml

@@ -0,0 +1,3 @@
+blockNode:
+    config:
+        PLUGINS: "stream-publisher,stream-subscriber,verification,blocks-file-historic,blocks-file-recent"


[nit] Indentation uses 8 spaces for the PLUGINS key, but looking at other values-overrides files like mid-size.yaml, they use 4 spaces. Should be consistent.

Same applies to lfh.yaml, rfh.yaml, and all-plugins.yaml

feat: initial selected plugins deployment changes

27a0a2e

Signed-off-by: Mustafa Uzun <[email protected]>

mustafauzunn added this to the 0.28.0 milestone Jan 7, 2026

mustafauzunn self-assigned this Jan 7, 2026

mustafauzunn added the Block Node Issues/PR related to the Block Node. label Jan 7, 2026

mustafauzunn linked an issue Jan 7, 2026 that may be closed by this pull request

feat(charts): Add Mount Volume for Plugins Source #1442

Open

mustafauzunn added 3 commits January 7, 2026 16:04

feat: predefined values

de2914a

Signed-off-by: Mustafa Uzun <[email protected]>

refactor: build

89a908b

Signed-off-by: Mustafa Uzun <[email protected]>

refactor: build

746b101

Signed-off-by: Mustafa Uzun <[email protected]>

mustafauzunn marked this pull request as ready for review January 12, 2026 11:05

mustafauzunn requested review from a team as code owners January 12, 2026 11:05

mustafauzunn requested a review from Nana-EC January 12, 2026 11:05

ata-nas reviewed Jan 13, 2026

View reviewed changes

mustafauzunn requested review from AlfredoG87 and jsync-swirlds January 13, 2026 12:06

jsync-swirlds reviewed Jan 13, 2026

View reviewed changes

AlfredoG87 requested changes Jan 14, 2026

View reviewed changes

		@@ -0,0 +1,11 @@
		#!/bin/bash

		# Change 0.25.0-rc1 to ${VERSION} when versions align

feat: Modify the Block Node build for dynamic plugins #2011

Are you sure you want to change the base?

feat: Modify the Block Node build for dynamic plugins #2011

Conversation

mustafauzunn commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviewer Notes

Related Issue(s)

Uh oh!

ata-nas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jsync-swirlds Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jsync-swirlds Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Jan 13, 2026

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jsync-swirlds Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mustafauzunn commented Jan 7, 2026 •

edited

Loading

jsync-swirlds Jan 13, 2026 •

edited

Loading

jsync-swirlds Jan 13, 2026 •

edited

Loading

jsync-swirlds Jan 13, 2026 •

edited

Loading