added troubleshooting info about shared drives/files and volume mounting

Victoria Bialas · Victoria Bialas · commit 1249d35fca06 · 2016-11-16T11:02:04.000-08:00
added more changes

updated per Nathan's comments on properly documenting directories formats for all platforms

incorporated Daniel's review comments, and added a clarification re: users' dir

copyedits

Signed-off-by: Victoria Bialas &lt;victoria.bialas@docker.com&gt;
diff --git a/compose/gettingstarted.md b/compose/gettingstarted.md
@@ -108,7 +108,23 @@ This Compose file defines two services, `web` and `redis`. The web service:
 * Mounts the project directory on the host to `/code` inside the container allowing you to modify the code without having to rebuild the image.
 * Links the web service to the Redis service.
 
-The `redis` service uses the latest public [Redis](https://registry.hub.docker.com/_/redis/) image pulled from the Docker Hub registry.
+The `redis` service uses the latest public
+[Redis](https://registry.hub.docker.com/_/redis/) image pulled from the Docker
+Hub registry.
+
+>**Tip:** If your project is outside of the `Users` directory (`cd ~`), then you
+need to share the drive or location of the Dockerfile and volume you are using.
+If you get runtime errors indicating an application file is not found, a volume
+mount is denied, or a service cannot start, try enabling file or drive sharing.
+Volume mounting requires shared drives for projects that live outside of
+`C:\Users` (Windows) or `/Users` (Mac), and is required for _any_ project on
+Docker for Windows that uses [Linux
+containers](/docker-for-windows/index.md#switch-between-windows-and-linux-containers-beta-feature).
+For more information, see [Shared
+Drives](../docker-for-windows/index.md#shared-drives) on Docker for Windows,
+[File sharing](../docker-for-mac/index.md#file-sharing) on Docker for Mac, and
+the general examples on how to [Manage data in
+containers](../engine/tutorials/dockervolumes.md).
 
 ## Step 4: Build and run your app with Compose
 
@@ -180,4 +196,4 @@ At this point, you have seen the basics of how Compose works.
 - Next, try the quick start guide for [Django](django.md),
   [Rails](rails.md), or [WordPress](wordpress.md).
 - [Explore the full list of Compose commands](./reference/index.md)
-- [Compose configuration file reference](compose-file.md)
+- [Compose configuration file reference](compose-file.md)
diff --git a/docker-for-mac/index.md b/docker-for-mac/index.md
@@ -216,6 +216,11 @@ There are some limitations on the directories that can be shared:
 
 See [Namespaces](osxfs.md#namespaces) in the topic on [osxfs file system sharing](osxfs.md) for more information.
 
+>**Tip:** File sharing is required for volume mounting if the project lives
+outside of the `/Users` directory. In that case, share the drive where the
+Dockerfile and volume are located. Otherwise, you will get file not found or
+cannot start service errors at runtime. (See also [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).)
+
 #### Privacy
 
 You can set Docker for Mac to auto-send diagnostics, crash reports, and usage data. This information can help Docker improve the application and get more context for troubleshooting problems.
@@ -283,4 +288,4 @@ ln -s /Applications/Docker.app/Contents/Resources/etc/docker-compose.bash-comple
 
 * Check out the <a href="https://blog.docker.com/2016/06/docker-mac-windows-public-beta/">blog posts</a> on Docker for Mac and Docker for Windows public betas, and <a href="https://blog.docker.com/2016/03/docker-for-mac-windows-beta/">earlier posts</a> on the initial private beta.
 
-* Please give feedback on your experience with the app and report bugs and problems by logging into our [Docker for Mac forum](https://forums.docker.com/c/docker-for-mac).
+* Please give feedback on your experience with the app and report bugs and problems by logging into our [Docker for Mac forum](https://forums.docker.com/c/docker-for-mac).
diff --git a/docker-for-mac/troubleshoot.md b/docker-for-mac/troubleshoot.md
@@ -6,6 +6,8 @@ redirect_from:
 title: Logs and troubleshooting
 ---
 
+<!-- /TOC -->
+
 Here is information about how to diagnose and troubleshoot problems, send logs
 and communicate with the Docker for Mac team, use our forums and Knowledge Hub,
 browse and log issues on GitHub, and find workarounds for known problems.
@@ -115,6 +117,17 @@ auto-generated reports on packages.
 
 ## Troubleshooting
 
+### Volume mounting requires file sharing for any project directories outside of `/Users`
+
+If you are using mounted volumes and get runtime errors indicating an
+application file is not found, a volume mount is denied, or a service cannot
+start (e.g., with [Docker Compose](/compose/gettingstarted.md)), you might
+need to enable [file sharing](index.md#file-sharing).
+
+Volume mounting requires shared drives for projects that live outside of the
+`/Users` directory. Go to <img src="images/whale-x.png"> --> **Preferences** -->
+**File sharing** and share the drive that contains the Dockerfile and volume.
+
 ### Recreate or update your containers after Beta 18 upgrade
 
 Docker 1.12.0 RC3 release introduces a backward incompatible change from RC2 to
@@ -346,4 +359,4 @@ Alternatively you could create a plain-text TCP proxy on localhost:1234 using:
     Then restart the NTP service with:
 
         sudo launchctl unload /System/Library/LaunchDaemons/org.ntp.ntpd.plist
-        sudo launchctl load /System/Library/LaunchDaemons/org.ntp.ntpd.plist
+        sudo launchctl load /System/Library/LaunchDaemons/org.ntp.ntpd.plist
diff --git a/docker-for-windows/index.md b/docker-for-windows/index.md
@@ -321,13 +321,27 @@ Share your local drives (volumes) with Docker for Windows, so that they are avai
 
 ![Shared Drives](images/settings-shared-drives.png)
 
-You will be asked to provide your Windows system username and password (domain user) to apply shared drives. You can select an option to have Docker store the credentials so that you don't have to re-enter them every time.
-
-Permissions to access shared drives are tied to the credentials you provide here. If you run `docker` commands and tasks under a different username than the one used here to set up sharing, your containers will not have permissions to access the mounted volumes.
-
->**Tip:** Shared drives are only required for volume mounting [Linux containers](#switch-between-windows-and-linux-containers-beta-feature), not Windows containers.
-
-See also [Verify domain user has permissions for shared drives](troubleshoot.md#verify-domain-user-has-permissions-for-shared-drives-volumes) in Troubleshooting.
+You will be asked to provide your Windows system username and password (domain
+user) to apply shared drives. You can select an option to have Docker store the
+credentials so that you don't have to re-enter them every time.
+
+Permissions to access shared drives are tied to the credentials you provide
+here. If you run `docker` commands and tasks under a different username than the
+one used here to set up sharing, your containers will not have permissions to
+access the mounted volumes.
+
+>**Tip:** In general, shared drives are only required for volume mounting [Linux
+containers](#switch-between-windows-and-linux-containers-beta-feature), and not
+for Windows containers. However, if the project lives outside of the `\Users`
+directory, you need to share the drive where the Dockerfile and volume are
+located even if you are using [Windows
+containers](#getting-started-with-windows-containers-beta-feature)). Runtime
+errors such as file not found or cannot start service may indicate shared drives
+are needed. (See also [Volume mounting requires shared drives for Linux containers and for any project directories outside of `C:\Users`](troubleshoot.md#volume-mounting-requires-shared-drives-for-linux-containers-and-for-any-project-directories-outside-of-cusers).)
+
+See also [Verify domain user has permissions for shared
+drives](troubleshoot.md#verify-domain-user-has-permissions-for-shared-drives-volumes)
+in Troubleshooting.
 
 #### Firewall rules for shared drives
 
@@ -469,4 +483,4 @@ If you want to go back to using Docker Toolbox, you have to disable the Hyper-V
 
 * Check out the <a href="https://blog.docker.com/2016/06/docker-mac-windows-public-beta/">blog posts</a> on Docker for Mac and Docker for Windows public betas, and <a href="https://blog.docker.com/2016/03/docker-for-mac-windows-beta/">earlier posts</a> on the initial private beta.
 
-* Please give feedback on your experience with the app and report bugs and problems by logging into our [Docker for Windows forum](https://forums.docker.com/c/docker-for-windows).
+* Please give feedback on your experience with the app and report bugs and problems by logging into our [Docker for Windows forum](https://forums.docker.com/c/docker-for-windows).
diff --git a/docker-for-windows/troubleshoot.md b/docker-for-windows/troubleshoot.md
@@ -6,48 +6,89 @@ redirect_from:
 title: Logs and troubleshooting
 ---
 
-Here is information about how to diagnose and troubleshoot problems, send logs and communicate with the Docker for Windows team, use our forums and Knowledge Hub, browse and log issues on GitHub, and find workarounds for known problems.
+Here is information about how to diagnose and troubleshoot problems, send logs
+and communicate with the Docker for Windows team, use our forums and Knowledge
+Hub, browse and log issues on GitHub, and find workarounds for known problems.
 
 ## Docker Knowledge Hub
 
-**Looking for help with Docker for Windows?** Check out the [Docker Knowledge Hub](http://success.docker.com/) for knowledge base articles, FAQs, and technical support for various subscription levels.
+**Looking for help with Docker for Windows?** Check out the [Docker Knowledge
+**Hub](http://success.docker.com/) for knowledge base articles, FAQs, and
+**technical support for various subscription levels.
 
 ## Submitting diagnostics, feedback, and GitHub issues
 
-If you encounter problems for which you do not find solutions in this documentation, on [Docker for Windows issues on GitHub](https://github.com/docker/for-win/issues), or the [Docker for Windows forum](https://forums.docker.com/c/docker-for-windows), we can help you troubleshoot the log data. See [Diagnose and Feedback](index.md#diagnose-and-feedback) to learn about diagnostics and how to create new issues on GitHub.
+If you encounter problems for which you do not find solutions in this
+documentation, on [Docker for Windows issues on
+GitHub](https://github.com/docker/for-win/issues), or the [Docker for Windows
+forum](https://forums.docker.com/c/docker-for-windows), we can help you
+troubleshoot the log data. See [Diagnose and
+Feedback](index.md#diagnose-and-feedback) to learn about diagnostics and how to
+create new issues on GitHub.
 
 ## Checking the Logs
 
 In addition to using the diagnose and feedback option to submit logs, you can browse the logs yourself.
 
 ### Use the systray menu to view logs
 
-To view Docker for Windows latest log, click on the `Diagnose & Feedback` menu entry in the systray and then on the `Log file` link. You can see the full history of logs in your `AppData\Local` folder.
+To view Docker for Windows latest log, click on the `Diagnose & Feedback` menu
+entry in the systray and then on the `Log file` link. You can see the full
+history of logs in your `AppData\Local` folder.
 
 ### Use the systray menu to report and issue
 
-If you encounter an issue and the suggested troubleshoot procedures outlined below don't fix it you can generate a diagnostics report. Click on the `Diagnose & Feedback` menu entry in the systray and then on the `Upload diagnostic...` link. This will upload diagnostics to our server and provide you with a unique ID you can use in email or the forum to reference the upload.
+If you encounter an issue and the suggested troubleshoot procedures outlined
+below don't fix it you can generate a diagnostics report. Click on the `Diagnose &
+Feedback` menu entry in the systray and then on the `Upload diagnostic...` link.
+This will upload diagnostics to our server and provide you with a unique ID you
+can use in email or the forum to reference the upload.
 
 ## Troubleshooting
 
 ### inotify on shared drives does not work
 
-Currently, `inotify` does not work on Docker for Windows. This will become evident, for example, when when an application needs to read/write to a container across a mounted drive. This is a known issue that the team is working on. Below is a temporary workaround, and a link to the issue.
+Currently, `inotify` does not work on Docker for Windows. This will become
+evident, for example, when when an application needs to read/write to a
+container across a mounted drive. This is a known issue that the team is working
+on. Below is a temporary workaround, and a link to the issue.
 
-* **Workaround for nodemon and Node.js** - If you are using [nodemon](https://github.com/remy/nodemon) with  `Node.js`, try the fallback polling mode described here: [nodemon isn't restarting node applications](https://github.com/remy/nodemon#application-isnt-restarting)
+* **Workaround for nodemon and Node.js** - If you are using [nodemon](https://github.com/remy/nodemon) with  `Node.js`, try the fallback
+polling mode described here: [nodemon isn't restarting node
+applications](https://github.com/remy/nodemon#application-isnt-restarting)
 
 * **Docker for Windows issue on GitHub** - See the issue [Inotify on shared drives does not work](https://github.com/docker/for-win/issues/56#issuecomment-242135705)
 
+### Volume mounting requires shared drives for Linux containers and for any project directories outside of `C:\Users`
+
+If you are using mounted volumes and get runtime errors indicating an
+application file is not found, a volume mount is denied, or a service cannot
+start (e.g., with [Docker Compose](/compose/gettingstarted.md)), you might
+need to enable [shared drives](index.md#shared-drives).
+
+Volume mounting requires shared drives for Windows containers, but also for
+Linux containers if the project lives outside of the `C:\Users` directory. Go to
+<img src="images/whale-x.png"> --> **Settings** --> **Shared Drives** and share
+the drive that contains the Dockerfile and volume.
 
 ### Verify domain user has permissions for shared drives (volumes)
 
->**Tip:** Shared drives are only required for volume mounting [Linux containers](index.md#switch-between-windows-and-linux-containers-beta-feature), not Windows containers.
+>**Tip:** Shared drives are only required for volume mounting [Linux
+containers](index.md#switch-between-windows-and-linux-containers-beta-feature),
+not Windows containers.
 
-Permissions to access shared drives are tied to the username and password you use to set up shared drives. (See [Shared Drives](index.md#shared-drives).) If you run `docker` commands and tasks under a different username than the one used to set up shared drives, your containers will not have permissions to access the mounted volumes. The volumes will show as empty.
+Permissions to access shared drives are tied to the username and password you
+use to set up shared drives. (See [Shared Drives](index.md#shared-drives).) If
+you run `docker` commands and tasks under a different username than the one used
+to set up shared drives, your containers will not have permissions to access the
+mounted volumes. The volumes will show as empty.
 
-The solution to this is to switch to the domain user account and reset credentials on shared drives.
+The solution to this is to switch to the domain user account and reset
+credentials on shared drives.
 
-Here is an example of how to de-bug this problem, given a scenario where you shared the `C` drive as a local user instead of as the domain user. Assume the local user is `samstevens` and the domain user is `merlin`.
+Here is an example of how to de-bug this problem, given a scenario where you
+shared the `C` drive as a local user instead of as the domain user. Assume the
+local user is `samstevens` and the domain user is `merlin`.
 
 1. Make sure you are logged in as the Windows domain user (for our example, `merlin`).
 
@@ -327,4 +368,4 @@ relates to Docker: [Docker fails to start on Windows
 10](https://github.com/docker/for-win/issues/27).
 
 For a temporary workaround, uninstall the firewall or anti-virus software, or explore other
-workarounds suggested on the forum.
+workarounds suggested on the forum.
