refactor: enhance documentation and streamline scripts

Author: gustavovalverde

docker/Dockerfile

@@ -46,9 +46,10 @@ ENV CARGO_HOME=${CARGO_HOME}
 ARG FEATURES
 ENV FEATURES=${FEATURES}
 
-ARG SHORT_SHA
-# If this is not set, it must be an empty string, so Zebra can try an alternative git commit source:
+# If this is not set, it must be an empty string, so Zebra can try an
+# alternative git commit source:
 # https://github.com/ZcashFoundation/zebra/blob/9ebd56092bcdfc1a09062e15a0574c94af37f389/zebrad/src/application.rs#L179-L182
+ARG SHORT_SHA
 ENV SHORT_SHA=${SHORT_SHA:-}
 
 # This stage builds tests without running them.
@@ -79,7 +80,7 @@ RUN addgroup --quiet --gid ${GID} ${USER} && \
 WORKDIR ${HOME}
 
 # Build Zebra test binaries, but don't run them
-
+#
 # Leverage a cache mount to /usr/local/cargo/registry/
 # for downloaded dependencies, a cache mount to /usr/local/cargo/git/db
 # for git repository dependencies, and a cache mount to ${HOME}/target/ for
@@ -132,11 +133,10 @@ COPY --chown=${UID}:${GID} ./docker/entrypoint.sh /usr/local/bin/entrypoint.sh
 
 ENTRYPOINT [ "entrypoint.sh", "test" ]
 
-# In this stage we build a release (generate the zebrad binary)
+# This stage builds the zebrad release binary.
 #
-# This step also adds `cache mounts` as this stage is completely independent from the
-# `test` stage. This step is a dependency for the `runtime` stage, which uses the resulting
-# zebrad binary from this step.
+# It also adds `cache mounts` as this stage is completely independent from the
+# `test` stage. The resulting zebrad binary is used in the `runtime` stage.
 FROM deps AS release
 
 ARG HOME
@@ -163,8 +163,8 @@ RUN --mount=type=bind,source=tower-batch-control,target=tower-batch-control \
     cargo build --locked --release --features "${FEATURES}" --package zebrad --bin zebrad && \
     cp ${HOME}/target/release/zebrad /usr/local/bin
 
-# This step starts from scratch using Debian and only adds the resulting binary
-# from the `release` stage.
+# This stage starts from scratch using Debian and copies the built zebrad binary
+# from the `release` stage along with other binaries and files.
 FROM debian:bookworm-slim AS runtime
 
 ARG FEATURES

docker/entrypoint.sh

@@ -26,7 +26,7 @@ if [[ ! -f "${ZEBRA_CONF_PATH}" ]]; then
   exit 1
 fi
 
-# Use gosu to drop privileges
+# Use gosu to drop privileges and execute the given command as the specified UID:GID
 exec_as_user() {
   exec gosu "${UID}:${GID}" "$@"
 }
@@ -105,26 +105,6 @@ prepare_conf_file() {
   echo "${ZEBRA_CONF_PATH}"
 }
 
-# Checks if a directory contains subdirectories
-#
-# Exits with 0 if it does, and 1 otherwise.
-check_directory_files() {
-  local dir="$1"
-  # Check if the directory exists
-  if [[ -d "${dir}" ]]; then
-    # Check if there are any subdirectories
-    if find "${dir}" -mindepth 1 -type d | read -r; then
-      :
-    else
-      echo "No subdirectories found in ${dir}."
-      exit 1
-    fi
-  else
-    echo "Directory ${dir} does not exist."
-    exit 1
-  fi
-}
-
 # Runs cargo test with an arbitrary number of arguments.
 #
 # ## Positional Parameters
@@ -164,7 +144,7 @@ run_cargo_test() {
 
 # Runs tests depending on the env vars.
 #
-# Positional Parameters
+# ## Positional Parameters
 #
 # - $@: Arbitrary command that will be executed if no test env var is set.
 run_tests() {
@@ -290,7 +270,7 @@ echo "Prepared the following Zebra config:"
 cat "${ZEBRA_CONF_PATH}"
 
 # - If "$1" is "--", "-", or "zebrad", run `zebrad` with the remaining params.
-# - If "$1" is "tests":
+# - If "$1" is "test":
 #   - and "$2" is "zebrad", run `zebrad` with the remaining params,
 #   - else run tests with the remaining params.
 # - TODO: If "$1" is "monitoring", start a monitoring node.