From cc00bf3a1ac000ffd7aa8f21a13c18f910061787 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.i.sundell@gmail.com>
Date: Thu, 10 Aug 2023 15:16:11 +0200
Subject: [PATCH] docs: add docs on the system, hub, user environments

---
 docs/topic/index.md              |  1 +
 docs/topic/three-environments.md | 76 ++++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 docs/topic/three-environments.md

diff --git a/docs/topic/index.md b/docs/topic/index.md
index 7ec4b88..90e7e9c 100644
--- a/docs/topic/index.md
+++ b/docs/topic/index.md
@@ -8,6 +8,7 @@ Topic guides provide in-depth explanations of specific topics.
 
 whentouse
 requirements
+three-environments
 security
 customizing-installer
 installer-actions
diff --git a/docs/topic/three-environments.md b/docs/topic/three-environments.md
new file mode 100644
index 0000000..46718b7
--- /dev/null
+++ b/docs/topic/three-environments.md
@@ -0,0 +1,76 @@
+(topic-three-environments)=
+
+# The system, hub, and user environments
+
+TLJH's documentation mentions the _system environment_, the _hub environment_,
+and the _user environment_. This section will introduce what is meant with that
+and clarify the distinctions between the environments.
+
+(system-environment)=
+
+## The system environment
+
+When this documentation mentions the _system environment_, it refers to the
+Linux environment with its installed `apt` packages, users in `/etc/passwd`,
+etc.
+
+A part of the system environment is a Python environment setup via the `apt`
+package `python` installed by default in Linux distributions supported by TLJH.
+To be specific, we can refer to this as the _system's Python environment_.
+
+If you would do `sudo python3 -m pip install <something>` you would end up
+installing something in the system's Python environment, and that would not be
+available in the hub environment or the user environment.
+
+The system's Python environment is only used by TLJH to run the `bootstrap.py`
+script downloaded as part of installing or upgrading TLJH. This script is also
+responsible for setting up the hub environment.
+
+(hub-environment)=
+
+## The hub environment
+
+The _hub environment_ is a [virtual Python environment] setup in `/opt/tljh/hub`
+by the `bootstrap.py` script using the system's Python environment during TLJH
+installation.
+
+The hub environment has Python packages installed in it related to running
+JupyterHub itself such as an JupyterHub authenticator package, but it doesn't
+include packages to start user servers like JupyterLab.
+
+When TLJH is installed/upgraded, the packages listed in
+[tljh/requirements-hub-env.txt] are installed/upgraded in this environment.
+
+If you would do `sudo /opt/tljh/hub/bin/python3 -m pip install <something>` you
+would end up installing something in the hub environment, and that would not be
+available in the system's Python environment or the user environment.
+
+[virtual Python environment]: https://docs.python.org/3/library/venv.html
+
+[tljh/requirements-hub-env.txt]: https://github.com/jupyterhub/the-littlest-jupyterhub/blob/HEAD/tljh/requirements-hub-env.txt
+
+(user-environment)=
+
+## The user environment
+
+The _user environment_ is a Python environment setup in `/opt/tljh/user` by the
+TLJH installer during TLJH installation. The user environment is not a virtual
+environment because an entirely separate installation of Python has been made
+for it.
+
+The user environment has packages installed in it related to running individual
+jupyter servers, such as `jupyterlab`.
+
+When TLJH is _installed_, the packages listed in
+[tljh/requirements-user-env.txt] are installed in this environment. When TLJH is
+_upgraded_ though, as little as possible is done to this environment. Typically
+only `jupyterhub` is upgraded to match the version in the hub environment. If
+upgrading to a new major version of TLJH, then something small may be done
+besides this, and then it should be described the changelog.
+
+If you would do `sudo /opt/tljh/user/bin/python3 -m pip install <something>`, or
+from a user server's terminal do `sudo -E pip install <something>` you would end
+up installing something in the user environment, and that would not be available
+in the system's Python environment or the hub environment.
+
+[tljh/requirements-user-env-extras.txt]: https://github.com/jupyterhub/the-littlest-jupyterhub/blob/HEAD/tljh/requirements-user-env-extras.txt