From 7756b145940220f652aa35b421054e8116dc7163 Mon Sep 17 00:00:00 2001
From: Cian Johnston <cian@coder.com>
Date: Tue, 15 Oct 2024 10:05:11 +0100
Subject: [PATCH] chore(README.md): add documentation regarding target user
 (#386)

(cherry picked from commit d14ab3d95830c830a71c2f1dcbf346667e738c43)
---
 README.md     | 1 +
 docs/users.md | 9 +++++++++
 2 files changed, 10 insertions(+)
 create mode 100644 docs/users.md

diff --git a/README.md b/README.md
index af5323d..0a54619 100644
--- a/README.md
+++ b/README.md
@@ -48,6 +48,7 @@ To explore more examples, tips, and advanced usage, check out the following guid
 - [Git Authentication](./docs/git-auth.md)
 - [Caching](./docs/caching.md)
 - [Custom Certificates](./docs/custom-certificates.md)
+- [Users](./docs/users.md)
 
 ## Setup Script
 
diff --git a/docs/users.md b/docs/users.md
new file mode 100644
index 0000000..6f121cd
--- /dev/null
+++ b/docs/users.md
@@ -0,0 +1,9 @@
+# Root Privileges
+
+Envbuilder always expects to be run as `root` in its container, as building an image will most likely require root privileges. Once the image is built, Envbuilder will drop root privileges and `exec` `ENVBUILDER_INIT_COMMAND` / `ENVBUILDER_INIT_SCRIPT` as a non-root user.
+
+## Choosing a target user
+
+Envbuilder will first attempt to switch to the `containerUser` defined `devcontainer.json`.
+If this is not specified, it will look up the last `USER` directive from the specified `Dockerfile` or image.
+If no alternative user is specified, Envbuilder will fallback to `root`.