From 46023f2fe24640f813d3bf8187f331c3a662f3e7 Mon Sep 17 00:00:00 2001
From: Eugene Yokota <eed3si9n@gmail.com>
Date: Thu, 24 Jan 2019 03:43:49 -0500
Subject: [PATCH] Update Docker plugin docs

Ref #1190
Ref #1189
---
 src/sphinx/formats/docker.rst | 41 +++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/src/sphinx/formats/docker.rst b/src/sphinx/formats/docker.rst
index 077e9e887..a23dbe33b 100644
--- a/src/sphinx/formats/docker.rst
+++ b/src/sphinx/formats/docker.rst
@@ -117,6 +117,22 @@ Environment Settings
     Overrides the default entrypoint for docker-specific service discovery tasks before running the application.
     Defaults to the bash executable script, available at ``bin/<script name>`` in the current ``WORKDIR`` of ``/opt/docker``.
 
+  ``dockerPermissionStrategy``
+    The strategy that decides how file permissions are set for the working directory inside the Docker image
+
+    * ``DockerPermissionStrategy.MultiStage`` (default) uses multi-stage Docker build to call chmod ahead of time.
+    * ``DockerPermissionStrategy.None`` does not attempt to change the file permissions, and use the host machine's file mode bits.
+    * ``DockerPermissionStrategy.Run`` calls ``RUN`` in the Dockerfile. This has regression on the resulting Docker image file size.
+    * ``DockerPermissionStrategy.CopyChown`` calls ``COPY --chown`` in the Dockerfile. Provided as a backward compatibility.
+
+  ``dockerChmodType``
+    The file permissions for the files copied into Docker image when ``MultiStage`` or ``Run`` strategy is used.
+
+    * ``DockerChmodType.UserGroupReadExecute`` (default): chmod -R u=rX,g=rX
+    * ``DockerChmodType.UserGroupWriteExecute``: chmod -R u=rwX,g=rwX
+    * ``DockerChmodType.SyncGroupToUser``: chmod -R g=u
+    * ``DockerChmodType.Custom``: Custom argument provided by the user.
+
   ``dockerVersion``
     The docker server version. Used to leverage new docker features while maintaining backwards compatibility.
 
@@ -230,6 +246,31 @@ The files from ``mappings in Docker`` are extracted underneath this directory.
 
   defaultLinuxInstallLocation in Docker := "/opt/docker"
 
+
+File Permission
+~~~~~~~~~~~~~~~
+By default, the working directory inside the Docker image is given read-only file permissions
+set using multi-stage Docker build, which requires Docker 17.5 or later (watch out if you're using older Minikube).
+
+If you want to make the working directory writable by the running process, here's the setting:
+
+.. code-block:: scala
+
+    import com.typesafe.sbt.packager.docker.DockerChmodType
+
+    dockerChmodType := DockerChmodType.UserGroupWriteExecute
+
+If you don't want SBT Native Packager to change the file permissions at all here's a strategy you can choose:
+
+.. code-block:: scala
+
+    import com.typesafe.sbt.packager.docker.DockerPermissionStrategy
+
+    dockerPermissionStrategy := DockerPermissionStrategy.None
+
+This will inherit the file mode bits set in your machine. Given that Kubernetes implementations like OpenShift will use an arbitrary user,
+remember to set both the user bits and group bits when running `chmod` yourself.
+
 Custom Dockerfile
 ~~~~~~~~~~~~~~~~~