Add Dockerfile enhancements and usage documentation

[calvinp0]

Enhance the Dockerfile by sourcing aliases in the user's .bashrc for non-interactive logins and refactor entrywrapper.sh for improved UID/GID remapping and ownership handling. Include detailed Docker usage instructions in the running documentation.

[Copilot]

Pull request overview

This PR enhances the Docker support for ARC by improving the Dockerfile configuration, refactoring the entry wrapper script for better UID/GID handling, and adding comprehensive Docker usage documentation.

• Adds sourcing of aliases to the mambauser's .bashrc for non-interactive shells
• Refactors entrywrapper.sh to support PUID/PGID environment variables for bind mount compatibility
• Adds detailed Docker usage documentation with examples for running ARC, RMG, and interactive shells

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
docs/source/running.rst	Adds new "Running via Docker" section with comprehensive examples for non-interactive ARC/RMG execution and interactive shell usage
dockerfiles/entrywrapper.sh	Refactors UID/GID remapping logic to support PUID/PGID environment variables, adds ownership handling for /work directory, and implements privilege dropping pattern
Dockerfile	Adds .bashrc configuration to source aliases.sh for non-interactive logins and sets USER to root for entrypoint privilege requirements

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The PUID remapping does not check if the target UID is already in use by another user. If PUID is set to a UID that belongs to an existing user, the usermod -u "$PUID" mambauser command will fail with an error, causing the script to exit due to set -e. Consider checking if the target UID already exists and either skip the remapping if it's already the current UID, or provide a clear error message explaining the conflict.

Suggested change

	usermod -u "$PUID" mambauser
	current_uid="$(id -u mambauser)"
	if [[ "$PUID" != "$current_uid" ]]; then
	if getent passwd "$PUID" >/dev/null; then
	echo "Error: Cannot remap mambauser to UID '$PUID' because it is already in use by another user." >&2
	exit 1
	fi
	usermod -u "$PUID" mambauser
	fi

[Copilot]

The PGID remapping logic has inconsistent behavior. When a group with the target GID already exists, usermod -g "$PGID" changes the user's primary group to that existing group. However, when no group exists with that GID, groupmod -g "$PGID" mambauser changes the GID of the mambauser group itself. This means the mambauser user could end up in different groups (an existing system group vs the renamed mambauser group) depending on whether the GID already exists. Consider always using groupmod to change the mambauser group's GID, and handle the case where the target GID is already taken by a different group by either failing with an error or choosing a different approach.

Suggested change

	if getent group "$PGID" >/dev/null; then
	usermod -g "$PGID" mambauser
	else
	groupmod -g "$PGID" mambauser
	fi
	existing_group=""
	if getent group "$PGID" >/dev/null; then
	existing_group="$(getent group "$PGID" | cut -d: -f1)"
	fi
	if [[ -n "$existing_group" && "$existing_group" != "mambauser" ]]; then
	echo "Error: requested PGID '$PGID' is already in use by group '$existing_group', cannot remap mambauser group." >&2
	exit 1
	fi
	groupmod -g "$PGID" mambauser

[Copilot]

After changing the UID with usermod, the ownership check and chown operations may not work as intended. When usermod changes the UID, the files previously owned by the old UID are not automatically updated to the new UID. The test -O /home/mambauser/Code checks if the current effective user owns the directory, but after usermod, this script is still running as root (UID 0), so the test will evaluate based on root ownership, not the new mambauser UID. The subsequent chown should fix ownership, but the conditional logic may not trigger correctly. Consider running the ownership fix unconditionally after UID/GID changes, or re-evaluating the ownership check logic.

Suggested change

	if [[ ! -O /home/mambauser/Code ]]; then
	chown -R mambauser:mambauser /home/mambauser/Code || true
	fi
	if [[ -d /work && ! -O /work ]]; then
	if [[ -d /home/mambauser/Code ]]; then
	chown -R mambauser:mambauser /home/mambauser/Code || true
	fi
	if [[ -d /work ]]; then

[Copilot]

The chown operations use || true to silently ignore failures. While this prevents the script from failing when chown cannot complete (e.g., on read-only mounts), it also masks legitimate permission errors that users should be aware of. Consider logging a warning message when chown fails, or at minimum document this behavior, so users understand why their files might not have the expected ownership even when PUID/PGID are set.

Suggested change

	chown -R mambauser:mambauser /home/mambauser/Code || true
	fi
	if [[ -d /work && ! -O /work ]]; then
	chown -R mambauser:mambauser /work || true
	if ! chown -R mambauser:mambauser /home/mambauser/Code; then
	echo "warning: failed to change ownership of /home/mambauser/Code to mambauser:mambauser (read-only mount or permission issue?)" >&2
	fi
	fi
	if [[ -d /work && ! -O /work ]]; then
	if ! chown -R mambauser:mambauser /work; then
	echo "warning: failed to change ownership of /work to mambauser:mambauser (read-only mount or permission issue?)" >&2
	fi

[kfir4444]

lgtm 👍