Merge pull request #11572 from djs55/docker-for-mac-filesharing

Improve Docker Desktop filesharing docs

docker-for-mac/index.md

@@ -99,15 +99,25 @@ File share settings are:
 - **Apply & Restart** makes the directory available to containers using Docker's
   bind mount (`-v`) feature.
 
-  There are some limitations on the directories that can be shared:
-
-  - The directory must not exist inside of Docker.
-
-For more information, see:
-
-- [Namespaces](osxfs.md#namespaces){: target="_blank" rel="noopener" class="_"} in the topic on
-  [osxfs file system sharing](osxfs.md).
-- [Volume mounting requires file sharing for any project directories outside of `/Users`](troubleshoot.md#volume-mounting-requires-file-sharing-for-any-project-directories-outside-of-users).)
+> Tips on shared folders, permissions, and volume mounts
+>
+ * Shared folders are designed to allow application code to be edited 
+ on the host while being executed in containers. For non-code items
+ such as cache directories or databases, the performance will be much 
+ better if they are stored in the Linux VM, using a [data volume](../storage/volumes.md)
+ (named volume) or [data container](../storage/volumes.md).
+>
+ * By default, Mac file systems are case-insensitive while Linux is case-sensitive.
+ On Linux, it is possible to create 2 separate files: `test` and `Test`, 
+ while on Mac these filenames would actually refer to the same underlying file. 
+ This can lead to problems where an app works correctly on a Mac 
+ (where the file contents are shared) but fails when run in Linux in 
+ production (where the file contents are distinct). To avoid this, Docker Desktop 
+ insists that all shared files are accessed as their original case. Therefore, if a file 
+ is created called `test`, it must be opened as `test`. Attempts to open `Test` will 
+ fail with the error `No such file or directory`. Similarly, once a file called `test` 
+ is created, attempts to create a second file called `Test` will fail. For more information, 
+ see [Volume mounting requires file sharing for any project directories outside of `/Users`](troubleshoot.md#volume-mounting-requires-file-sharing-for-any-project-directories-outside-of-users).)
 
 #### Proxies
 

storage/index.md

@@ -134,6 +134,16 @@ Some use cases for volumes include:
   the volume, then back up the volume's directory
   (such as `/var/lib/docker/volumes/<volume-name>`).
 
+- When your application requires high-performance I/O on Docker Desktop. Volumes
+  are stored in the Linux VM rather than the host, which means that the reads and writes
+  have much lower latency and higher throughput.
+
+- When your application requires fully native file system behavior on Docker
+  Desktop. For example, a database engine requires precise control over disk
+  flushing to guarantee transaction durability. Volumes are stored in the Linux
+  VM and can make these guarantees, whereas bind mounts are remoted to macOS or
+  Windows, where the file systems behave slightly differently.
+
 ## Good use cases for bind mounts
 
 In general, you should use volumes where possible. Bind mounts are appropriate

storage/volumes.md

@@ -11,7 +11,7 @@ redirect_from:
 
 Volumes are the preferred mechanism for persisting data generated by and used
 by Docker containers. While [bind mounts](bind-mounts.md) are dependent on the
-directory structure of the host machine, volumes are completely managed by
+directory structure and OS of the host machine, volumes are completely managed by
 Docker. Volumes have several advantages over bind mounts:
 
 - Volumes are easier to back up or migrate than bind mounts.
@@ -21,6 +21,8 @@ Docker. Volumes have several advantages over bind mounts:
 - Volume drivers let you store volumes on remote hosts or cloud providers, to
   encrypt the contents of volumes, or to add other functionality.
 - New volumes can have their content pre-populated by a container.
+- Volumes on Docker Desktop have much higher performance than bind mounts from
+  Mac and Windows hosts.
 
 In addition, volumes are often a better choice than persisting data in a
 container's writable layer, because a volume does not increase the size of the
@@ -216,6 +218,42 @@ $ docker container rm devtest
 $ docker volume rm myvol2
 ```
 
+## Use a volume with docker-compose
+
+A single docker compose service with a volume looks like this:
+
+```yml
+version: "3.7"
+services:
+  frontend:
+    image: node:lts
+    volumes:
+      - myapp:/home/node/app
+volumes:
+  myapp:
+```
+
+On the first invocation of `docker-compose up` the volume will be created. The same
+volume will be reused on following invocations.
+
+A volume may be created directly outside of compose with `docker volume create` and
+then referenced inside `docker-compose.yml` as follows:
+
+```yml
+version: "3.7"
+services:
+  frontend:
+    image: node:lts
+    volumes:
+      - myapp:/home/node/app
+volumes:
+  myapp:
+    external: true
+```
+
+For more information about using volumes with compose see
+[the compose reference](../compose/compose-file-v2.md#volume-configuration-reference).
+
 ### Start a service with volumes
 
 When you start a service and define a volume, each service container uses its own