Update Dockerfile docs and default for volumes

Dockerfile.in

@@ -14,35 +14,29 @@
 
 # HOW TO USE THIS CONTAINER:
 #
-# For most users, the simplest way to use this container is to mount a volume
-# on /git.  The only commandline argument (or env var) that is really required
-# is `--repo` ($GIT_SYNC_REPO).  Everything else is optional (run this with
+# The only commandline argument (or env var) that is really required is
+# `--repo` ($GIT_SYNC_REPO).  Everything else is optional (run this with
 # `--man` for details).
 #
-# This container will run as UID:GID 65533:65533 by default, and unless you
-# change that, you do not need to think about permissions much.  If you run
-# into permissions problems, this might help:
+# This container will run as UID:GID 65533:65533 by default.  For most users,
+# the simplest ways to use this container are either:
+#   a) use the default UID/GID and mount a volume on /git writeable by those
+#   b) set your own UID/GID and mount a volume on /git writeable by those
 #
-#  - User does not mount a volume
-#    => should work, but limited utility
+# If you mount a volume anywhere else, you must set `--root` ($GIT_SYNC_ROOT).
+# If you do not mount a volume, this will run but you can't access the results
+# (which might be useful for testing, but not much else).
 #
-#  - User mounts a new docker volume on /git
-#    => should work
+# Newly created docker volumes (the very first `docker run -v`) are initialized
+# based on the in-image mountpoint's UID/GID?mode, so another solution for
+# using this with docker is to set your own UID/GID and also add the default
+# GID as a supplemental group (see `docker run --group-add`).
 #
-#  - User mounts an existing docker volume on /git
-#    => if the volume already exists with compatible permissions it should work
-#    => if the volume already exists with different permissions you can either
-#       set the container UID or GID(s) or you can chown the volume
+# Kubernetes offers `Pod.spec.securityContext.fsGroup` to manage volume
+# permissions.
 #
-#  - User mounts an existing dir on /git
-#    => set container UID or GID(s) to be able to access that dir
-#
-#  - User sets a different UID and git-sync GID
-#    => should work
-#
-#  - User sets a different GID
-#    => either add the git-sync GID or else set --root, mount a volume,
-#       and manage volume permissions to access that volume
+# If you set any UID other than the default and want to use git over SSH, you
+# should set `--add-user` ($GIT_SYNC_ADD_USER).
 
 #############################################################################
 # First we prepare the image that we want, regardless of build layers.
@@ -66,20 +60,16 @@ RUN rm -rf /var/lib/apt/lists/*
 
 # Add the default UID to /etc/passwd so SSH is satisfied.
 RUN echo "git-sync:x:65533:65533::/tmp:/sbin/nologin" >> /etc/passwd
-# A user might choose a different UID and set the --add-user flag, which needs
-# to be able to write to /etc/passwd.
+# A user might choose a different UID and set the `--add-user` flag, which
+# needs to be able to write to /etc/passwd.
 RUN chmod 0666 /etc/passwd
 
 # Add the default GID to /etc/group for completeness.
 RUN echo "git-sync:x:65533:git-sync" >> /etc/group
 
-# Make a directory that can be used to mount volumes.  Git-sync itself does not
-# default the --root ($GIT_SYNC_ROOT) flag, but we can set a default here,
-# which makes the container image easier to use.  Setting the mode to include
-# group-write allows users to run this image as a different user, as long as
-# they use our git-sync group.  If the user needs a different group or sets
-# $GIT_SYNC_ROOT or --root, their values will override this, and we assume they
-# are handling permissions themselves.
+# Make a directory that can be used to mount volumes.  Setting the mode to
+# include group-write allows users to run this image as a different user, as
+# long as they use our git-sync group.
 RUN mkdir -m 02775 /git && chown 65533:65533 /git
 
 # When building, we can pass a hash of the licenses tree, which docker checks
@@ -111,6 +101,11 @@ ENV HOME=/tmp
 WORKDIR /tmp
 
 # Default values for flags.
-ENV GIT_SYNC_ROOT=/tmp/git
+# Git-sync itself does not default the `--root` ($GIT_SYNC_ROOT) flag, but we
+# can set a default here, which makes the container image easier to use.  The
+# permissions were set for the default git-sync UID and GID.  If the user needs
+# a different group or sets `--root` ($GIT_SYNC_ROOT), their values will
+# override this, and we assume they are handling permissions themselves.
+ENV GIT_SYNC_ROOT=/git
 
 ENTRYPOINT ["/{ARG_BIN}"]