Fix #1077

* Documentation `common.md` updated
* `test_nb_user_change` test written

base-notebook/test/test_container_options.py

 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
 import time
+import logging
 
 import pytest
 
+LOGGER = logging.getLogger(__name__)
+
 
 def test_cli_args(container, http_client):
     """Container should respect notebook server command line args
@@ -61,6 +64,37 @@ def test_gid_change(container):
     assert 'groups=110(jovyan),100(users)' in logs
 
 
+def test_nb_user_change(container):
+    """Container should change the user name of the default user."""
+    nb_user = "nayvoj"
+    running_container = container.run(
+        tty=True,
+        user="root",
+        environment=[f"NB_USER={nb_user}",
+                      "CHOWN_HOME=yes"],
+        working_dir=f"/home/{nb_user}",
+        command=['start.sh', 'bash', '-c', 'sleep infinity']
+    )
+    
+    LOGGER.info(f"Checking if the user is changed to {nb_user} by the start script ...")
+    output = running_container.logs(stdout=True).decode("utf-8")
+    assert f"Set username to: {nb_user}" in output, f"User is not changed to {nb_user}" 
+    
+    LOGGER.info(f"Checking {nb_user} id ...")
+    command = "id"
+    expected_output = f"uid=1000({nb_user}) gid=100(users) groups=100(users)"
+    cmd = running_container.exec_run(command, user=nb_user)
+    output = cmd.output.decode("utf-8").strip("\n")
+    assert output == expected_output, f"Bad user {output}, expected {expected_output}"
+    
+    LOGGER.info(f"Checking if {nb_user} owns his home folder ...")
+    command = f'stat -c "%U %G" /home/{nb_user}/'
+    expected_output = f"{nb_user} users"
+    cmd = running_container.exec_run(command)
+    output = cmd.output.decode("utf-8").strip("\n")
+    assert output == expected_output, f"Bad owner for the {nb_user} home folder {output}, expected {expected_output}"
+
+
 def test_chown_extra(container):
     """Container should change the UID/GID of CHOWN_EXTRA."""
     c = container.run(

docs/using/common.md

@@ -23,7 +23,7 @@ docker run -d -p 8888:8888 jupyter/base-notebook start-notebook.sh --NotebookApp
 You may instruct the `start-notebook.sh` script to customize the container environment before launching
 the notebook server. You do so by passing arguments to the `docker run` command.
 
-* `-e NB_USER=jovyan` - Instructs the startup script to change the default container username from `jovyan` to the provided value. Causes the script to rename the `jovyan` user home folder. For this option to take effect, you must run the container with `--user root` and set the working directory `-w /home/$NB_USER`. This feature is useful when mounting host volumes with specific home folder.
+* `-e NB_USER=jovyan` - Instructs the startup script to change the default container username from `jovyan` to the provided value. Causes the script to rename the `jovyan` user home folder. For this option to take effect, you must run the container with `--user root`, set the working directory `-w /home/$NB_USER` and set the environment variable `-e CHOWN_HOME=yes` (see below for detail). This feature is useful when mounting host volumes with specific home folder.
 * `-e NB_UID=1000` - Instructs the startup script to switch the numeric user ID of `$NB_USER` to the given value. This feature is useful when mounting host volumes with specific owner permissions. For this option to take effect, you must run the container with `--user root`. (The startup script will `su $NB_USER` after adjusting the user ID.) You might consider using modern Docker options `--user` and `--group-add` instead. See the last bullet below for details.
 * `-e NB_GID=100` - Instructs the startup script to change the primary group of`$NB_USER` to `$NB_GID` (the new group is added with a name of `$NB_GROUP` if it is defined, otherwise the group is named `$NB_USER`).  This feature is useful when mounting host volumes with specific group permissions. For this option to take effect, you must run the container with `--user root`. (The startup script will `su $NB_USER` after adjusting the group ID.) You might consider using modern Docker options `--user` and `--group-add` instead. See the last bullet below for details.  The user is added to supplemental group `users` (gid 100) in order to allow write access to the home directory and `/opt/conda`.  If you override the user/group logic, ensure the user stays in group `users` if you want them to be able to modify files in the image.
 * `-e NB_GROUP=<name>` - The name used for `$NB_GID`, which defaults to `$NB_USER`.  This is only used if `$NB_GID` is specified and completely optional: there is only cosmetic effect.