From 9acab145cddc04033533fb1ee174dd823fd88670 Mon Sep 17 00:00:00 2001
From: Joseph Hale <me@jhale.dev>
Date: Sat, 15 Jun 2024 14:57:18 -0700
Subject: [PATCH] doc: Replicate detailed `nonroot` user docs

Node.js has great docs for rootless usage. Since their docs are
MIT licensed, we're replicating them here with attribution.
---
 Dockerfile |  5 -----
 README.md  | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 62 insertions(+), 8 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 28e325f..985e66a 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -37,10 +37,5 @@ RUN curl -sSL https://install.python-poetry.org | python3 -
 ###############################################################################
 FROM python-poetry-base AS python-poetry
 COPY --from=python-poetry-builder $POETRY_HOME $POETRY_HOME
-
-###############################################################################
-# POETRY RUNTIME IMAGE - Add a 'nonroot' unprivileged user to run the apps
-###############################################################################
-# Add the non-root user with UID/GID 1000:1000
 RUN groupadd --gid 1000 nonroot \
     && useradd --uid 1000 --gid 1000 --no-create-home --shell /bin/bash nonroot
\ No newline at end of file
diff --git a/README.md b/README.md
index 4172471..492b6cc 100644
--- a/README.md
+++ b/README.md
@@ -63,9 +63,68 @@ make build-version \
     PYTHON_IMAGE_TAG="3.10-slim"
 ```
 
-This image will also defined an unprivileged 'nonroot' user with UID:GID 1000:1000 to be used in your derived
-images with the USER directive and run your apps more safely. In this case of course remeber to assign the
-corresponding ownership to your application tree.
+## Non-root User
+
+> [!NOTE]
+>
+> This section was adapted from the Node.js docs for [**Non-root
+> user**](https://github.com/nodejs/docker-node/blob/main/docs/BestPractices.md#non-root-user)
+> in their Docker images.
+
+
+By default, Docker runs commands inside the container as root which violates the [Principle of Least Privilege (PoLP)](https://en.wikipedia.org/wiki/Principle_of_least_privilege) when superuser permissions are not strictly required. You want to run the container as an unprivileged user whenever possible. The nonroot images provide the `nonroot` user for such purpose. The Docker Image can then be run with the `nonroot` user in the following way:
+
+```
+-u "nonroot"
+```
+
+Alternatively, the user can be activated in the `Dockerfile`:
+
+```Dockerfile
+FROM thehale/python-poetry:1.8.3
+...
+# At the end, set the user to use when running this image
+USER nonroot
+```
+
+> [!TIP] 
+>
+> When using the `nonroot` user, remember to assign the corresponding ownership
+> to your application tree (e.g. `chmod`).
+
+Note that the `nonroot` user is neither a build-time nor a run-time dependency
+and it can be removed or altered, as long as the functionality of the
+application you want to add to the container does not depend on it.
+
+If you do not want nor need the user created in this image, you can remove it with the following:
+
+```Dockerfile
+# For debian based images use:
+RUN userdel -r nonroot
+
+# For alpine based images use:
+RUN deluser --remove-home nonroot
+```
+
+If you need to change the uid/gid of the user, you can use:
+
+```Dockerfile
+RUN groupmod -g 999 nonroot && usermod -u 999 -g 999 nonroot
+```
+
+If you need another name for the user (ex. `myapp`), execute:
+
+```Dockerfile
+RUN usermod -d /home/myapp -l myapp nonroot
+```
+
+For alpine based images, you do not have `groupmod` nor `usermod`, so to change the uid/gid you have to delete the previous user:
+
+```Dockerfile
+RUN deluser --remove-home nonroot \
+  && addgroup -S nonroot -g 999 \
+  && adduser -S -G nonroot -u 999 nonroot
+```
 
 ## License