Merge pull request #687 from rkdarst/group_handling

Update group handling: set primary gid, leave suplemental with group users

base-notebook/start.sh

@@ -70,11 +70,12 @@ if [ $(id -u) == 0 ] ; then
         usermod -u $NB_UID $NB_USER
     fi
 
-    # Add NB_USER to NB_GID if it's not the default group
+    # Set NB_USER primary gid to NB_GID (after making the group).  Set
+    # supplementary gids to NB_GID and 100.
     if [ "$NB_GID" != $(id -g $NB_USER) ] ; then
         echo "Add $NB_USER to group: $NB_GID"
-        groupadd -g $NB_GID -o $NB_USER
-        usermod -a -G $NB_GID $NB_USER
+        groupadd -g $NB_GID -o ${NB_GROUP:-${NB_USER}}
+        usermod -g $NB_GID -a -G $NB_GID,100 $NB_USER
     fi
 
     # Enable sudo if requested

base-notebook/test/test_container_options.py

@@ -57,8 +57,8 @@ def test_gid_change(container):
     )
     c.wait(timeout=10)
     logs = c.logs(stdout=True).decode('utf-8')
-    assert 'gid=100(users)' in logs
-    assert 'groups=100(users),110(jovyan)' in logs
+    assert 'gid=110(jovyan)' in logs
+    assert 'groups=110(jovyan),100(users)' in logs
 
 
 def test_sudo(container):

docs/using/common.md

@@ -25,7 +25,8 @@ 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.
 * `-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 add the `$NB_USER` to a new supplemental group with the given group ID. 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.
+* `-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.
 * `-e CHOWN_HOME=yes` - Instructs the startup script to change the `$NB_USER` home directory owner and group to the current value of `$NB_UID` and `$NB_GID`. This change will take effect even if the user home directory is mounted from the host using `-v` as described below. The change is **not** applied recursively by default. You can change modify the `chown` behavior by setting `CHOWN_HOME_OPTS` (e.g., `-e CHOWN_HOME_OPTS='-R'`).
 * `-e CHOWN_EXTRA="<some dir>,<some other dir>` - Instructs the startup script to change the owner and group of each comma-separated container directory to the current value of `$NB_UID` and `$NB_GID`. The change is **not** applied recursively by default. You can change modify the `chown` behavior by setting `CHOWN_EXTRA_OPTS` (e.g., `-e CHOWN_EXTRA_OPTS='-R'`).
 * `-e GRANT_SUDO=yes` - Instructs the startup script to grant the `NB_USER` user passwordless `sudo` capability. You do **not** need this option to allow the user to `conda` or `pip` install additional packages. This option is useful, however, when you wish to give `$NB_USER` the ability to install OS packages with `apt` or modify other root-owned files in the container. For this option to take effect, you must run the container with `--user root`. (The `start-notebook.sh` script will `su $NB_USER` after adding `$NB_USER` to sudoers.) **You should only enable `sudo` if you trust the user or if the container is running on an isolated host.**