Improve docker and troubleshooting instructions (docs only)

docs/index.md

@@ -77,6 +77,6 @@ The DDEV project is committed to supporting [Semantic Version 2.0.0](https://sem
 ## Support
 
 - [ddev Documentation](https://ddev.readthedocs.io)
-- [ddev StackOverflow](https://stackoverflow.com/questions/tagged/ddev) for support and frequently asked questions
+- [ddev StackOverflow](https://stackoverflow.com/questions/tagged/ddev) for support and frequently asked questions. We respond quite quickly here and the results provide quite a library of user-curated solutions.
 - [ddev issue queue](https://github.com/drud/ddev/issues) for bugs and feature requests
-- The `#ddev` channel in [Drupal Slack](https://drupal.slack.com/messages/C5TQRQZRR) and [TYPO3 Slack](https://typo3.slack.com/messages/C8TRNQ601) for interactive, immediate community support
+- The `#ddev` channel in [Drupal Slack](https://www.drupal.org/slack) and [TYPO3 Slack](https://my.typo3.org/index.php?id=35) for interactive, immediate community support

docs/users/docker_installation.md

@@ -23,6 +23,8 @@ Docker Toolbox is only recommended for systems that absolutely won't run Docker-
 
 [Chocolatey](https://chocolatey.org/install) users: `choco install docker-toolbox`
 
+On Docker Toolbox you must by default have your project directory somewhere inside your home directory, as only the home directory is shared with Docker by default.
+
 
 ## Linux Installation: Docker-ce
 
@@ -45,18 +47,32 @@ After installing docker-ce you *must* install docker-compose separately. [Follow
 
 See [Docker's post-installation steps](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user). You need to add your linux user to the "docker" group. and normally set up docker to start on boot.
 
+<a name="troubleshooting"></a>
+## Testing and Troubleshooting Your Docker Installation
 
-## Testing Your Docker Installation
+Docker needs to be able to a few things for ddev to work:
 
-macOS or Linux: Run `docker-compose version && docker run -t -p 80:80 -v "$PWD:/tmp/homedir" busybox:latest ls /tmp/homedir` - you should see the contents of your home directory displayed.
+* Mount the project code directory from the host into the container; the project code directory is usually somewhere in a subdirectory of your home directory. 
+* Mount ~/.ddev for SSL cert cache and import-db. 
+* Access TCP ports on the host to serve HTTP and HTTPS. These are ports 80 and 443 by default, but they can be changed on a per-project basis.
 
-Windows in cmd window: Run `docker run -t -p 80:80 -v "%USERPROFILE%:/tmp/homedir" busybox ls /tmp/homedir` - you should see the contents of your home directory displayed.
+So we can use a single docker command to make sure that docker is set up to do what we want:
 
-Windows in git-bash window: run ` docker run -t -p 80:80 -v "$USERPROFILE:/tmp/homedir" busybox ls //tmp/homedir` - you should see the contents of your home directory displayed.
+**On Windows this command should be run in git-bash (or Docker Quickstart Terminal with Docker Toolbox).** In your project directory run `docker run --rm -t -p 80:80 -v "/$PWD:/tmp/projdir" -v "/$HOME:/tmp/homedir" busybox sh -c "echo ---- Project Directory && ls //tmp/projdir && echo ---- Home Directory && ls //tmp/homedir"` - you should see the contents of your home directory displayed. (On Windows, make sure you do this using git-bash or Docker Quickstart Terminal.)
 
-If any of these steps fails you'll need to troubleshoot. 
+If that fails (if you get an error, or you don't see the contents of your project directory and your home directory) you'll need to troubleshoot:
 
 * "port is already allocated": See [troubleshooting](troubleshooting.md).
+* `invalid mount config for type "bind": bind mount source path does not exist: <some path>` means the filesystem isn't successfully shared into the docker container.
 * "The path ... is not shared and is not known to Docker": Visit docker's preferences/settings->File sharing and share the appropriate path or drive.
 * "Error response from daemon: Get https://registry-1.docker.io/v2/" - Docker may not be running (restart it) or you may not have any access to the internet.
-* "403 authentication required": Try `docker logout` and do it again. 
+* "403 authentication required" when trying to `ddev start`: Try `docker logout` and do it again. Docker authentication is *not* required for any normal ddev action.
+
+If you are on Docker for Windows or Docker for Mac and you are seeing shared directories not show up in the web container (nothing there when you `ddev ssh`) then:
+
+* Unshare and then reshare the drive
+* Consider resetting Docker to factory defaults. This often helps in this situation because Docker goes through the whole authentication process again.
+
+If you are on Linux, the most common problem is having an old docker-compose, since the docker-compose that installs by default is incompatible with ddev. You'll find out about this right away because ddev will tell you on `ddev start` or most other ddev commands.
+
+If you are on Docker Toolbox on Windows, the most common problem is trying to put the project directory outside the home directory.

docs/users/extend/customization-extendibility.md

@@ -46,7 +46,7 @@ The default configuration for ddev uses nginx as the web server (`webserver_type
 - The `location ~ ^/(phpstatus|ping)$ {` block is required for the webserver container healthcheck to work.
 `
 - Any errors in your configuration may cause the web container to fail and try to restart, so if you see that behavior, use `ddev logs` to diagnose.
-- **IMPORTANT**: Changes to .ddev/nginx-site.conf take place on a `ddev restart` or when the container is rebuilt for another reason.
+- **IMPORTANT**: Changes to .ddev/nginx-site.conf take place on a `ddev rm && ddev start` or when the container is rebuilt for another reason.
 
 ## Providing custom apache configuration
 
@@ -60,15 +60,15 @@ If you're using `webserver_type: apache-fpm` or `webserver_type: apache-cgi` in
 - The alias `Alias "/phpstatus" "/var/www/phpstatus.php"` is required for the healthcheck script to work.
 `
 - Any errors in your configuration may cause the web container to fail and try to restart, so if you see that behavior, use `ddev logs` to diagnose.
-- **IMPORTANT**: Changes to .ddev/apache/apache-site.conf take place on a `ddev restart` (or when the container is rebuilt for another reason).
+- **IMPORTANT**: Changes to .ddev/apache/apache-site.conf take place on a `ddev rm && ddev start` (or when the container is rebuilt for another reason).
 
 ## Providing custom PHP configuration (php.ini)
 
 You can provide additional PHP configuration for a project by creating a directory called `.ddev/php/` and adding any number of php configuration ini files (they must be *.ini files). Normally, you should just override the specific option that you need to override. Note that any file that exists in `.ddev/php/` will be copied into `/etc/php/[version]/(cli|fpm)/conf.d`, so it's possible to replace files that already exist in the container. Common usage is to put custom overrides in a file called `my-php.ini`. Make sure you include the section header that goes with each item (like `[PHP]`)
 
 One interesting implication of this behavior is that it's possible to disable extensions by replacing the configuration file that loads them. For instance, if you were to create an empty file at `.ddev/php/20-xdebug.ini`, it would replace the configuration that loads xdebug, which would cause xdebug to not be loaded!
 
-To load the new configuration, just run a `ddev restart`.
+To load the new configuration, just run a `ddev rm && ddev start`.
 
 An example file in .ddev/php/my-php.ini might look like this:
 ```

docs/users/troubleshooting.md

@@ -1,6 +1,6 @@
 <h1>Troubleshooting</h1>
 
-Things might go wrong!
+Things might go wrong! Besides the suggestions on this page don't forget about [Stack Overflow](https://stackoverflow.com/tags/ddev) and [the ddev issue queue](https://github.com/drud/ddev/issues) and [other support options](https://ddev.readthedocs.io/en/latest/#support). And see [Docker troubleshooting suggstions](./docker_installation.md#troubleshooting).
 
 <a name="unable-listen"></a>
 ## Webserver ports are already occupied by another webserver
@@ -70,23 +70,32 @@ We welcome your [suggestions](https://github.com/drud/ddev/issues/new) based on
 <a name="container-restarts"></a>
 ## DDEV-Local reports container restarts and does not arrive at "ready"
 
-### Restarts of the database container
+## Restarts of the database container
 
-We've seen cases where this is caused by old databases that are not compatible with the current version of MariaDB that DDEV-Local is using. See [issue](https://github.com/drud/ddev/issues/615) for more information. The simple fix is to 
+The most common cause of the database container not coming up is a damaged database, so the mariadb server daemon is unable to start. This is typically caused by an unexpected docker event like system shutdown or docker exit which doesn't give the db container time to clean up and close connections. See [issue](https://github.com/drud/ddev/issues/748). In general, the easiest fix is to destroy and reload the database from either a database dump or a ddev snapshot. Otherwise, that issue has more ambitious approaches that may be taken if you have neither. But the easiest approach is this, which *will destroy and then reload your project database*:
 
-Note: Your project database will be destroyed by this procedure.
+1. `ddev remove --remove-data --omit-snapshot`
+2. mv .ddev .ddev.bak (renames the directory with config.yaml and docker-compose.yml and any custom nginx/php/mariadb config you may have added. Renaming it means .)
+3. `ddev config`
+4. `ddev start` 
+5. `ddev import-db` or `ddev restore-snapshot <snapshot-name>` if you have a db to import or a snapshot to restore.
 
-1. `ddev remove --remove-data`
-2. rm -r .ddev (removes the config.yaml and docker-compose.yml and any custom nginx/php/mariadb config you may have added. It makes sense to make a backup of these before proceeding.)
-3. `ddev start` 
-4. `ddev import-db` if you have a db to import
+Another approach to destroying the database is to destroy the docker volume where it is =stored with `docker volume rm <projectname>-mariadb`
 
-### Restarts of the web container
+## "web service unhealthy" or "web service starting" or exited 
 
-The most common cause of the web container restarting is a user-defined .ddev/nginx-site.conf or .ddev/apache/apache-site.conf - Please rename these to <xxx_site.conf> during testing. To figure out what's wrong with it after you've identified that as the problem, `ddev logs` will likely give the information you need.
+The most common cause of the web container being unhealthy is a user-defined .ddev/nginx-site.conf or .ddev/apache/apache-site.conf - Please rename these to <xxx_site.conf> during testing. To figure out what's wrong with it after you've identified that as the problem, use `ddev logs` and review the error.
 
-Changes to .ddev/nginx-site.conf and .ddev/apache/apache-site.conf take effect only when you do a `ddev restart` or the equivalent.
+Changes to .ddev/nginx-site.conf and .ddev/apache/apache-site.conf take effect only when you do a `ddev rm && ddev start` or the equivalent.
+
+## No input file specified (404) or Forbidden (403)
+
+If you get a 404 with "No input file specified" (nginx) or a 403 with "Forbidden" (apache) when you visit your project it may mean that no index.php or index.html is being found in the docroot. This can result from:
+
+* Missing index.php: There may not be an index.php or index.html in your project.
+* Misconfigured docroot: If the docroot isn't where the webserver thinks it is, then the webserver won't find the index.php. Look at your .ddev/config.yaml to verify it has a docroot that will lead to the index.php. It should be a relative path from the project root to the directory where the index.php is.
+* Docker not mounting your code: If you `ddev ssh` and `ls` and there's nothing there, Docker may not be mounting your code. See [docker installation](./docker_installation.md) for testing docker install. (Is Docker, the drive or directory where your project is must be shared. In Docker Toolbox it *must* be a subdirectory of your home directory unless you [make special accomodations for Docker Toolbox](http://support.divio.com/local-development/docker/how-to-use-a-directory-outside-cusers-with-docker-toolbox-on-windowsdocker-for-windows)).
 
 ## More Support
 
-Refer to the [support options](https://ddev.readthedocs.io/en/latest/#support) page.
+[Support options](https://ddev.readthedocs.io/en/latest/#support) has a variety of options.