From 6d27bde13ccd0ce267c00e85aa105e6220ab2925 Mon Sep 17 00:00:00 2001 From: Reza Rajan <28660160+rezarajan@users.noreply.github.com> Date: Sat, 20 Sep 2025 08:40:02 +0000 Subject: [PATCH 1/4] feat(dynamic-forging): include --start-as-non-producing-node flag for dynamic forging - update readme with new env var and usage Signed-off-by: Reza Rajan <28660160+rezarajan@users.noreply.github.com> --- README.md | 47 ++++++++++++++++++++++++++++++++++++++++++++++- bin/run-node | 6 ++++++ 2 files changed, 52 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index aa5a3fa..6e50593 100644 --- a/README.md +++ b/README.md @@ -148,6 +148,46 @@ docker run --detach \ ghcr.io/blinklabs-io/cardano-node run ``` +##### Dynamic Block Forging + +To start a block producer in non-producing mode initially (for dynamic block forging): + +```bash +docker run --detach \ + --name cardano-node \ + --restart unless-stopped \ + -e CARDANO_BLOCK_PRODUCER=true \ + -e START_AS_NON_PRODUCING=true \ + -e CARDANO_SHELLEY_KES_KEY=/opt/cardano/config/keys/kes.skey \ + -e CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE=/opt/cardano/config/keys/node.cert \ + -e CARDANO_SHELLEY_VRF_KEY=/opt/cardano/config/keys/vrf.skey \ + -v /src/cardano/node-keys:/opt/cardano/config/keys \ + -v /srv/cardano/node-db:/data/db \ + -v /srv/cardano/node-ipc:/ipc \ + -p 3001:3001 \ + -p 12798:12798 \ + ghcr.io/blinklabs-io/cardano-node run +``` + +With dynamic block forging enabled, you can control block production without restarting the node: + +- **Enable block forging**: Ensure credential files are present and send SIGHUP + ```bash + docker exec cardano-node pkill -SIGHUP cardano-node + ``` + +- **Disable block forging**: Move/rename credential files and send SIGHUP + ```bash + docker exec cardano-node mv /opt/cardano/config/keys/kes.skey /opt/cardano/config/keys/kes.skey.disabled + docker exec cardano-node pkill -SIGHUP cardano-node + ``` + +- **Re-enable block forging**: Restore credential files and send SIGHUP + ```bash + docker exec cardano-node mv /opt/cardano/config/keys/kes.skey.disabled /opt/cardano/config/keys/kes.skey + docker exec cardano-node pkill -SIGHUP cardano-node + ``` + The above uses Docker's built in supervisor to restart a container which fails for any reason. This will also cause the container to automatically restart after a host reboot, so long as Docker is configured to start on boot. We @@ -224,7 +264,12 @@ and operational certificate. `${CARDANO_CONFIG_BASE}/keys/vrf.skey`) - `CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE` - Stake pool identity certificate (default: - `${CARDANO_CONFIG_BASE}/keys/node.cert` + `${CARDANO_CONFIG_BASE}/keys/node.cert`) +- `START_AS_NON_PRODUCING` + - Start block producer node in non-producing mode (default: `false`) + - When set to `true`, adds the `--start-as-non-producing-node` flag + - Only applies when `CARDANO_BLOCK_PRODUCER=true` + - Enables dynamic block forging control via SIGHUP signals #### Controlling Mithril snapshots diff --git a/bin/run-node b/bin/run-node index afffb25..807a520 100755 --- a/bin/run-node +++ b/bin/run-node @@ -81,6 +81,7 @@ if [[ -z $ANCILLARY_VERIFICATION_KEY && -f $ANCILLARY_VERIFICATION_KEY_PATH ]]; fi SNAPSHOT_DIGEST=${SNAPSHOT_DIGEST:-latest} RESTORE_SNAPSHOT=${RESTORE_SNAPSHOT:-true} +START_AS_NON_PRODUCING=${START_AS_NON_PRODUCING:-false} echo CARDANO_BIND_ADDR=${CARDANO_BIND_ADDR} echo CARDANO_BLOCK_PRODUCER=${CARDANO_BLOCK_PRODUCER} @@ -92,6 +93,7 @@ echo CARDANO_PORT=${CARDANO_PORT} echo CARDANO_RTS_OPTS=${CARDANO_RTS_OPTS} echo CARDANO_SOCKET_PATH=${CARDANO_SOCKET_PATH} echo CARDANO_TOPOLOGY=${CARDANO_TOPOLOGY} +echo START_AS_NON_PRODUCING=${START_AS_NON_PRODUCING} # block producer only if [[ ${CARDANO_BLOCK_PRODUCER} == true ]]; then @@ -170,6 +172,10 @@ if [[ ${CARDANO_BLOCK_PRODUCER} == true ]]; then --shelley-vrf-key ${CARDANO_SHELLEY_VRF_KEY} \ --socket-path ${CARDANO_SOCKET_PATH} \ --topology ${CARDANO_TOPOLOGY}) + # Add --start-as-non-producing-node flag if START_AS_NON_PRODUCING is true + if [[ ${START_AS_NON_PRODUCING} == true ]]; then + effopts+=(--start-as-non-producing-node) + fi else effopts=(--config ${CARDANO_CONFIG} \ --database-path ${CARDANO_DATABASE_PATH} \ From 3941d308b0b87d00869539abb764158a7c94b202 Mon Sep 17 00:00:00 2001 From: Reza Rajan <28660160+rezarajan@users.noreply.github.com> Date: Sat, 20 Sep 2025 08:44:40 +0000 Subject: [PATCH 2/4] docs: fix typo Signed-off-by: Reza Rajan <28660160+rezarajan@users.noreply.github.com> --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6e50593..45222c7 100644 --- a/README.md +++ b/README.md @@ -141,8 +141,8 @@ docker run --detach \ -e CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE=/opt/cardano/config/keys/node.cert \ -e CARDANO_SHELLEY_VRF_KEY=/opt/cardano/config/keys/vrf.skey \ -v /src/cardano/node-keys:/opt/cardano/config/keys \ - -v /srv/cardano/node-db:/data/db \ - -v /srv/cardano/node-ipc:/ipc \ + -v /src/cardano/node-db:/data/db \ + -v /src/cardano/node-ipc:/ipc \ -p 3001:3001 \ -p 12798:12798 \ ghcr.io/blinklabs-io/cardano-node run @@ -162,8 +162,8 @@ docker run --detach \ -e CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE=/opt/cardano/config/keys/node.cert \ -e CARDANO_SHELLEY_VRF_KEY=/opt/cardano/config/keys/vrf.skey \ -v /src/cardano/node-keys:/opt/cardano/config/keys \ - -v /srv/cardano/node-db:/data/db \ - -v /srv/cardano/node-ipc:/ipc \ + -v /src/cardano/node-db:/data/db \ + -v /src/cardano/node-ipc:/ipc \ -p 3001:3001 \ -p 12798:12798 \ ghcr.io/blinklabs-io/cardano-node run From 8a9a6ebe68db5b7113fd1e6d14522b52780bbd3e Mon Sep 17 00:00:00 2001 From: Reza Rajan <28660160+rezarajan@users.noreply.github.com> Date: Sat, 20 Sep 2025 18:51:47 +0000 Subject: [PATCH 3/4] docs(readme): fix typo src -> srv Signed-off-by: Reza Rajan <28660160+rezarajan@users.noreply.github.com> --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 45222c7..9a107bc 100644 --- a/README.md +++ b/README.md @@ -140,9 +140,9 @@ docker run --detach \ -e CARDANO_SHELLEY_KES_KEY=/opt/cardano/config/keys/kes.skey \ -e CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE=/opt/cardano/config/keys/node.cert \ -e CARDANO_SHELLEY_VRF_KEY=/opt/cardano/config/keys/vrf.skey \ - -v /src/cardano/node-keys:/opt/cardano/config/keys \ - -v /src/cardano/node-db:/data/db \ - -v /src/cardano/node-ipc:/ipc \ + -v /srv/cardano/node-keys:/opt/cardano/config/keys \ + -v /srv/cardano/node-db:/data/db \ + -v /srv/cardano/node-ipc:/ipc \ -p 3001:3001 \ -p 12798:12798 \ ghcr.io/blinklabs-io/cardano-node run @@ -161,9 +161,9 @@ docker run --detach \ -e CARDANO_SHELLEY_KES_KEY=/opt/cardano/config/keys/kes.skey \ -e CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE=/opt/cardano/config/keys/node.cert \ -e CARDANO_SHELLEY_VRF_KEY=/opt/cardano/config/keys/vrf.skey \ - -v /src/cardano/node-keys:/opt/cardano/config/keys \ - -v /src/cardano/node-db:/data/db \ - -v /src/cardano/node-ipc:/ipc \ + -v /srv/cardano/node-keys:/opt/cardano/config/keys \ + -v /srv/cardano/node-db:/data/db \ + -v /srv/cardano/node-ipc:/ipc \ -p 3001:3001 \ -p 12798:12798 \ ghcr.io/blinklabs-io/cardano-node run @@ -193,9 +193,9 @@ for any reason. This will also cause the container to automatically restart after a host reboot, so long as Docker is configured to start on boot. We set variables to configure a block producer and pass the paths to the 3 keys we need. Our node's persistent data and client communication socket are mapped -to `/src/cardano/node-db` and `/src/cardano/node-ipc` on the host, +to `/srv/cardano/node-db` and `/srv/cardano/node-ipc` on the host, respectively. This allows for running applications directly on the host which -may need access to these. We also map `/src/cardano/node-keys` on the host to +may need access to these. We also map `/srv/cardano/node-keys` on the host to a path within the container to support running as a block producer. Last, we add mapping the host's port 12798 to the container 12798, which is the port for exposing the node's metrics in Prometheus format, for monitoring. From cf5a5eab4cffb046f23b2c2358d65132da2a7427 Mon Sep 17 00:00:00 2001 From: Reza Rajan <28660160+rezarajan@users.noreply.github.com> Date: Sat, 20 Sep 2025 19:31:55 +0000 Subject: [PATCH 4/4] feat(entrypoint): include arg parsing for --start-as-non-producing-node Signed-off-by: Reza Rajan <28660160+rezarajan@users.noreply.github.com> --- bin/run-node | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/bin/run-node b/bin/run-node index 807a520..df0ac07 100755 --- a/bin/run-node +++ b/bin/run-node @@ -24,6 +24,7 @@ for i in ${!options[@]}; do --shelley-vrf-key) CARDANO_SHELLEY_VRF_KEY=${v}; found=true ;; --socket-path) CARDANO_SOCKET_PATH=${v}; found=true ;; --topology) CARDANO_TOPOLOGY=${v}; found=true ;; + --start-as-non-producing-node) START_AS_NON_PRODUCING=${v}; found=true ;; esac if [[ ${found} == true ]]; then options[i]=""; @@ -44,6 +45,7 @@ CARDANO_PORT=${CARDANO_PORT:-3001} CARDANO_RTS_OPTS=${CARDANO_RTS_OPTS:--N2 -A64m -I0 -qg -qb --disable-delayed-os-memory-return} CARDANO_SOCKET_PATH=${CARDANO_SOCKET_PATH:-/ipc/node.socket} CARDANO_TOPOLOGY=${CARDANO_TOPOLOGY:-${CARDANO_CONFIG_BASE}/${CARDANO_NETWORK}/topology.json} +START_AS_NON_PRODUCING=${START_AS_NON_PRODUCING:-false} # mithril and devnet case ${CARDANO_NETWORK} in mainnet|preprod) __path=release-${CARDANO_NETWORK} ;; @@ -81,7 +83,6 @@ if [[ -z $ANCILLARY_VERIFICATION_KEY && -f $ANCILLARY_VERIFICATION_KEY_PATH ]]; fi SNAPSHOT_DIGEST=${SNAPSHOT_DIGEST:-latest} RESTORE_SNAPSHOT=${RESTORE_SNAPSHOT:-true} -START_AS_NON_PRODUCING=${START_AS_NON_PRODUCING:-false} echo CARDANO_BIND_ADDR=${CARDANO_BIND_ADDR} echo CARDANO_BLOCK_PRODUCER=${CARDANO_BLOCK_PRODUCER}