doc: update the node oci image desc w/ details/examples

Author: johnalotoski

Diff for: 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"