From f3d65d7373a54318d6c05aa3fdde55a2d8439bbc Mon Sep 17 00:00:00 2001
From: John Lotoski <john.lotoski@iohk.io>
Date: Wed, 5 Feb 2025 18:56:09 -0600
Subject: [PATCH 01/14] imp: add by-network /opt/cardano/config subdir in oci

---
 nix/docker/README.md              |  4 +-
 nix/docker/context/bin/entrypoint |  6 +--
 nix/docker/context/bin/run-node   |  6 +--
 nix/docker/default.nix            | 71 ++++++++++++++++++++++++-------
 4 files changed, 64 insertions(+), 23 deletions(-)

diff --git a/nix/docker/README.md b/nix/docker/README.md
index 047f813fee9..87977cd74b1 100644
--- a/nix/docker/README.md
+++ b/nix/docker/README.md
@@ -27,8 +27,8 @@ docker run --rm -it --entrypoint=bash \
   ghcr.io/intersectmbo/cardano-node:dev
 
 cardano-node run \
-  --config /opt/cardano/config/mainnet-config.json \
-  --topology /opt/cardano/config/mainnet-topology.json \
+  --config /opt/cardano/config/mainnet/config.json \
+  --topology /opt/cardano/config/mainnet/topology.json \
   --socket-path /opt/cardano/ipc/socket \
   --database-path /opt/cardano/data \
   --host-addr 0.0.0.0 \
diff --git a/nix/docker/context/bin/entrypoint b/nix/docker/context/bin/entrypoint
index 0baefe476e3..4d08684a2a5 100755
--- a/nix/docker/context/bin/entrypoint
+++ b/nix/docker/context/bin/entrypoint
@@ -2,15 +2,15 @@
 
 if [[ -n $NETWORK ]]; then
 
-  exec /usr/local/bin/run-network $@
+  exec /usr/local/bin/run-network "$@"
 
 elif [[ $1 == "run" ]]; then
 
-  exec /usr/local/bin/run-node $@
+  exec /usr/local/bin/run-node "$@"
 
 elif [[ $1 == "cli" ]]; then
 
-  exec /usr/local/bin/run-client $@
+  exec /usr/local/bin/run-client "$@"
 
 else
 
diff --git a/nix/docker/context/bin/run-node b/nix/docker/context/bin/run-node
index a0c1c49e61c..85f704a0653 100755
--- a/nix/docker/context/bin/run-node
+++ b/nix/docker/context/bin/run-node
@@ -9,11 +9,11 @@ echo "Running the cardano node ..."
 CARDANO_CONFIG_BASE="/opt/cardano/config"
 
 if [[ -z $CARDANO_CONFIG ]]; then
-  CARDANO_CONFIG="$CARDANO_CONFIG_BASE/mainnet-config.json"
+  CARDANO_CONFIG="$CARDANO_CONFIG_BASE/mainnet/config.json"
 fi
 
 if [[ -z $CARDANO_TOPOLOGY ]]; then
-  CARDANO_TOPOLOGY="$CARDANO_CONFIG_BASE/mainnet-topology.json"
+  CARDANO_TOPOLOGY="$CARDANO_CONFIG_BASE/mainnet/topology.json"
 fi
 
 if [[ -z $CARDANO_DATABASE_PATH ]]; then
@@ -102,7 +102,7 @@ CARDANO_BLOCK_PRODUCER=$CARDANO_BLOCK_PRODUCER
 CNODE_HOSTNAME="$CARDANO_PUBLIC_IP"
 CNODE_PORT=$CARDANO_PORT
 CUSTOM_PEERS="$CARDANO_CUSTOM_PEERS"
-GENESIS_JSON="$CARDANO_CONFIG_BASE/mainnet-shelley-genesis.json"
+GENESIS_JSON="$CARDANO_CONFIG_BASE/mainnet/shelley-genesis.json"
 TOPOLOGY="$CARDANO_TOPOLOGY"
 LOG_DIR="$CARDANO_LOG_DIR"
 EOF
diff --git a/nix/docker/default.nix b/nix/docker/default.nix
index 3bc5f39c331..2f9452eccd8 100644
--- a/nix/docker/default.nix
+++ b/nix/docker/default.nix
@@ -105,34 +105,75 @@ let
   # The Docker context with static content
   context = ./context;
 
-  # Mainnet configuration used by the 'run' option
-  mainnetConfigFile = builtins.toFile "mainnet-config.json"
-    (builtins.toJSON commonLib.environments.mainnet.nodeConfig);
-  mainnetTopologyFile = commonLib.mkTopology commonLib.environments.mainnet;
+  genCfgs = let
+    environments = lib.getAttrs [ "mainnet" "preprod" "preview" "sanchonet" ] commonLib.environments;
+    cardano-deployment = commonLib.mkConfigHtml environments;
+  in
+    pkgs.runCommand "cardano-html" {} ''
+      mkdir "$out"
+      cp "${cardano-deployment}/index.html" "$out/"
+      cp "${cardano-deployment}/rest-config.json" "$out/"
+
+      ENVS=(${lib.escapeShellArgs (builtins.attrNames environments)})
+      for ENV in "''${ENVS[@]}"; do
+        # Migrate each env from a flat dir to an ENV subdir
+        mkdir -p "$out/config/$ENV"
+        for i in $(find ${cardano-deployment} -type f -name "$ENV-*" -printf "%f\n"); do
+          cp -v "${cardano-deployment}/$i" "$out/config/$ENV/''${i#"$ENV-"}"
+        done
+
+        # Adjust genesis file, config and config-bp refs
+        for i in config config-bp db-sync-config; do
+          if [ -f "$out/config/$ENV/$i.json" ]; then
+            sed -i "s|\"$ENV-|\"|g" "$out/config/$ENV/$i.json"
+          fi
+        done
+
+        # Adjust index.html file refs
+        sed -i "s|$ENV-|config/$ENV/|g" "$out/index.html"
+      done
+    '';
 
 in
   dockerTools.buildImage {
     name = "${repoName}";
     tag = "${gitrev}";
     fromImage = baseImage;
-    created = "now";   # Set creation date to build time. Breaks reproducibility
 
-    # May require system-features = kvm in /etc/nix/nix.conf
-    # https://discourse.nixos.org/t/cannot-build-docker-image/7445
-    # runAsRoot = '' ln -s ${cardano-node} bin/cardano-node '';
+    # Set creation date to build time. Breaks reproducibility
+    created = "now";
 
     extraCommands = ''
-      mkdir -p opt/cardano/config
+      # These directories serve as defaults when the node docker container uses the `run` arg.
+      # Alternatively, when the NETWORK environment variable is set the defaults are different.
+      # TODO: Reduce the confusion on this.
       mkdir -p opt/cardano/data
       mkdir -p opt/cardano/ipc
       mkdir -p opt/cardano/logs
       mkdir -p usr/local/bin
-      ln -s ${mainnetConfigFile} opt/cardano/config/mainnet-config.json
-      ln -s ${mainnetTopologyFile} opt/cardano/config/mainnet-topology.json
-      cp ${runNetwork}/bin/* usr/local/bin
-      cp ${context}/bin/* usr/local/bin
-      ln -s ${cardano-node}/bin/cardano-node usr/local/bin/cardano-node
-      ln -s ${cardano-cli}/bin/cardano-cli usr/local/bin/cardano-cli
+
+      cp -v ${runNetwork}/bin/* usr/local/bin
+      cp -v ${context}/bin/* usr/local/bin
+
+      ln -sv ${cardano-node}/bin/cardano-node usr/local/bin/cardano-node
+      ln -sv ${cardano-cli}/bin/cardano-cli usr/local/bin/cardano-cli
+
+      # Create iohk-nix network configs, organized by network directory.
+      SRC="${genCfgs}"
+      DST="opt/cardano"
+
+      # Make the directory structure with the iohk-nix configs mutable.
+      # This leaves the option to create merged entrypoint configs in the network directory.
+      find "$SRC" -mindepth 1 -type d -exec bash -c "DIR=\"{}\"; mkdir -v -p \"$DST/\''${DIR#${genCfgs}/}\"" \;
+
+      # Keep all base iohk-nix config files immutable via symlinks to nix store.
+      find "$SRC" -mindepth 1 -type f -exec bash -c "FILE=\"{}\"; TGT=\"$DST/\''${FILE#${genCfgs}/}\"; ln -sv \"\$FILE\" \"\$TGT\"" \;
+
+      # Preserve legacy oci config and topo path for backwards compatibility.
+      pushd opt/cardano/config
+      ln -sv mainnet/config.json mainnet-config.json
+      ln -sv mainnet/topology.json mainnet-topology.json
+      popd
     '';
 
     config = {

From f0deeb40c5c996cf33400a6500c570138caa66bf Mon Sep 17 00:00:00 2001
From: John Lotoski <john.lotoski@iohk.io>
Date: Fri, 7 Feb 2025 15:02:13 -0600
Subject: [PATCH 02/14] imp: align node oci scripts mode and custom mode
 defaults

---
 nix/docker/context/bin/run-node | 15 +++++++++++----
 nix/docker/default.nix          | 30 ++++++++++++++++++++++--------
 2 files changed, 33 insertions(+), 12 deletions(-)

diff --git a/nix/docker/context/bin/run-node b/nix/docker/context/bin/run-node
index 85f704a0653..ec38bed745f 100755
--- a/nix/docker/context/bin/run-node
+++ b/nix/docker/context/bin/run-node
@@ -1,6 +1,4 @@
 #!/bin/env bash
-
-# https://vaneyckt.io/posts/safer_bash_scripts_with_set_euxo_pipefail
 set -eo pipefail
 
 echo "Running the cardano node ..."
@@ -16,12 +14,16 @@ if [[ -z $CARDANO_TOPOLOGY ]]; then
   CARDANO_TOPOLOGY="$CARDANO_CONFIG_BASE/mainnet/topology.json"
 fi
 
+# Breaking change from the historical default of: /opt/cardano/data
+# in order to align both the "scripts" and "custom" modes of image operation.
 if [[ -z $CARDANO_DATABASE_PATH ]]; then
-  CARDANO_DATABASE_PATH="/opt/cardano/data"
+  CARDANO_DATABASE_PATH="/opt/cardano/data/db"
 fi
 
+# Breaking change from the historical default of: /opt/cardano/ipc/socket
+# in order to align both the "scripts" and "custom" modes of image operation.
 if [[ -z $CARDANO_SOCKET_PATH ]]; then
-  CARDANO_SOCKET_PATH="/opt/cardano/ipc/socket"
+  CARDANO_SOCKET_PATH="/opt/cardano/ipc/node.socket"
 fi
 
 if [[ -z $CARDANO_LOG_DIR ]]; then
@@ -102,7 +104,12 @@ CARDANO_BLOCK_PRODUCER=$CARDANO_BLOCK_PRODUCER
 CNODE_HOSTNAME="$CARDANO_PUBLIC_IP"
 CNODE_PORT=$CARDANO_PORT
 CUSTOM_PEERS="$CARDANO_CUSTOM_PEERS"
+
+# Breaking change from the historical default of:
+# $CARDANO_CONFIG_BASE/mainnet-shelley-genesis.json in order to align
+# use of the by network organized configuration files.
 GENESIS_JSON="$CARDANO_CONFIG_BASE/mainnet/shelley-genesis.json"
+
 TOPOLOGY="$CARDANO_TOPOLOGY"
 LOG_DIR="$CARDANO_LOG_DIR"
 EOF
diff --git a/nix/docker/default.nix b/nix/docker/default.nix
index 2f9452eccd8..c199971c66a 100644
--- a/nix/docker/default.nix
+++ b/nix/docker/default.nix
@@ -144,17 +144,31 @@ in
     created = "now";
 
     extraCommands = ''
-      # These directories serve as defaults when the node docker container uses the `run` arg.
-      # Alternatively, when the NETWORK environment variable is set the defaults are different.
-      # TODO: Reduce the confusion on this.
-      mkdir -p opt/cardano/data
-      mkdir -p opt/cardano/ipc
-      mkdir -p opt/cardano/logs
+      # The "scripts" operation mode of this image, when the NETWORK env var is
+      # set to a valid network, will use the following default directories
+      # mounted at /:
+      mkdir -p data
+      mkdir -p ipc
+
+      # Similarly, make a root level dir for logs:
+      mkdir -p logs
+
+      # The "custom" operation mode of this image, when the NETWORK env is
+      # unset and `run` is provided as an entrypoint arg, will use the
+      # following default directories.  To reduce confusion caused by default
+      # directory paths varying by mode, symlink these directories to the
+      # "scripts" mode default directories at the root location.  This will
+      # permit use of volume mounts at the root directory location regardless
+      # of which mode the image is operating in.
+      mkdir -p opt/cardano
+      ln -sv /data opt/cardano/data
+      ln -sv /ipc opt/cardano/ipc
+      ln -sv /logs opt/cardano/logs
+
+      # Setup bins
       mkdir -p usr/local/bin
-
       cp -v ${runNetwork}/bin/* usr/local/bin
       cp -v ${context}/bin/* usr/local/bin
-
       ln -sv ${cardano-node}/bin/cardano-node usr/local/bin/cardano-node
       ln -sv ${cardano-cli}/bin/cardano-cli usr/local/bin/cardano-cli
 

From 6c5e2ab31dfebdb5d6e509ad80ce3cfbd2589501 Mon Sep 17 00:00:00 2001
From: John Lotoski <john.lotoski@iohk.io>
Date: Sat, 8 Feb 2025 02:27:31 -0600
Subject: [PATCH 03/14] imp: constrain script envs until iohk-nix deprecated
 envs removed

---
 nix/scripts-submit-api.nix | 9 +++++++--
 nix/scripts.nix            | 9 +++++++--
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/nix/scripts-submit-api.nix b/nix/scripts-submit-api.nix
index 4f31af7e677..46449b68eba 100644
--- a/nix/scripts-submit-api.nix
+++ b/nix/scripts-submit-api.nix
@@ -25,7 +25,12 @@ let
     passthru = { inherit service; };
   };
 
-  scripts = forEnvironments (environment: recurseIntoAttrs {
+  # Until complete removal of some iohk-nix deprecated environments which have
+  # dangling dependencies such as shelley_qa, explicitly declare the
+  # environments we we want included.
+  environments' = pkgs.lib.getAttrs [ "mainnet" "preprod" "preview" "sanchonet" ] environments;
+
+  scripts = forEnvironmentsCustom (environment: recurseIntoAttrs {
     submit-api = mkScript environment;
-  });
+  }) environments';
 in scripts
diff --git a/nix/scripts.nix b/nix/scripts.nix
index f6bdc1184d6..fd5befa6ab0 100644
--- a/nix/scripts.nix
+++ b/nix/scripts.nix
@@ -33,6 +33,11 @@ let
     exePath = "${scriptBin}/bin/cardano-node-${service.environment}";
   };
 
-in forEnvironments (environment: recurseIntoAttrs rec {
+  # Until complete removal of some iohk-nix deprecated environments which have
+  # dangling dependencies such as shelley_qa, explicitly declare the
+  # environments we we want included.
+  environments' = pkgs.lib.getAttrs [ "mainnet" "preprod" "preview" "sanchonet" ] environments;
+
+in forEnvironmentsCustom (environment: recurseIntoAttrs rec {
   node = mkScript environment;
-})
+}) environments'

From ca316522865249c54f0b23dc96816d9e4d332dfc Mon Sep 17 00:00:00 2001
From: John Lotoski <john.lotoski@iohk.io>
Date: Sat, 8 Feb 2025 02:30:33 -0600
Subject: [PATCH 04/14] doc: update the node oci image desc w/ details/examples

---
 nix/docker/default.nix | 76 +++++++++++++++++++++++++++++++++++-------
 1 file changed, 64 insertions(+), 12 deletions(-)

diff --git a/nix/docker/default.nix b/nix/docker/default.nix
index c199971c66a..7ba2d4d1b61 100644
--- a/nix/docker/default.nix
+++ b/nix/docker/default.nix
@@ -6,23 +6,75 @@
 #   nix build .#dockerImage/node
 #   docker load -i result
 #
-# To launch with pre-loaded configuration, using the NETWORK env.
+#
+# Scripts Mode:
+#
+# To launch cardano-node with pre-loaded configuration, "scripts" mode,
+# use the NETWORK env variable to declare an existing cardano network name.
+#
 # An example using a docker volume to persist state:
 #
-#   docker run -v /data -e NETWORK=mainnet ghcr.io/intersectmbo/cardano-node
+#   docker run -v data:/data -e NETWORK=mainnet ghcr.io/intersectmbo/cardano-node
+#
+# In "scripts" mode, default state directories include /{data,ipc,logs}, with
+# /data/db being the default database state location.
+#
+#
+# Custom Mode:
+#
+# To launch cardano-node with a custom configuration, "custom" mode, provide
+# entrypoint args starting with `run` and:
+#   * Leave the NETWORK env variable unset,
+#   * Optionally include additional cardano-node args to the entrypoint afer `run`,
+#   * Optionally include environment variables interpreted by `nix/docker/context/bin/run-node`
+#
+# For example, launch a custom cardano-node using cardano-node args and a
+# local configuration mapped into the container:
 #
-# Provide a complete command otherwise:
+#   docker run \
+#     -v "$PWD/config/cardano:/config" \
+#     ghcr.io/intersectmbo/cardano-node \
+#     run \
+#     --config /config/mainnet/config.json \
+#     --topology /config/mainnet/topology.json \
+#     --database-path /data/db
 #
-#   docker run -v $PWD/configuration/cardano:/configuration \
-#     ghcr.io/intersectmbo/cardano-node run \
-#      --config /configuration/mainnet-config.yaml \
-#      --topology /configuration/mainnet-topology.json \
-#      --database-path /db
+# Custom mode may also leverage standard mainnet or testnet network config
+# files found at /opt/cardano/config and organized under a subdirectory of the
+# network name.  For example, to utilize standard configs for preview network,
+# but modify the cardano-node listening port:
 #
-# Mount a volume into /ipc for establishing cross-container communication via node.socket
+#   docker run \
+#     -v "$PWD/preprod-data:/data" \
+#     -e CARDANO_CONFIG="/opt/cardano/config/preprod/config.json" \
+#     -e CARDANO_TOPOLOGY="/opt/cardano/config/preprod/topology.json" \
+#     -e CARDANO_PORT="6001" \
+#     ghcr.io/intersectmbo/cardano-node \
+#     run
+#
+# In "custom" mode, default state directories include
+# /opt/cardano/{data,ipc,logs} and with /opt/cardano/data/db being the default
+# database state location.  Standard network config files can be found under
+# /opt/cardano/config.
+#
+#
+# Bind Mounting Considerations:
+#
+# For "custom" mode, the /opt/cardano/{data,ipc,logs} default state directories have been
+# symlinked to the "scripts" mode default state directories of /{data,ipc,logs}
+# respectively.  This makes bind mounting easier when switching between
+# "scripts" and "custom" container modes as bind mounting any of the root
+# default state directory locations, /{data,ipc,logs}, will work for both modes.
+#
+#
+# Cardano-node socket sharing:
+#
+# To share a cardano-node socket with a different container, a volume can be made
+# for establishing cross-container communication:
 #
 #   docker run -v node-ipc:/ipc -e NETWORK=mainnet ghcr.io/intersectmbo/cardano-node
 #   docker run -v node-ipc:/ipc -e NETWORK=mainnet ghcr.io/intersectmbo/some-node-client
+#
 ############################################################################
 
 { pkgs
@@ -106,15 +158,15 @@ let
   context = ./context;
 
   genCfgs = let
-    environments = lib.getAttrs [ "mainnet" "preprod" "preview" "sanchonet" ] commonLib.environments;
-    cardano-deployment = commonLib.mkConfigHtml environments;
+    environments' = lib.getAttrs [ "mainnet" "preprod" "preview" "sanchonet" ] commonLib.environments;
+    cardano-deployment = commonLib.mkConfigHtml environments';
   in
     pkgs.runCommand "cardano-html" {} ''
       mkdir "$out"
       cp "${cardano-deployment}/index.html" "$out/"
       cp "${cardano-deployment}/rest-config.json" "$out/"
 
-      ENVS=(${lib.escapeShellArgs (builtins.attrNames environments)})
+      ENVS=(${lib.escapeShellArgs (builtins.attrNames environments')})
       for ENV in "''${ENVS[@]}"; do
         # Migrate each env from a flat dir to an ENV subdir
         mkdir -p "$out/config/$ENV"

From aa516495a3c11c504e9ad9da051003a745051acf Mon Sep 17 00:00:00 2001
From: John Lotoski <john.lotoski@iohk.io>
Date: Mon, 10 Feb 2025 17:53:37 -0600
Subject: [PATCH 05/14] imp: align oci cardano-submit-api paths w/ node image,
 update docs

---
 docker-compose.yml        |  2 +-
 nix/docker/default.nix    | 19 ++++++---
 nix/docker/submit-api.nix | 90 ++++++++++++++++++++++++++-------------
 nix/pkgs.nix              |  2 +-
 4 files changed, 74 insertions(+), 39 deletions(-)

diff --git a/docker-compose.yml b/docker-compose.yml
index 1055d4506d4..0b10259ddb2 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -19,7 +19,7 @@ services:
     depends_on:
       - cardano-node
     volumes:
-      - node-ipc:/node-ipc
+      - node-ipc:/ipc
     ports:
       - 8090:8090
     restart: on-failure
diff --git a/nix/docker/default.nix b/nix/docker/default.nix
index 7ba2d4d1b61..3fc252a6422 100644
--- a/nix/docker/default.nix
+++ b/nix/docker/default.nix
@@ -12,9 +12,12 @@
 # To launch cardano-node with pre-loaded configuration, "scripts" mode,
 # use the NETWORK env variable to declare an existing cardano network name.
 #
-# An example using a docker volume to persist state:
+# An example using a docker named volume to persist state:
 #
-#   docker run -v data:/data -e NETWORK=mainnet ghcr.io/intersectmbo/cardano-node
+#   docker run \
+#     -v data:/data \
+#     -e NETWORK=mainnet \
+#     ghcr.io/intersectmbo/cardano-node
 #
 # In "scripts" mode, default state directories include /{data,ipc,logs}, with
 # /data/db being the default database state location.
@@ -128,14 +131,16 @@ let
         utillinux         # System utilities for Linux
       ];
     };
-    # set up /tmp (override with TMPDIR variable)
+
+    # Set up /tmp (override with TMPDIR variable)
     extraCommands = ''
       mkdir -m 0777 tmp
     '';
   };
 
-  # Image with all iohk-nix network configs or utilizes a configuration volume mount
-  # To choose a network, use `-e NETWORK testnet`
+  # For "script" mode, generate scripts for iohk-nix networks which can be
+  # utilized by setting the environment NETWORK variable to the desired
+  # network in the docker command: `-e NETWORK <network>`
   clusterStatements = lib.concatStringsSep "\n" (lib.mapAttrsToList (env: scripts: let
     scriptBin = scripts.${script};
     in ''
@@ -154,7 +159,7 @@ let
     fi
   '';
 
-  # The Docker context with static content
+  # The docker context with static content
   context = ./context;
 
   genCfgs = let
@@ -192,7 +197,7 @@ in
     tag = "${gitrev}";
     fromImage = baseImage;
 
-    # Set creation date to build time. Breaks reproducibility
+    # Set creation date to build time. Breaks reproducibility.
     created = "now";
 
     extraCommands = ''
diff --git a/nix/docker/submit-api.nix b/nix/docker/submit-api.nix
index 85808a85c8f..e51cdf3419a 100644
--- a/nix/docker/submit-api.nix
+++ b/nix/docker/submit-api.nix
@@ -6,26 +6,48 @@
 #   nix run .#dockerImage/submit-api
 #   docker load -i result
 #
-# cardano-submit-api
-#   To launch with provided mainnet configuration
+# Scripts Mode:
 #
-#     docker run -e NETWORK=mainnet ghcr.io/intersectmbo/cardano-submit-api:<TAG>
+# To launch cardano-submit-api with pre-loaded configuration, "scripts" mode,
+# use the NETWORK env variable to declare an existing cardano network name.
 #
-#   To launch with provided testnet configuration
+# An example using a docker named volume to share ipc socket state:
 #
-#     docker run -e NETWORK=testnet ghcr.io/intersectmbo/cardano-submit-api:<TAG>
+#   docker run \
+#     -v node-ipc:/ipc \
+#     -e NETWORK=mainnet \
+#     ghcr.io/intersectmbo/cardano-submit-api
 #
-#   Provide a complete command otherwise:
+# In "scripts" mode, the node.socket file is expected at /ipc.
 #
-#     docker run -v $PWD/config.yaml:/config.yaml ghcr.io/intersectmbo/cardano-submit-api:<TAG> \
-#       --config /config.yaml --mainnet --socket-path /node-ipc/node.socket
 #
-# See the docker-compose.yml for demonstration of using Docker secrets instead of mounting a pgpass
+# Custom Mode:
+#
+# To launch cardano-submit-api with a custom configuration, "custom" mode,
+# leave the NETWORK env variable unset and provide a complete set of
+# cardano-submit-api args to the entrypoint.
+#
+# For example:
+#
+#   docker run \
+#     -v $PWD/config.json:/config.json \
+#     ghcr.io/intersectmbo/cardano-submit-api \
+#     --config /config.json \
+#     --mainnet \
+#     --socket-path /ipc/node.socket
+#
+# See the docker-compose.yml for a demonstration of cardano-node and
+# cardano-submit-api together.
+#
+#
+# Bind Mounting Considerations:
+#
+# In the container a /node-ipc directory is symlinked to /ipc both align the
+# default ipc socket state directory in both the cardano-node and
+# cardano-submit-api images and remain backward compatible.
 #
 ############################################################################
-
 { pkgs
-, commonLib
 , dockerTools
 
 # The main contents of the image.
@@ -36,7 +58,6 @@
 
 # Other things to include in the image.
 , bashInteractive
-, buildPackages
 , cacert
 , coreutils
 , curl
@@ -75,14 +96,16 @@ let
         utillinux         # System utilities for Linux
       ];
     };
-    # set up /tmp (override with TMPDIR variable)
+
+    # Set up /tmp (override with TMPDIR variable)
     extraCommands = ''
       mkdir -m 0777 tmp
     '';
   };
 
-  # Image with all iohk-nix network configs or utilizes a configuration volume mount
-  # To choose a network, use `-e NETWORK testnet`
+  # For "script" mode, generate scripts for iohk-nix networks which can be
+  # utilized by setting the environment NETWORK variable to the desired
+  # network in the docker command: `-e NETWORK <network>`
   clusterStatements = lib.concatStringsSep "\n" (lib.mapAttrsToList (env: scripts: let
     scriptBin = scripts.${script};
     in ''
@@ -90,22 +113,31 @@ let
         exec ${scriptBin}/bin/${scriptBin.name} $@
     '') scripts);
 
-  nodeDockerImage = let
-    entry-point = writeScriptBin "entry-point" ''
-      #!${runtimeShell}
-      if [[ -z "$NETWORK" ]]; then
-        exec ${pkgs.${exe}}/bin/${exe} $@
-      ${clusterStatements}
-      else
-        echo "Managed configuration for network "$NETWORK" does not exist"
-      fi
-    '';
+  entry-point = writeScriptBin "entry-point" ''
+    #!${runtimeShell}
+    if [[ -z "$NETWORK" ]]; then
+      exec ${pkgs.${exe}}/bin/${exe} $@
+    ${clusterStatements}
+    else
+      echo "Managed configuration for network "$NETWORK" does not exist"
+    fi
+  '';
 
   in dockerTools.buildImage {
     name = "${repoName}";
-    fromImage = baseImage;
     tag = "${gitrev}";
-    created = "now";   # Set creation date to build time. Breaks reproducibility
+    fromImage = baseImage;
+
+    # Set creation date to build time. Breaks reproducibility.
+    created = "now";
+
+    extraCommands = ''
+      # The "scripts" operation mode of this image, when the NETWORK env var is
+      # set to a valid network, will use the following default directories
+      # mounted at /:
+      mkdir -p ipc
+      ln -sv ipc node-ipc
+    '';
 
     copyToRoot = pkgs.buildEnv {
       name = "image-root";
@@ -119,6 +151,4 @@ let
         "${toString scripts.mainnet.${script}.passthru.service.port}/tcp" = {};
       };
     };
-  };
-
-in nodeDockerImage
+  }
diff --git a/nix/pkgs.nix b/nix/pkgs.nix
index 63dd1685d28..a875d6c2c90 100644
--- a/nix/pkgs.nix
+++ b/nix/pkgs.nix
@@ -113,7 +113,7 @@ in with final;
   submitApiDockerImage =
     let
       defaultConfig = {
-        socketPath = "/node-ipc/node.socket";
+        socketPath = "/ipc/node.socket";
         listenAddress = "0.0.0.0";
       };
     in

From ce311b51eccc198350f8427ce9bc342fa4ffc91c Mon Sep 17 00:00:00 2001
From: John Lotoski <john.lotoski@iohk.io>
Date: Mon, 10 Feb 2025 21:52:28 -0600
Subject: [PATCH 06/14] imp: add oci merge mode for node config/topo

---
 nix/docker/context/bin/entrypoint | 78 +++++++++++++++++++++++++++++--
 nix/docker/default.nix            | 18 ++++++-
 2 files changed, 90 insertions(+), 6 deletions(-)

diff --git a/nix/docker/context/bin/entrypoint b/nix/docker/context/bin/entrypoint
index 4d08684a2a5..8fd78db282c 100755
--- a/nix/docker/context/bin/entrypoint
+++ b/nix/docker/context/bin/entrypoint
@@ -1,20 +1,90 @@
 #!/bin/env bash
 
+[[ -n $DEBUG ]] && set -x
+
+# If the NETWORK env var is set to a valid cardano network, pre-defined
+# configuration will be utilized.
 if [[ -n $NETWORK ]]; then
 
-  exec /usr/local/bin/run-network "$@"
+  # If either CARDANO_<CONFIG|TOPOLOGY>_JSON_MERGE env vars are set, iohk-nix
+  # pre-defined configuration will be used as a starting point and merged with
+  # custom configuration provided as json in the environment variable(s).
+  if [[ -n $CARDANO_CONFIG_JSON_MERGE || -n $CARDANO_CONFIG_TOPOLOGY_MERGE ]]; then
 
-elif [[ $1 == "run" ]]; then
+    # Do a recursive deep merge of iohk-nix NETWORK config and/or topology with
+    # the supplied json merge environment variable(s).
+    #
+    # In a jq deep merge, arrays are replaced, primitive values in the second
+    # object override the first, different types for the same key result in
+    # full replacement and null values persist.
+    CFG="/opt/cardano/config"
+    if [[ -n $CARDANO_CONFIG_JSON_MERGE ]]; then
+      jq -S \
+        --argjson deepMerge "$CARDANO_CONFIG_JSON_MERGE" \
+        '. * $deepMerge' \
+        < "$CFG/$NETWORK/config.json" \
+        > "$CFG/$NETWORK/config-merged.json"
+      export CARDANO_CONFIG="$CFG/$NETWORK/config-merged.json"
+    else
+      export CARDANO_CONFIG="$CFG/$NETWORK/config.json"
+    fi
+
+    if [[ -n $CARDANO_TOPOLOGY_JSON_MERGE ]]; then
+      jq -S \
+        --argjson deepMerge "$CARDANO_TOPOLOGY_JSON_MERGE" \
+        '. * $deepMerge' \
+        < "$CFG/$NETWORK/topology.json" \
+        > "$CFG/$NETWORK/topology-merged.json"
+      export CARDANO_TOPOLOGY="$CFG/$NETWORK/topology-merged.json"
+    else
+      export CARDANO_TOPOLOGY="$CFG/$NETWORK/topology.json"
+    fi
+
+    if [[ -n $DEBUG ]]; then
+      echo "Cardano config is:"
+      cat "$CARDANO_CONFIG"
+      echo
+      echo "Cardano topology is:"
+      cat "$CARDANO_TOPOLOGY"
+      echo
+    fi
 
+    # Run cardano-node using iohk-nix base config merged with provided custom
+    # config for the requested NETWORK.
+    unset NETWORK
+    if [[ $1 == "run" ]]; then
+      exec /usr/local/bin/run-node "$@"
+    else
+      exec /usr/local/bin/run-node run "$@"
+    fi
+
+  else
+    # Run cardano-node using "scripts" mode for the requested NETWORK.
+    exec /usr/local/bin/run-network "$@"
+  fi
+
+elif [[ $1 == "run" ]]; then
+  # Run cardano-node using "custom" mode.
   exec /usr/local/bin/run-node "$@"
 
 elif [[ $1 == "cli" ]]; then
-
+  # Run cardano-cli with the provided entrypoint args
   exec /usr/local/bin/run-client "$@"
 
 else
 
-  echo "Nothing to do! Perhaps try [run|cli], or set NETWORK environment variable."
+  echo "Nothing to do! Perhaps try one of:"
+  echo
+  echo "  * Setting the NETWORK env var to a valid cardano network, such as mainnet."
+  echo "    * Optionally provide CARDANO_CONFIG_JSON_MERGE and/or CARDANO_TOPOLOGY_JSON_MERGE"
+  echo "      to run cardano-node with custom config deep merged to the base NETWORK config."
+  echo
+  echo "  * Leave the NETWORK env var unset and provide entrypoint args starting with \"run\" and:"
+  echo "    * Optionally include environment variables interpreted by nix/docker/context/bin/run-node."
+  echo "    * Optionally include additional cardano-node args to the entrypoint afer \"run\"."
+  echo
+  echo "  * Leave the NETWORK env var unset and provide entrypoint args"
+  echo "    starting with \"cli\" following by cardano-cli command args."
   exit 1
 
 fi
diff --git a/nix/docker/default.nix b/nix/docker/default.nix
index 3fc252a6422..ee583fe8f4f 100644
--- a/nix/docker/default.nix
+++ b/nix/docker/default.nix
@@ -28,8 +28,8 @@
 # To launch cardano-node with a custom configuration, "custom" mode, provide
 # entrypoint args starting with `run` and:
 #   * Leave the NETWORK env variable unset,
-#   * Optionally include additional cardano-node args to the entrypoint afer `run`,
-#   * Optionally include environment variables interpreted by `nix/docker/context/bin/run-node`
+#   * Optionally include additional cardano-node args to the entrypoint afer "run",
+#   * Optionally include environment variables interpreted by nix/docker/context/bin/run-node
 #
 # For example, launch a custom cardano-node using cardano-node args and a
 # local configuration mapped into the container:
@@ -61,6 +61,17 @@
 # /opt/cardano/config.
 #
 #
+# Merge Mode:
+#
+# With the NETWORK env variable set and one or both of
+# CARDANO_<CONFIG|TOPOLOGY>_JSON_MERGE env variables set and containing valid
+# json, cardano-node will run with deep merged base NETWORK config and json
+# merge config.
+#
+# Optional env variables and cardano-node args which can be used in custom mode
+# can also be used in this mode.
+#
+#
 # Bind Mounting Considerations:
 #
 # For "custom" mode, the /opt/cardano/{data,ipc,logs} default state directories have been
@@ -101,6 +112,7 @@
 , iana-etc
 , iproute
 , iputils
+, jq
 , socat
 , utillinux
 , lib
@@ -127,6 +139,7 @@ let
         iana-etc          # IANA protocol and port number assignments
         iproute           # Utilities for controlling TCP/IP networking
         iputils           # Useful utilities for Linux networking
+        jq                # Lightweight and flexible command-line JSON processor
         socat             # Utility for bidirectional data transfer
         utillinux         # System utilities for Linux
       ];
@@ -228,6 +241,7 @@ in
       cp -v ${context}/bin/* usr/local/bin
       ln -sv ${cardano-node}/bin/cardano-node usr/local/bin/cardano-node
       ln -sv ${cardano-cli}/bin/cardano-cli usr/local/bin/cardano-cli
+      ln -sv ${jq}/bin/jq usr/local/bin/jq
 
       # Create iohk-nix network configs, organized by network directory.
       SRC="${genCfgs}"

From 94cab88f87d4acf6d808c555d73c46b245d77164 Mon Sep 17 00:00:00 2001
From: John Lotoski <john.lotoski@iohk.io>
Date: Mon, 10 Feb 2025 21:53:32 -0600
Subject: [PATCH 07/14] doc: prefer root mountpoints for oci examples

---
 nix/docker/README.md              | 18 +++++++++---------
 nix/docker/context/bin/run-client |  6 ++++--
 2 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/nix/docker/README.md b/nix/docker/README.md
index 87977cd74b1..841184bf3d1 100644
--- a/nix/docker/README.md
+++ b/nix/docker/README.md
@@ -23,14 +23,14 @@ fi
 
 # Bash into the node to look around
 docker run --rm -it --entrypoint=bash \
-  -v node-data:/opt/cardano/data \
+  -v node-data:/data \
   ghcr.io/intersectmbo/cardano-node:dev
 
 cardano-node run \
   --config /opt/cardano/config/mainnet/config.json \
   --topology /opt/cardano/config/mainnet/topology.json \
-  --socket-path /opt/cardano/ipc/socket \
-  --database-path /opt/cardano/data \
+  --socket-path /ipc/node.socket \
+  --database-path /data/db \
   --host-addr 0.0.0.0 \
   --port 3001
 ```
@@ -51,7 +51,7 @@ Run -e NETWORK=mainnet and check graceful shutdown SIGINT with -it
 docker run --rm -it \
   -p 3001:3001 \
   -e NETWORK=mainnet \
-  -v node-data:/data/db \
+  -v node-data:/data \
   ghcr.io/intersectmbo/cardano-node:dev
 ```
 
@@ -63,7 +63,7 @@ docker run --detach \
   --name=relay \
   -p 3001:3001 \
   -e NETWORK=mainnet \
-  -v node-data:/data/db \
+  -v node-data:/data \
   ghcr.io/intersectmbo/cardano-node:dev
 
 docker logs -f relay
@@ -76,7 +76,7 @@ Check graceful shutdown SIGINT with -it
 ```
 docker run --rm -it \
   -p 3001:3001 \
-  -v node-data:/opt/cardano/data \
+  -v node-data:/data \
   ghcr.io/intersectmbo/cardano-node:dev run
 ```
 
@@ -87,8 +87,8 @@ docker rm -f relay
 docker run --detach \
   --name=relay \
   -p 3001:3001 \
-  -v node-data:/opt/cardano/data \
-  -v node-ipc:/opt/cardano/ipc \
+  -v node-data:/data \
+  -v node-ipc:/ipc \
   ghcr.io/intersectmbo/cardano-node:dev run
 
 docker logs -f relay
@@ -98,7 +98,7 @@ docker logs -f relay
 
 ```
 alias cardano-cli="docker run --rm -it \
-  -v node-ipc:/opt/cardano/ipc \
+  -v node-ipc:/ipc \
   ghcr.io/intersectmbo/cardano-node:dev cli"
 
 cardano-cli query tip --mainnet
diff --git a/nix/docker/context/bin/run-client b/nix/docker/context/bin/run-client
index d7042110a56..78e2d98e969 100755
--- a/nix/docker/context/bin/run-client
+++ b/nix/docker/context/bin/run-client
@@ -4,7 +4,9 @@
 shift
 
 if [[ -z $CARDANO_NODE_SOCKET_PATH ]]; then
-  export CARDANO_NODE_SOCKET_PATH="/opt/cardano/ipc/socket"
+  # Breaking change from the historical default of: /opt/cardano/ipc/socket
+  # in order to align both the "scripts" and "custom" modes of image operation.
+  export CARDANO_NODE_SOCKET_PATH="/opt/cardano/ipc/node.socket"
 fi
 
-/usr/local/bin/cardano-cli $@
+/usr/local/bin/cardano-cli "$@"

From 8b2a773040ba45ce15ff7afea52108180c81aaca Mon Sep 17 00:00:00 2001
From: John Lotoski <john.lotoski@iohk.io>
Date: Mon, 10 Feb 2025 22:06:07 -0600
Subject: [PATCH 08/14] shellcheck: oci script compliance, typo fix

---
 nix/docker/context/bin/entrypoint |  2 +-
 nix/docker/context/bin/run-node   | 60 +++++++++++++++++--------------
 2 files changed, 34 insertions(+), 28 deletions(-)

diff --git a/nix/docker/context/bin/entrypoint b/nix/docker/context/bin/entrypoint
index 8fd78db282c..666f09e32de 100755
--- a/nix/docker/context/bin/entrypoint
+++ b/nix/docker/context/bin/entrypoint
@@ -9,7 +9,7 @@ if [[ -n $NETWORK ]]; then
   # If either CARDANO_<CONFIG|TOPOLOGY>_JSON_MERGE env vars are set, iohk-nix
   # pre-defined configuration will be used as a starting point and merged with
   # custom configuration provided as json in the environment variable(s).
-  if [[ -n $CARDANO_CONFIG_JSON_MERGE || -n $CARDANO_CONFIG_TOPOLOGY_MERGE ]]; then
+  if [[ -n $CARDANO_CONFIG_JSON_MERGE || -n $CARDANO_TOPOLOGY_JSON_MERGE ]]; then
 
     # Do a recursive deep merge of iohk-nix NETWORK config and/or topology with
     # the supplied json merge environment variable(s).
diff --git a/nix/docker/context/bin/run-node b/nix/docker/context/bin/run-node
index ec38bed745f..8536d8960f5 100755
--- a/nix/docker/context/bin/run-node
+++ b/nix/docker/context/bin/run-node
@@ -3,6 +3,8 @@ set -eo pipefail
 
 echo "Running the cardano node ..."
 
+[[ -n $DEBUG ]] && set -x
+
 # Define a few defaults
 CARDANO_CONFIG_BASE="/opt/cardano/config"
 
@@ -107,7 +109,7 @@ CUSTOM_PEERS="$CARDANO_CUSTOM_PEERS"
 
 # Breaking change from the historical default of:
 # $CARDANO_CONFIG_BASE/mainnet-shelley-genesis.json in order to align
-# use of the by network organized configuration files.
+# with network organized configuration files.
 GENESIS_JSON="$CARDANO_CONFIG_BASE/mainnet/shelley-genesis.json"
 
 TOPOLOGY="$CARDANO_TOPOLOGY"
@@ -121,17 +123,19 @@ EOF
 #
 runRelayNode () {
 
-  effopts=(--config $CARDANO_CONFIG \
-    --topology $CARDANO_TOPOLOGY \
-    --database-path $CARDANO_DATABASE_PATH \
-    --socket-path $CARDANO_SOCKET_PATH \
-    --host-addr $CARDANO_BIND_ADDR \
-    --port $CARDANO_PORT)
+  effopts=(
+    "--config" "$CARDANO_CONFIG" \
+    "--topology" "$CARDANO_TOPOLOGY" \
+    "--database-path" "$CARDANO_DATABASE_PATH" \
+    "--socket-path" "$CARDANO_SOCKET_PATH" \
+    "--host-addr" "$CARDANO_BIND_ADDR" \
+    "--port" "$CARDANO_PORT"
+  )
 
-  effopts+=(${options[@]})
+  effopts+=("${options[@]}")
 
-  echo "cardano-node run ${effopts[@]}"
-  exec /usr/local/bin/cardano-node run ${effopts[@]}
+  echo "cardano-node run ${effopts[*]}"
+  exec /usr/local/bin/cardano-node run "${effopts[@]}"
 }
 
 #####################################################################
@@ -140,20 +144,22 @@ runRelayNode () {
 #
 runBlockProducerNode () {
 
-  effopts=(--config $CARDANO_CONFIG \
-    --topology $CARDANO_TOPOLOGY \
-    --database-path $CARDANO_DATABASE_PATH \
-    --socket-path $CARDANO_SOCKET_PATH \
-    --host-addr $CARDANO_BIND_ADDR \
-    --port $CARDANO_PORT \
-    --shelley-kes-key $CARDANO_SHELLEY_KES_KEY \
-    --shelley-vrf-key $CARDANO_SHELLEY_VRF_KEY \
-    --shelley-operational-certificate $CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE)
-
-  effopts+=(${options[@]})
-
-  echo "cardano-node run ${effopts[@]}"
-  exec /usr/local/bin/cardano-node run ${effopts[@]}
+  effopts=(
+    "--config" "$CARDANO_CONFIG" \
+    "--topology" "$CARDANO_TOPOLOGY" \
+    "--database-path" "$CARDANO_DATABASE_PATH" \
+    "--socket-path" "$CARDANO_SOCKET_PATH" \
+    "--host-addr" "$CARDANO_BIND_ADDR" \
+    "--port" "$CARDANO_PORT" \
+    "--shelley-kes-key" "$CARDANO_SHELLEY_KES_KEY" \
+    "--shelley-vrf-key" "$CARDANO_SHELLEY_VRF_KEY" \
+    "--shelley-operational-certificate" "$CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE"
+  )
+
+  effopts+=("${options[@]}")
+
+  echo "cardano-node run ${effopts[*]}"
+  exec /usr/local/bin/cardano-node run "${effopts[@]}"
 }
 
 # Shift the first option by one index
@@ -161,7 +167,7 @@ shift
 
 # Override default values with explicit options
 
-options=($@)
+options=("$@")
 
 for i in "${!options[@]}"
 do
@@ -194,9 +200,9 @@ printRunEnv
 writeRootEnv
 
 # The IPC socket dir is not created on demand
-mkdir -p `dirname ${CARDANO_SOCKET_PATH}`
+mkdir -p "$(dirname "$CARDANO_SOCKET_PATH")"
 
-if [[ ${CARDANO_BLOCK_PRODUCER} == true ]]; then
+if [[ $CARDANO_BLOCK_PRODUCER == true ]]; then
   runBlockProducerNode
 else
   runRelayNode

From 25ccc087e9c2d3fdf07c43b015a7b34754ee127a Mon Sep 17 00:00:00 2001
From: John Lotoski <john.lotoski@iohk.io>
Date: Tue, 11 Feb 2025 14:45:33 -0600
Subject: [PATCH 09/14] imp: add oci merged mode cfg check, doc updates

---
 nix/docker/context/bin/entrypoint | 45 ++++++++++++++++++++++---------
 nix/docker/context/bin/run-client |  4 ++-
 nix/docker/context/bin/run-node   |  7 +++--
 nix/docker/default.nix            | 36 ++++++++++++++++++-------
 nix/docker/submit-api.nix         |  6 +++--
 5 files changed, 71 insertions(+), 27 deletions(-)

diff --git a/nix/docker/context/bin/entrypoint b/nix/docker/context/bin/entrypoint
index 666f09e32de..7011656170e 100755
--- a/nix/docker/context/bin/entrypoint
+++ b/nix/docker/context/bin/entrypoint
@@ -3,21 +3,30 @@
 [[ -n $DEBUG ]] && set -x
 
 # If the NETWORK env var is set to a valid cardano network, pre-defined
-# configuration will be utilized.
+# configuration will be used.
 if [[ -n $NETWORK ]]; then
 
   # If either CARDANO_<CONFIG|TOPOLOGY>_JSON_MERGE env vars are set, iohk-nix
-  # pre-defined configuration will be used as a starting point and merged with
-  # custom configuration provided as json in the environment variable(s).
+  # pre-defined NETWORK configuration will be used as a starting point and
+  # merged with custom configuration provided as json in the environment
+  # variable(s).
   if [[ -n $CARDANO_CONFIG_JSON_MERGE || -n $CARDANO_TOPOLOGY_JSON_MERGE ]]; then
 
+    CFG="/opt/cardano/config"
+    if ! [[ -f $CFG/$NETWORK/config.json && -f $CFG/$NETWORK/topology.json ]]; then
+      echo "Network \"$NETWORK\" doesn't appear to have expected base configuration available at:"
+      echo "  $CFG/$NETWORK/{config,topology}.json"
+      echo
+      echo "Please check that the NETWORK environment variable is set to a valid cardano network name."
+      exit 1
+    fi
+
     # Do a recursive deep merge of iohk-nix NETWORK config and/or topology with
     # the supplied json merge environment variable(s).
     #
     # In a jq deep merge, arrays are replaced, primitive values in the second
     # object override the first, different types for the same key result in
     # full replacement and null values persist.
-    CFG="/opt/cardano/config"
     if [[ -n $CARDANO_CONFIG_JSON_MERGE ]]; then
       jq -S \
         --argjson deepMerge "$CARDANO_CONFIG_JSON_MERGE" \
@@ -41,10 +50,10 @@ if [[ -n $NETWORK ]]; then
     fi
 
     if [[ -n $DEBUG ]]; then
-      echo "Cardano config is:"
+      echo "Cardano config in merge mode is:"
       cat "$CARDANO_CONFIG"
       echo
-      echo "Cardano topology is:"
+      echo "Cardano topology in merge mode is:"
       cat "$CARDANO_TOPOLOGY"
       echo
     fi
@@ -73,18 +82,28 @@ elif [[ $1 == "cli" ]]; then
 
 else
 
-  echo "Nothing to do! Perhaps try one of:"
+  echo "Nothing to do!  Available modes of operation are:"
   echo
-  echo "  * Setting the NETWORK env var to a valid cardano network, such as mainnet."
-  echo "    * Optionally provide CARDANO_CONFIG_JSON_MERGE and/or CARDANO_TOPOLOGY_JSON_MERGE"
-  echo "      to run cardano-node with custom config deep merged to the base NETWORK config."
+  echo "Scripts mode:"
+  echo "  * Set the NETWORK env var to a valid cardano network, such as mainnet to use default network config."
   echo
+  echo "Custom mode:"
   echo "  * Leave the NETWORK env var unset and provide entrypoint args starting with \"run\" and:"
-  echo "    * Optionally include environment variables interpreted by nix/docker/context/bin/run-node."
-  echo "    * Optionally include additional cardano-node args to the entrypoint afer \"run\"."
+  echo "    * Optionally set environment variables interpreted by /usr/local/bin/run-node."
+  echo "    * Optionally include additional cardano-node args to the entrypoint after \"run\"."
+  echo
+  echo "Merge mode:"
+  echo "  * Set the NETWORK env var to a valid cardano network, such as mainnet, and"
+  echo "    set CARDANO_CONFIG_JSON_MERGE and/or CARDANO_TOPOLOGY_JSON_MERGE env vars"
+  echo "    with valid json to run cardano-node with deep merged base NETWORK and custom config."
+  echo "  * The extra environment variables and cardano-node args that can be used in custom mode"
+  echo "    are also available in merge mode."
   echo
+  echo "CLI mode:"
   echo "  * Leave the NETWORK env var unset and provide entrypoint args"
-  echo "    starting with \"cli\" following by cardano-cli command args."
+  echo "    starting with \"cli\" followed by cardano-cli command args."
+  echo "  * A docker volume mount to the cardano-node ipc socket will need to be included, example:"
+  echo "      -v node-ipc:/ipc"
   exit 1
 
 fi
diff --git a/nix/docker/context/bin/run-client b/nix/docker/context/bin/run-client
index 78e2d98e969..dc785d0f8b8 100755
--- a/nix/docker/context/bin/run-client
+++ b/nix/docker/context/bin/run-client
@@ -1,12 +1,14 @@
 #!/bin/env bash
 
+[[ -n $DEBUG ]] && set -x
+
 # Shift the first option by one index
 shift
 
 if [[ -z $CARDANO_NODE_SOCKET_PATH ]]; then
   # Breaking change from the historical default of: /opt/cardano/ipc/socket
   # in order to align both the "scripts" and "custom" modes of image operation.
-  export CARDANO_NODE_SOCKET_PATH="/opt/cardano/ipc/node.socket"
+  export CARDANO_NODE_SOCKET_PATH="/ipc/node.socket"
 fi
 
 /usr/local/bin/cardano-cli "$@"
diff --git a/nix/docker/context/bin/run-node b/nix/docker/context/bin/run-node
index 8536d8960f5..2009d48713c 100755
--- a/nix/docker/context/bin/run-node
+++ b/nix/docker/context/bin/run-node
@@ -18,16 +18,19 @@ fi
 
 # Breaking change from the historical default of: /opt/cardano/data
 # in order to align both the "scripts" and "custom" modes of image operation.
+# Prefer root mountpoints for consistency via symlink /opt/cardano/data -> /data
 if [[ -z $CARDANO_DATABASE_PATH ]]; then
-  CARDANO_DATABASE_PATH="/opt/cardano/data/db"
+  CARDANO_DATABASE_PATH="/data/db"
 fi
 
 # Breaking change from the historical default of: /opt/cardano/ipc/socket
 # in order to align both the "scripts" and "custom" modes of image operation.
+# Prefer root mountpoints for consistency via symlink /opt/cardano/ipc -> /ipc
 if [[ -z $CARDANO_SOCKET_PATH ]]; then
-  CARDANO_SOCKET_PATH="/opt/cardano/ipc/node.socket"
+  CARDANO_SOCKET_PATH="/ipc/node.socket"
 fi
 
+# Prefer root mountpoints for consistency via symlink /opt/cardano/ipc -> /ipc
 if [[ -z $CARDANO_LOG_DIR ]]; then
   CARDANO_LOG_DIR="/opt/cardano/logs"
 fi
diff --git a/nix/docker/default.nix b/nix/docker/default.nix
index ee583fe8f4f..0b680046774 100644
--- a/nix/docker/default.nix
+++ b/nix/docker/default.nix
@@ -26,10 +26,11 @@
 # Custom Mode:
 #
 # To launch cardano-node with a custom configuration, "custom" mode, provide
-# entrypoint args starting with `run` and:
-#   * Leave the NETWORK env variable unset,
-#   * Optionally include additional cardano-node args to the entrypoint afer "run",
+# entrypoint args starting with "run" and:
+#   * Leave the NETWORK env variable unset
+#   * Optionally include additional cardano-node args to the entrypoint afer "run"
 #   * Optionally include environment variables interpreted by nix/docker/context/bin/run-node
+#     from the cardano-node repo, or /usr/local/bin/run-node in the container
 #
 # For example, launch a custom cardano-node using cardano-node args and a
 # local configuration mapped into the container:
@@ -44,7 +45,7 @@
 #
 # Custom mode may also leverage standard mainnet or testnet network config
 # files found at /opt/cardano/config and organized under a subdirectory of the
-# network name.  For example, to utilize standard configs for preview network,
+# network name.  For example, to utilize standard configs for preprod network,
 # but modify the cardano-node listening port:
 #
 #   docker run \
@@ -56,9 +57,10 @@
 #     run
 #
 # In "custom" mode, default state directories include
-# /opt/cardano/{data,ipc,logs} and with /opt/cardano/data/db being the default
-# database state location.  Standard network config files can be found under
-# /opt/cardano/config.
+# /opt/cardano/{data,ipc,logs}, with /opt/cardano/data/db being the default
+# database state location.  These state directories are symlinked to root in the container:
+# /opt/cardano/{data,ipc,logs} -> /{data,ipc,logs} for more consistency between modes.
+# Standard network config files can be found under /opt/cardano/config.
 #
 #
 # Merge Mode:
@@ -72,6 +74,22 @@
 # can also be used in this mode.
 #
 #
+# CLI Mode:
+#
+# To run cardano-cli, leave the NETWORK env variable unset and provide
+# entrypoint args starting with "cli" followed by cardano-cli command args.
+# The cardano-node ipc socket state will need to be provided in cli mode.
+#
+# An example using a docker named volume to share cardano-node ipc socket state:
+#
+#   docker run \
+#     -v node-ipc:/ipc \
+#     ghcr.io/intersectmbo/cardano-node \
+#     cli \
+#     query tip \
+#     --mainnet
+#
+#
 # Bind Mounting Considerations:
 #
 # For "custom" mode, the /opt/cardano/{data,ipc,logs} default state directories have been
@@ -224,7 +242,7 @@ in
       mkdir -p logs
 
       # The "custom" operation mode of this image, when the NETWORK env is
-      # unset and `run` is provided as an entrypoint arg, will use the
+      # unset and "run" is provided as an entrypoint arg, will use the
       # following default directories.  To reduce confusion caused by default
       # directory paths varying by mode, symlink these directories to the
       # "scripts" mode default directories at the root location.  This will
@@ -248,7 +266,7 @@ in
       DST="opt/cardano"
 
       # Make the directory structure with the iohk-nix configs mutable.
-      # This leaves the option to create merged entrypoint configs in the network directory.
+      # This allows the option to create merged entrypoint configs in the network directory.
       find "$SRC" -mindepth 1 -type d -exec bash -c "DIR=\"{}\"; mkdir -v -p \"$DST/\''${DIR#${genCfgs}/}\"" \;
 
       # Keep all base iohk-nix config files immutable via symlinks to nix store.
diff --git a/nix/docker/submit-api.nix b/nix/docker/submit-api.nix
index e51cdf3419a..bc1a740571a 100644
--- a/nix/docker/submit-api.nix
+++ b/nix/docker/submit-api.nix
@@ -42,9 +42,9 @@
 #
 # Bind Mounting Considerations:
 #
-# In the container a /node-ipc directory is symlinked to /ipc both align the
+# In the container a /node-ipc directory is symlinked to /ipc both to align the
 # default ipc socket state directory in both the cardano-node and
-# cardano-submit-api images and remain backward compatible.
+# cardano-submit-api images and remain backwards compatible.
 #
 ############################################################################
 { pkgs
@@ -136,6 +136,8 @@ let
       # set to a valid network, will use the following default directories
       # mounted at /:
       mkdir -p ipc
+
+      # Symlink /node-ipc -> /ipc for consistency and backwards compatability
       ln -sv ipc node-ipc
     '';
 

From 7a184fd9e01213a2660fbab732828434fc2faf11 Mon Sep 17 00:00:00 2001
From: John Lotoski <john.lotoski@iohk.io>
Date: Tue, 11 Feb 2025 16:11:19 -0600
Subject: [PATCH 10/14] docs: refactor the nix readme, docker readme, docker
 nix comments

---
 nix/README.md             |  12 ++-
 nix/docker/README.md      | 193 +++++++++++++++++++++++++++++++++-----
 nix/docker/default.nix    | 104 +-------------------
 nix/docker/submit-api.nix |  45 +--------
 4 files changed, 182 insertions(+), 172 deletions(-)

diff --git a/nix/README.md b/nix/README.md
index adb27469298..84a1244b8e2 100644
--- a/nix/README.md
+++ b/nix/README.md
@@ -1,12 +1,16 @@
 # Nix dependencies
 
-The nix build use the new flake format to manage dependencies. To add flake support to your native nix setup please see https://nixos.wiki/wiki/Flakes.
+The nix build uses the new flake format to manage dependencies. To add flake support to your native nix setup please see https://nixos.wiki/wiki/Flakes.
 
-Cardano-node nix build depends primarily on [haskell.nix](https://github.com/input-output-hk/haskell.nix) and secondarily, for some utilities, on [iohk-nix](https://github.com/input-output-hk/iohk-nix/).
+The cardano-node nix build depends primarily on [haskell.nix](https://github.com/input-output-hk/haskell.nix) and secondarily, for some utilities, on [iohk-nix](https://github.com/input-output-hk/iohk-nix/).
 
 Both can be updated with:
 
 ```
-nix flake lock --update-input haskellNix
-nix flake lock --update-input iohkNix
+nix flake update haskellNix
+nix flake update iohkNix
 ```
+
+# Building Cardano Node with Nix
+
+See: https://github.com/input-output-hk/cardano-node-wiki/wiki/building-the-node-using-nix
diff --git a/nix/docker/README.md b/nix/docker/README.md
index 841184bf3d1..dbd9b07c827 100644
--- a/nix/docker/README.md
+++ b/nix/docker/README.md
@@ -1,13 +1,20 @@
+# Building the Cardano Node and Cardano Submit API Docker Images
+To build and load the oci images into the Docker engine, the most
+basic commands are:
+```
+# Build and load the cardano-node oci image
+nix build .#dockerImage/node
+docker load -i result
 
-## Build Cardano Node + Image
-
-https://github.com/input-output-hk/cardano-node-wiki/wiki/building-the-node-using-nix
-
+# Build and load the cardano-submit-api oci image
+nix build .#dockerImage/submit-api
+docker load -i result
 ```
-# Build + Install the cardano node
-nix build .#mainnet/node -o ~/bin/cardano-node
 
-# Build + Install the cardano Docker image from bash shell
+From a bash shell, the following command example for the cardano-node image
+offers a little more convenience by tagging the loaded image with "dev" and
+also tagging with a git tag if one is present at the build git commit hash.
+```
 nix build .#dockerImage/node \
   && RES=$(docker load -i result) \
   && LOADED="${RES##Loaded image: }" \
@@ -20,33 +27,168 @@ if [ $? -eq 0 ]; then
   echo "Current tag: $GITTAG"
   docker tag ghcr.io/intersectmbo/cardano-node:dev "ghcr.io/intersectmbo/cardano-node:$GITTAG"
 fi
+```
 
-# Bash into the node to look around
-docker run --rm -it --entrypoint=bash \
-  -v node-data:/data \
+To take a quick look around in the cardano-node container:
+```
+docker run \
+  --rm -it --entrypoint=bash \
   ghcr.io/intersectmbo/cardano-node:dev
+```
 
-cardano-node run \
-  --config /opt/cardano/config/mainnet/config.json \
-  --topology /opt/cardano/config/mainnet/topology.json \
-  --socket-path /ipc/node.socket \
-  --database-path /data/db \
-  --host-addr 0.0.0.0 \
-  --port 3001
+A similar command can be run to look around the cardano-submit-api container.
+
+
+# Cardano Node Image Operation
+## Scripts Mode
+To launch cardano-node with pre-loaded configuration, "scripts" mode,
+use the `NETWORK` env variable to declare an existing cardano network name.
+
+An example using a docker named volume to persist state to the host:
 ```
+docker run \
+  -v data:/data \
+  -e NETWORK=mainnet \
+  ghcr.io/intersectmbo/cardano-node:dev
+```
+
+In "scripts" mode, default state directories include `/{data,ipc,logs}`, with
+`/data/db` being the default database state location.
 
-## Manual Testing
 
+## Custom Mode
+To launch cardano-node with a custom configuration, "custom" mode, provide
+entrypoint args starting with `run` and:
+* Leave the `NETWORK` env variable unset
+* Optionally include additional cardano-node args to the entrypoint after `run`
+* Optionally include environment variables interpreted by [nix/docker/context/bin/run-node](context/bin/run-node),
+  or `/usr/local/bin/run-node` in the container
+
+For example, launch a custom cardano-node container using cardano-node args and
+a local configuration mapped into the container:
+```
+docker run \
+  -v "$PWD/config/cardano:/config" \
+  ghcr.io/intersectmbo/cardano-node:dev \
+  run \
+  --config /config/mainnet/config.json \
+  --topology /config/mainnet/topology.json \
+  --database-path /data/db
+```
+
+Custom mode may also leverage standard mainnet or testnet network config
+files found at `/opt/cardano/config` and organized under a subdirectory of the
+network's name.  For example, to utilize standard configs for preprod network,
+but modify the cardano-node listening port:
+```
+  docker run \
+    -v "$PWD/preprod-data:/data" \
+    -e CARDANO_CONFIG="/opt/cardano/config/preprod/config.json" \
+    -e CARDANO_TOPOLOGY="/opt/cardano/config/preprod/topology.json" \
+    -e CARDANO_PORT="6001" \
+    ghcr.io/intersectmbo/cardano-node:dev \
+    run
+```
+
+In "custom" mode, default state directories include
+`/opt/cardano/{data,ipc,logs}`, with `/opt/cardano/data/db` being the default
+database state location.  These state directories are symlinked to root in the container:
+`/opt/cardano/{data,ipc,logs} -> /{data,ipc,logs}` for more consistency between modes.
+Standard network config files can be found under `/opt/cardano/config`.
+
+
+## Merge Mode
+With the `NETWORK` env variable set and one or both of
+`CARDANO_<CONFIG|TOPOLOGY>_JSON_MERGE` env variables set and containing valid
+json, cardano-node will run with deep merged base `NETWORK` config and json
+merge config.
+
+Optional env variables and cardano-node args which can be used in custom mode
+can also be used in this mode.
+
+
+## CLI Mode
+To run cardano-cli, leave the `NETWORK` env variable unset and provide
+entrypoint args starting with `cli` followed by cardano-cli command args.
+The cardano-node ipc socket state will need to be provided in cli mode.
+
+An example using a docker named volume to share cardano-node ipc socket state:
+```
+docker run \
+  -v node-ipc:/ipc \
+  ghcr.io/intersectmbo/cardano-node:dev \
+  cli \
+  query tip \
+  --mainnet
+```
+
+## Bind Mounting Considerations
+For "custom" mode, the `/opt/cardano/{data,ipc,logs}` default state directories have been
+symlinked to the "scripts" mode default state directories of `/{data,ipc,logs}`
+respectively.  This makes bind mounting easier when switching between
+"scripts" and "custom" container modes as bind mounting any of the root
+default state directory locations, `/{data,ipc,logs}`, will work for both modes.
+
+
+## Cardano-node socket sharing
+To share a cardano-node socket with a different container, a volume can be made
+for establishing cross-container communication:
+```
+docker run -v node-ipc:/ipc -e NETWORK=mainnet ghcr.io/intersectmbo/cardano-node:dev
+docker run -v node-ipc:/ipc -e NETWORK=mainnet ghcr.io/intersectmbo/some-node-client
+```
+
+# Cardano Submit API Image Operation
+## Scripts Mode
+To launch cardano-submit-api with pre-loaded configuration, "scripts" mode,
+use the `NETWORK` env variable to declare an existing cardano network name.
+
+An example using a docker named volume to share ipc socket state:
+```
+docker run \
+  -v node-ipc:/ipc \
+  -e NETWORK=mainnet \
+  ghcr.io/intersectmbo/cardano-submit-api:dev
+```
+In "scripts" mode, the `node.socket` file is expected at `/ipc`.
+
+
+## Custom Mode
+To launch cardano-submit-api with a custom configuration, "custom" mode,
+leave the `NETWORK` env variable unset and provide a complete set of
+cardano-submit-api args to the entrypoint.
+
+For example:
+```
+docker run \
+  -v node-ipc:/ipc \
+  -v $PWD/config.json:/config.json \
+  ghcr.io/intersectmbo/cardano-submit-api:dev \
+  --config /config.json \
+  --mainnet \
+  --socket-path /ipc/node.socket
+```
+
+See the [docker-compose.yml](../../docker-compose.yml) file for a demonstration
+of cardano-node and cardano-submit-api together.
+
+
+## Bind Mounting Considerations:
+In the cardano-submit-api container a `/node-ipc` directory is symlinked to `/ipc`
+both to align the default ipc socket state directory in both the cardano-node
+and cardano-submit-api images and to remain backwards compatible.
+
+
+# Manual Testing
 1. Run -e NETWORK=mainnet and check graceful shutdown SIGINT with -it
 2. Run -e NETWORK=mainnet and check graceful shutdown SIGTERM with --detach
 3. Run without -e NETWORK and check graceful shutdown SIGINT with -it
 4. Run without -e NETWORK and check graceful shutdown SIGTERM with --detach
 5. Check cardano-cli access
 
-### Run with NETWORK
 
+## Run with NETWORK
 Run -e NETWORK=mainnet and check graceful shutdown SIGINT with -it
-
 ```
 docker run --rm -it \
   -p 3001:3001 \
@@ -56,7 +198,6 @@ docker run --rm -it \
 ```
 
 Run -e NETWORK=mainnet and check graceful shutdown SIGTERM with --detach
-
 ```
 docker rm -f relay
 docker run --detach \
@@ -69,10 +210,9 @@ docker run --detach \
 docker logs -f relay
 ```
 
-### Run without NETWORK
 
+## Run without NETWORK
 Check graceful shutdown SIGINT with -it
-
 ```
 docker run --rm -it \
   -p 3001:3001 \
@@ -81,7 +221,6 @@ docker run --rm -it \
 ```
 
 Check graceful shutdown SIGTERM with --detach
-
 ```
 docker rm -f relay
 docker run --detach \
@@ -94,10 +233,12 @@ docker run --detach \
 docker logs -f relay
 ```
 
-### Check cardano-cli
 
+## Check cardano-cli
+Check successful cardano-cli query
 ```
-alias cardano-cli="docker run --rm -it \
+alias cardano-cli="docker run \
+  --rm -it \
   -v node-ipc:/ipc \
   ghcr.io/intersectmbo/cardano-node:dev cli"
 
diff --git a/nix/docker/default.nix b/nix/docker/default.nix
index 0b680046774..aa56f656011 100644
--- a/nix/docker/default.nix
+++ b/nix/docker/default.nix
@@ -1,112 +1,14 @@
 ############################################################################
-# Docker image builder
+# Docker image builder for cardano-node
 #
 # To build and load into the Docker engine:
 #
 #   nix build .#dockerImage/node
 #   docker load -i result
 #
+# Include `-L` in the nix build command args to see build logs.
 #
-# Scripts Mode:
-#
-# To launch cardano-node with pre-loaded configuration, "scripts" mode,
-# use the NETWORK env variable to declare an existing cardano network name.
-#
-# An example using a docker named volume to persist state:
-#
-#   docker run \
-#     -v data:/data \
-#     -e NETWORK=mainnet \
-#     ghcr.io/intersectmbo/cardano-node
-#
-# In "scripts" mode, default state directories include /{data,ipc,logs}, with
-# /data/db being the default database state location.
-#
-#
-# Custom Mode:
-#
-# To launch cardano-node with a custom configuration, "custom" mode, provide
-# entrypoint args starting with "run" and:
-#   * Leave the NETWORK env variable unset
-#   * Optionally include additional cardano-node args to the entrypoint afer "run"
-#   * Optionally include environment variables interpreted by nix/docker/context/bin/run-node
-#     from the cardano-node repo, or /usr/local/bin/run-node in the container
-#
-# For example, launch a custom cardano-node using cardano-node args and a
-# local configuration mapped into the container:
-#
-#   docker run \
-#     -v "$PWD/config/cardano:/config" \
-#     ghcr.io/intersectmbo/cardano-node \
-#     run \
-#     --config /config/mainnet/config.json \
-#     --topology /config/mainnet/topology.json \
-#     --database-path /data/db
-#
-# Custom mode may also leverage standard mainnet or testnet network config
-# files found at /opt/cardano/config and organized under a subdirectory of the
-# network name.  For example, to utilize standard configs for preprod network,
-# but modify the cardano-node listening port:
-#
-#   docker run \
-#     -v "$PWD/preprod-data:/data" \
-#     -e CARDANO_CONFIG="/opt/cardano/config/preprod/config.json" \
-#     -e CARDANO_TOPOLOGY="/opt/cardano/config/preprod/topology.json" \
-#     -e CARDANO_PORT="6001" \
-#     ghcr.io/intersectmbo/cardano-node \
-#     run
-#
-# In "custom" mode, default state directories include
-# /opt/cardano/{data,ipc,logs}, with /opt/cardano/data/db being the default
-# database state location.  These state directories are symlinked to root in the container:
-# /opt/cardano/{data,ipc,logs} -> /{data,ipc,logs} for more consistency between modes.
-# Standard network config files can be found under /opt/cardano/config.
-#
-#
-# Merge Mode:
-#
-# With the NETWORK env variable set and one or both of
-# CARDANO_<CONFIG|TOPOLOGY>_JSON_MERGE env variables set and containing valid
-# json, cardano-node will run with deep merged base NETWORK config and json
-# merge config.
-#
-# Optional env variables and cardano-node args which can be used in custom mode
-# can also be used in this mode.
-#
-#
-# CLI Mode:
-#
-# To run cardano-cli, leave the NETWORK env variable unset and provide
-# entrypoint args starting with "cli" followed by cardano-cli command args.
-# The cardano-node ipc socket state will need to be provided in cli mode.
-#
-# An example using a docker named volume to share cardano-node ipc socket state:
-#
-#   docker run \
-#     -v node-ipc:/ipc \
-#     ghcr.io/intersectmbo/cardano-node \
-#     cli \
-#     query tip \
-#     --mainnet
-#
-#
-# Bind Mounting Considerations:
-#
-# For "custom" mode, the /opt/cardano/{data,ipc,logs} default state directories have been
-# symlinked to the "scripts" mode default state directories of /{data,ipc,logs}
-# respectively.  This makes bind mounting easier when switching between
-# "scripts" and "custom" container modes as bind mounting any of the root
-# default state directory locations, /{data,ipc,logs}, will work for both modes.
-#
-#
-# Cardano-node socket sharing:
-#
-# To share a cardano-node socket with a different container, a volume can be made
-# for establishing cross-container communication:
-#
-#   docker run -v node-ipc:/ipc -e NETWORK=mainnet ghcr.io/intersectmbo/cardano-node
-#   docker run -v node-ipc:/ipc -e NETWORK=mainnet ghcr.io/intersectmbo/some-node-client
-#
+# See the nix/docker/README.md file for details on modes of operation.
 ############################################################################
 
 { pkgs
diff --git a/nix/docker/submit-api.nix b/nix/docker/submit-api.nix
index bc1a740571a..3bc39f57724 100644
--- a/nix/docker/submit-api.nix
+++ b/nix/docker/submit-api.nix
@@ -1,51 +1,14 @@
 ############################################################################
-# Docker image builder
+# Docker image builder for cardano-submit-api
 #
 # To build and load into the Docker engine:
 #
-#   nix run .#dockerImage/submit-api
+#   nix build -L .#dockerImage/submit-api
 #   docker load -i result
 #
-# Scripts Mode:
-#
-# To launch cardano-submit-api with pre-loaded configuration, "scripts" mode,
-# use the NETWORK env variable to declare an existing cardano network name.
-#
-# An example using a docker named volume to share ipc socket state:
-#
-#   docker run \
-#     -v node-ipc:/ipc \
-#     -e NETWORK=mainnet \
-#     ghcr.io/intersectmbo/cardano-submit-api
-#
-# In "scripts" mode, the node.socket file is expected at /ipc.
-#
-#
-# Custom Mode:
-#
-# To launch cardano-submit-api with a custom configuration, "custom" mode,
-# leave the NETWORK env variable unset and provide a complete set of
-# cardano-submit-api args to the entrypoint.
-#
-# For example:
-#
-#   docker run \
-#     -v $PWD/config.json:/config.json \
-#     ghcr.io/intersectmbo/cardano-submit-api \
-#     --config /config.json \
-#     --mainnet \
-#     --socket-path /ipc/node.socket
-#
-# See the docker-compose.yml for a demonstration of cardano-node and
-# cardano-submit-api together.
-#
-#
-# Bind Mounting Considerations:
-#
-# In the container a /node-ipc directory is symlinked to /ipc both to align the
-# default ipc socket state directory in both the cardano-node and
-# cardano-submit-api images and remain backwards compatible.
+# Include `-L` in the nix build command args to see build logs.
 #
+# See the nix/docker/README.md file for details on modes of operation.
 ############################################################################
 { pkgs
 , dockerTools

From 32a61c4c999fa2d6dc1780ce6c4cadb65c983867 Mon Sep 17 00:00:00 2001
From: John Lotoski <john.lotoski@iohk.io>
Date: Tue, 11 Feb 2025 16:59:28 -0600
Subject: [PATCH 11/14] doc: add a node oci merge mode example

---
 nix/docker/README.md | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/nix/docker/README.md b/nix/docker/README.md
index dbd9b07c827..d8384279bc7 100644
--- a/nix/docker/README.md
+++ b/nix/docker/README.md
@@ -1,4 +1,4 @@
-# Building the Cardano Node and Cardano Submit API Docker Images
+# Building Node and Submit API Images
 To build and load the oci images into the Docker engine, the most
 basic commands are:
 ```
@@ -12,7 +12,7 @@ docker load -i result
 ```
 
 From a bash shell, the following command example for the cardano-node image
-offers a little more convenience by tagging the loaded image with "dev" and
+offers a little more convenience by tagging the loaded image with `dev` and
 also tagging with a git tag if one is present at the build git commit hash.
 ```
 nix build .#dockerImage/node \
@@ -106,13 +106,25 @@ merge config.
 Optional env variables and cardano-node args which can be used in custom mode
 can also be used in this mode.
 
+An example:
+```
+docker run \
+  -v $PWD/node-ipc:/ipc \
+  -v $(pwd)/mainnet-data:/data \
+  -e NETWORK=mainnet \
+  -e CARDANO_CONFIG_JSON_MERGE='{"MaxConcurrencyBulkSync": 2}' \
+  -e CARDANO_TOPOLOGY_JSON_MERGE='{"useLedgerAfterSlot": 147000000}' \
+  ghcr.io/intersectmbo/cardano-node:dev
+```
 
 ## CLI Mode
 To run cardano-cli, leave the `NETWORK` env variable unset and provide
 entrypoint args starting with `cli` followed by cardano-cli command args.
 The cardano-node ipc socket state will need to be provided in cli mode.
 
-An example using a docker named volume to share cardano-node ipc socket state:
+An example using a docker named volume to share cardano-node ipc socket state
+follows. In this example, another container running cardano-node and also
+sharing ipc socket state to the same named volume would already be running.
 ```
 docker run \
   -v node-ipc:/ipc \
@@ -122,6 +134,10 @@ docker run \
   --mainnet
 ```
 
+See the [Cardano-node socket sharing](#cardano-node-socket-sharing) section for
+more on sharing ipc state between containers.
+
+
 ## Bind Mounting Considerations
 For "custom" mode, the `/opt/cardano/{data,ipc,logs}` default state directories have been
 symlinked to the "scripts" mode default state directories of `/{data,ipc,logs}`
@@ -150,6 +166,7 @@ docker run \
   -e NETWORK=mainnet \
   ghcr.io/intersectmbo/cardano-submit-api:dev
 ```
+
 In "scripts" mode, the `node.socket` file is expected at `/ipc`.
 
 

From 8a3c96ca05270fcf4b9fe967662f86be47b6c64a Mon Sep 17 00:00:00 2001
From: John Lotoski <john.lotoski@iohk.io>
Date: Wed, 12 Feb 2025 15:29:35 -0600
Subject: [PATCH 12/14] env: rm sanchonet scripts/release-bin/docker env for
 stoppage

---
 nix/binary-release.nix     | 2 +-
 nix/docker/default.nix     | 2 +-
 nix/scripts-submit-api.nix | 2 +-
 nix/scripts.nix            | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/nix/binary-release.nix b/nix/binary-release.nix
index aa61fdcfa44..38240c0b8ba 100644
--- a/nix/binary-release.nix
+++ b/nix/binary-release.nix
@@ -18,7 +18,7 @@ let
   name = "cardano-node-${version}-${platform}";
 
   environments = lib.getAttrs
-    [ "mainnet" "preprod" "preview" "sanchonet" ]
+    [ "mainnet" "preprod" "preview" ]
     pkgs.cardanoLib.environments;
 
 
diff --git a/nix/docker/default.nix b/nix/docker/default.nix
index aa56f656011..c892e5daa21 100644
--- a/nix/docker/default.nix
+++ b/nix/docker/default.nix
@@ -96,7 +96,7 @@ let
   context = ./context;
 
   genCfgs = let
-    environments' = lib.getAttrs [ "mainnet" "preprod" "preview" "sanchonet" ] commonLib.environments;
+    environments' = lib.getAttrs [ "mainnet" "preprod" "preview" ] commonLib.environments;
     cardano-deployment = commonLib.mkConfigHtml environments';
   in
     pkgs.runCommand "cardano-html" {} ''
diff --git a/nix/scripts-submit-api.nix b/nix/scripts-submit-api.nix
index 46449b68eba..7a549fa8673 100644
--- a/nix/scripts-submit-api.nix
+++ b/nix/scripts-submit-api.nix
@@ -28,7 +28,7 @@ let
   # Until complete removal of some iohk-nix deprecated environments which have
   # dangling dependencies such as shelley_qa, explicitly declare the
   # environments we we want included.
-  environments' = pkgs.lib.getAttrs [ "mainnet" "preprod" "preview" "sanchonet" ] environments;
+  environments' = pkgs.lib.getAttrs [ "mainnet" "preprod" "preview" ] environments;
 
   scripts = forEnvironmentsCustom (environment: recurseIntoAttrs {
     submit-api = mkScript environment;
diff --git a/nix/scripts.nix b/nix/scripts.nix
index fd5befa6ab0..9188f04c200 100644
--- a/nix/scripts.nix
+++ b/nix/scripts.nix
@@ -36,7 +36,7 @@ let
   # Until complete removal of some iohk-nix deprecated environments which have
   # dangling dependencies such as shelley_qa, explicitly declare the
   # environments we we want included.
-  environments' = pkgs.lib.getAttrs [ "mainnet" "preprod" "preview" "sanchonet" ] environments;
+  environments' = pkgs.lib.getAttrs [ "mainnet" "preprod" "preview" ] environments;
 
 in forEnvironmentsCustom (environment: recurseIntoAttrs rec {
   node = mkScript environment;

From aac6a9d1d220bf8fa5c8949d32b4ef34ffdd77ac Mon Sep 17 00:00:00 2001
From: John Lotoski <john.lotoski@iohk.io>
Date: Wed, 12 Feb 2025 16:18:45 -0600
Subject: [PATCH 13/14] docs: add a pre-existing state section to the docker
 readme

---
 nix/docker/README.md | 34 +++++++++++++++++++++++++++++-----
 1 file changed, 29 insertions(+), 5 deletions(-)

diff --git a/nix/docker/README.md b/nix/docker/README.md
index d8384279bc7..048390ef51d 100644
--- a/nix/docker/README.md
+++ b/nix/docker/README.md
@@ -82,7 +82,7 @@ network's name.  For example, to utilize standard configs for preprod network,
 but modify the cardano-node listening port:
 ```
   docker run \
-    -v "$PWD/preprod-data:/data" \
+    -v preprod-data:/data \
     -e CARDANO_CONFIG="/opt/cardano/config/preprod/config.json" \
     -e CARDANO_TOPOLOGY="/opt/cardano/config/preprod/topology.json" \
     -e CARDANO_PORT="6001" \
@@ -104,13 +104,14 @@ json, cardano-node will run with deep merged base `NETWORK` config and json
 merge config.
 
 Optional env variables and cardano-node args which can be used in custom mode
-can also be used in this mode.
+can also be used in this mode.  Merge mode uses the same default state
+directories as custom mode.
 
 An example:
 ```
 docker run \
-  -v $PWD/node-ipc:/ipc \
-  -v $(pwd)/mainnet-data:/data \
+  -v node-ipc:/ipc \
+  -v mainnet-data:/data \
   -e NETWORK=mainnet \
   -e CARDANO_CONFIG_JSON_MERGE='{"MaxConcurrencyBulkSync": 2}' \
   -e CARDANO_TOPOLOGY_JSON_MERGE='{"useLedgerAfterSlot": 147000000}' \
@@ -146,7 +147,7 @@ respectively.  This makes bind mounting easier when switching between
 default state directory locations, `/{data,ipc,logs}`, will work for both modes.
 
 
-## Cardano-node socket sharing
+## Cardano-node Socket Sharing
 To share a cardano-node socket with a different container, a volume can be made
 for establishing cross-container communication:
 ```
@@ -154,6 +155,29 @@ docker run -v node-ipc:/ipc -e NETWORK=mainnet ghcr.io/intersectmbo/cardano-node
 docker run -v node-ipc:/ipc -e NETWORK=mainnet ghcr.io/intersectmbo/some-node-client
 ```
 
+
+## Pre-existing State Mounting
+If pre-existing cardano-node database state for a network of interest is
+available on the host, but not yet available in the container, the state can be
+mapped into the container with a local volume driver bind mount.
+
+An example using preprod state from a `$PWD/preprod-data` path follows.  Recall
+from above that scripts, custom and merge modes use a default database state
+location of `/data/db` either directly or indirectly by symlink, so the host
+`$PWD/preprod-data` directory should contain the database state under a `db`
+subdir.
+```
+docker run \
+  -v "$PWD/preprod-data:/data" \
+  -e NETWORK=preprod \
+  ghcr.io/intersectmbo/cardano-node:dev
+```
+
+Pre-existing host state may be obtained by any number of means such as host
+cardano-node service, rsync'd known good state from a remote, [Mithril
+snapshot](https://mithril.network/doc/) or other out-of-band methods.
+
+
 # Cardano Submit API Image Operation
 ## Scripts Mode
 To launch cardano-submit-api with pre-loaded configuration, "scripts" mode,

From 9acaffed7380ac7e44784b71ba03e9238ccea64d Mon Sep 17 00:00:00 2001
From: John Lotoski <john.lotoski@iohk.io>
Date: Wed, 12 Feb 2025 18:24:30 -0600
Subject: [PATCH 14/14] oci: switch node to cfg cp to avoid broken symlinks
 from host

---
 nix/docker/README.md   | 30 ++++++++++++++++++++++++++++++
 nix/docker/default.nix | 13 +++++++------
 2 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/nix/docker/README.md b/nix/docker/README.md
index 048390ef51d..50e77c7a9d8 100644
--- a/nix/docker/README.md
+++ b/nix/docker/README.md
@@ -178,6 +178,36 @@ cardano-node service, rsync'd known good state from a remote, [Mithril
 snapshot](https://mithril.network/doc/) or other out-of-band methods.
 
 
+## Host Mount Image Network Configs
+To host mount and explore the image configuration files found under
+`/opt/cardano` a new named docker volume can be created.  Docker will
+initialize the new named volume with the contents of the container.
+
+An example would be:
+```
+docker run \
+  -v opt-cardano:/opt/cardano \
+  ghcr.io/intersectmbo/cardano-node:dev
+```
+
+The above command will create a new named volume of `opt-cardano` with the
+container contents of `/opt/cardano` and print some image mode information
+before exiting.  If there is already a named volume of `opt-cardano`, simply
+select a different name, or allow a random name assignment by dropping the
+`$NAME:` suffix of the `-v` option.
+
+Exploring the configuration contents from the host after creating the named
+volume can be done with commands such as:
+```
+docker volume ls
+
+# Use the "Mountpoint" value in this command below
+docker volume inspect opt-cardano
+
+sudo tree /var/lib/docker/volumes/opt-cardano/_data
+```
+
+
 # Cardano Submit API Image Operation
 ## Scripts Mode
 To launch cardano-submit-api with pre-loaded configuration, "scripts" mode,
diff --git a/nix/docker/default.nix b/nix/docker/default.nix
index c892e5daa21..1cc75c9f953 100644
--- a/nix/docker/default.nix
+++ b/nix/docker/default.nix
@@ -167,12 +167,13 @@ in
       SRC="${genCfgs}"
       DST="opt/cardano"
 
-      # Make the directory structure with the iohk-nix configs mutable.
-      # This allows the option to create merged entrypoint configs in the network directory.
-      find "$SRC" -mindepth 1 -type d -exec bash -c "DIR=\"{}\"; mkdir -v -p \"$DST/\''${DIR#${genCfgs}/}\"" \;
-
-      # Keep all base iohk-nix config files immutable via symlinks to nix store.
-      find "$SRC" -mindepth 1 -type f -exec bash -c "FILE=\"{}\"; TGT=\"$DST/\''${FILE#${genCfgs}/}\"; ln -sv \"\$FILE\" \"\$TGT\"" \;
+      # Make the directory structure with the iohk-nix configs mutable. This
+      # enables creation of merge mode entrypoint configs in the respective
+      # NETWORK directory. Keep config files as read-only copies from the nix
+      # store instead of direct symlinks.  This avoids volume mount failures
+      # caused by broken symlinks as seen from the host.
+      cp -R "$SRC"/* "$DST"
+      find "$DST" -mindepth 1 -type d -exec bash -c "chmod 0755 {}" \;
 
       # Preserve legacy oci config and topo path for backwards compatibility.
       pushd opt/cardano/config