From 9289fa17e7cc57c60f20ccaab9432aca21adb1bf Mon Sep 17 00:00:00 2001
From: cytopia <cytopia@everythingcli.org>
Date: Thu, 1 Nov 2018 10:50:10 +0100
Subject: [PATCH] Refs #105 document how to mitigate OSX performance issues

---
 docs/getting-started/install-the-devilbox.rst | 27 +++++++++++++++++++
 docs/support/troubleshooting.rst              | 15 +++++++++++
 2 files changed, 42 insertions(+)

diff --git a/docs/getting-started/install-the-devilbox.rst b/docs/getting-started/install-the-devilbox.rst
index 72b481357..d3c528227 100644
--- a/docs/getting-started/install-the-devilbox.rst
+++ b/docs/getting-started/install-the-devilbox.rst
@@ -122,6 +122,33 @@ shared mounts among multiple container:
    * |ext_lnk_docker_selinux_label|
    * |ext_lnk_docker_mount_z_flag|
 
+.. _install_the_devilbox_osx_performance:
+
+OSX: Performance
+----------------
+
+Out of the box, Docker for Mac has some performance issues when it comes to mount directories with
+a lot of files inside. To mitigate this issue, you can adjust the caching settings for mounted
+directories.
+
+To do so, you will want to adjust the :ref:`env_mount_options` to allow caching on mounts.
+
+.. code-block:: bash
+   :caption: .env
+   :emphasize-lines: 3
+
+   host> vi .env
+
+   MOUNT_OPTIONS=,cached
+
+Ensure to read the links below to understand why this problem exists and how the fix works.
+The Docker documentation will also give you alternative caching options to consider.
+
+.. seealso::
+   * https://github.com/cytopia/devilbox/issues/105#issuecomment-426229921
+   * https://forums.docker.com/t/file-access-in-mounted-volumes-extremely-slow-cpu-bound/8076/281
+   * https://docs.docker.com/docker-for-mac/osxfs-caching/#tuning-with-consistent-cached-and-delegated-configurations
+   * :ref:`env_mount_options`
 
 Checklist
 =========
diff --git a/docs/support/troubleshooting.rst b/docs/support/troubleshooting.rst
index f4aa3d429..6cc4dcab1 100644
--- a/docs/support/troubleshooting.rst
+++ b/docs/support/troubleshooting.rst
@@ -116,6 +116,21 @@ This simply means your Docker and/or Docker Compose versions are outdated.
 
 .. seealso:: :ref:`prerequisites`
 
+
+Performance
+===========
+
+Performance issues on Docker for Mac
+------------------------------------
+
+By default Docker for Mac has performance issues on mounted directories with a lot of files inside.
+To overcome this issue you can apply different kinds of caching options to the mount points.
+
+.. seealso::
+   * :ref:`install_the_devilbox_osx_performance`
+   * :ref:`env_mount_options`
+
+
 DNS issues
 ==========