chore: improve the run_macaron.sh script

[nathanwn]

This pull request makes a number of improvements to our current run_macaron.sh script.

This is to prepare for another pull request, #512, which adds support for Podman as an alternative container engine to run the Macaron image.

Set bash "strict" flags

Commit: 95cb003

The following bash built-in flags are added to the script. These flags effectively help make the script less error-prone.

• set -e: exit immediately if a command fails (with non-zero return code), or if a function returns non-zero.
• set -u: treat unset variables and parameters as errors when performing parameter expansion.
  Note: In case a variable ${VAR} is unset but we still need to expand, we can use the syntax ${VAR:-} to expand it to an empty string (bash documentation).
• set -o pipefail: set the return value of a pipeline to the value of the last (rightmost) command to exit with a non-zero status, or zero if all commands in the pipeline exit successfully.

Reference: https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html.

Simplify passing environment variables into the container

Commit: b4d49f0

During docker run, we can pass environment variables into the container as follows:

$ docker run [...] -e "http_proxy=${http_proxy}" [...]

In cases where we want the container to "inherit" the environment variables on the host, we do not need to explicitly specify the value, i.e., doing this should be enough:

$ docker run [...] -e http_proxy [...]

Passing the environment variables into the container in this implicit manner is also very useful when we want to use the set -x flag of bash for debugging purposes but do not want secret values to be logged out as plain text.

Inherit the JAVA_OPTS environment variable into the container

Commit: d1f6341

Proxy settings for the Gradle wrapper can also be set through the JAVA_OPTS environment variable (besides GRADLE_OPTS). We should also pass it into the container.

Other changes

• b7374c2 and dca163b mostly remove redundant logic from the script.
• 1147ede changes how analyze and verify-policy are referred to, from "actions" to "commands".
• fff08a9 refactors functions in the script that check for the existence of files or directories. With set -u, these functions can return 1 and immediately stop the script with exit code 1.
• c2bda95 renames the functions in the script to make the intentions clearer.

[behnazh-w]

The main reason we pass MAVEN_OPTS and GRADLE_OPTS is to download mvnw and gradlew when proxy is set. With JAVA_OPTS we will pass a lot more options, potentially interfering with the JVM process. Have you encountered a case where JAVA_OPTS is absolutely necessary and the other environment variables cannot be used?

[nathanwn]

Reverted in d47f254.

[behnazh-w]

We use action commands in the CLI RST documentations, which needs to be adjust to be consistent.

[nathanwn]

We use action commands in the CLI RST documentation, which needs to be adjusted to be consistent.

RST doc has been adjusted in 57e3c16.

[tromai]

The latest changes to the RST doc files look good to me. My approval still holds.