Docs updates for v1.17, including mac M1 update to nfs script, fixes d…

…dev#2792, fixes ddev#2804 (ddev#2868)

* Don't let install_ddev.sh be run with sudo, fixes ddev#2792
* Add nfs setup script for mac m1
* Update docs for mac M1
* Add to FAQ about moving projects
* Mention that composer v2 is default

.spellcheckwordlist.txt

@@ -102,6 +102,8 @@ Usage
 Use
 Uses
 Uz
+VPN
+VPNs
 WAMP
 WSL
 WSL2
@@ -314,6 +316,7 @@ nfsd
 nfsmount
 nginx
 ngrok
+noerrors
 nolock
 not
 npm
@@ -403,12 +406,14 @@ susi
 symlink
 symlinks
 sys
+sysinternals
 system32
 systemctl
 systemd
 tableplus
 tasklist
 tcp
+tcpview
 test
 testddev
 tgz

docs/index.md

@@ -31,13 +31,13 @@ Docker and docker-compose are required before anything will work with DDEV. This
 
 ### Homebrew - macOS/Linux
 
-For macOS and Linux users, we recommend installing and upgrading via [Homebrew](https://brew.sh/) (macOS) or [Homebrew on Linux](https://docs.brew.sh/Homebrew-on-Linux) (Linux):
+For macOS (both amd64 and arm64) and Linux users, we recommend installing and upgrading via [Homebrew](https://brew.sh/) (macOS) or [Homebrew on Linux](https://docs.brew.sh/Homebrew-on-Linux) (Linux):
 
 ```
-brew tap drud/ddev && brew install ddev
+brew install drud/ddev/ddev
 ```
 
-If you would like more frequent "edge" releases then use `brew tap drud/ddev-edge` instead.)
+If you would like more frequent "edge" releases then use `brew install drud/ddev-edge/ddev` instead.)
 
 As a one-time initialization, run `mkcert -install`. Linux users may have to take additional actions as discussed below in "Linux `mkcert -install` additional instructions".
 

docs/users/alternate-uses.md

@@ -70,6 +70,14 @@ ExecStop=/usr/local/bin/ddev poweroff
 WantedBy=multi-user.target
 ```
 
+* ddev-router needs to be restarted in order to refresh the Let's Encrypt certificates, so you may have to `ddev poweroff` and `ddev start -a` every few weeks. Rebooting the server will accomplish this.
+* You'll likely want to turn off PHP errors to screen in a .ddev/php/noerrors.ini:
+
+```ini
+display_errors = Off
+display_startup_errors = Off
+```
+
 Caveats:
 
 * It's unknown how much traffic a given server and docker setup can sustain, or what the results will be if the traffic is more than the server can handle.

docs/users/cli-usage.md

@@ -14,7 +14,7 @@ Each of these commands has full help. For example, `ddev start -h` or `ddev help
 * `ddev sequelpro`, `ddev sequelace`, and `ddev tableplus` (macOS only, if the app is installed) give access to the Sequel Pro, Sequel Ace, or TablePlus database browser GUIs.
 * `ddev heidisql` (Windows/WSL2 only, if installed) gives access to the HeidiSQL database browser GUI.
 * `ddev import-db` and `ddev export-db` let you import or export a sql or compressed sql file.
-* `ddev composer` lets you run composer (inside the container), for example `ddev composer install` will do a full composer install for you without even needing composer on your computer. See [developer tools](developer-tools.md#ddev-and-composer).
+* `ddev composer` lets you run composer (inside the container), for example `ddev composer install` will do a full composer install for you without even needing composer on your computer. See [developer tools](developer-tools.md#ddev-and-composer). Composer version 2 is the default, but you can also configure composer version 1.
 * `ddev snapshot` makes a very fast snapshot of your database that can be easily and quickly restored with `ddev snapshot restore`.
 * `ddev share` works with [ngrok](https://ngrok.com/) (and requires ngrok) so you can let someone in the next office or on the other side of the planet see your project and what you're working on. `ddev share -h` gives more info about how to set up ngrok (it's easy).
 * `ddev ssh` opens a bash session in the web container (or other container).
@@ -31,7 +31,7 @@ In addition to the *commands* listed above, there are loads and loads of tools i
 
 * `ddev describe` tells how to access **MailHog**, which captures email in your development environment.
 * `ddev describe` tells how to use the built-in **phpMyAdmin** and `ddev launch -p` gives direct access to it.
-* Composer, git, node, npm, and dozens of other tools are installed in the web container, and you can access them via `ddev ssh` or `ddev exec`.
+* Composer, git, node, npm, and dozens of other tools are installed in the web container, and you can access them via `ddev ssh` or `ddev exec`. Composer v2 is the default. To use composer v1, `ddev config --composer-version=1`.
 * `ddev logs` gets you webserver logs; `ddev logs -s db` gets dbserver logs.
 * sqlite3 and the mysql client are inside the web container (and mysql client is also in the db container).
 
@@ -701,7 +701,7 @@ Commands can also be executed using the shorter `ddev . <cmd>` alias.
 
 The `ddev ssh` command will open an interactive bash or sh shell session to the container for a ddev service. The web service is connected to by default. The session can be ended by typing `exit`. To connect to another service, use the `--service` flag to specify the service you want to connect to. For example, to connect to the database container, you would run `ddev ssh --service db`. To specify the destination directory, use the `--dir` flag. For example, to connect to the database container and be placed into the `/home` directory, you would run `ddev ssh --service db --dir /home`.
 
-If you want to use your personal ssh keys within the web container, that's possible. Use `ddev auth ssh` to add the keys from your ~/.ssh directory and provide a passphrase, and then those keys will be usable from within the web container. You generally only have to `ddev auth ssh` one time per computer reboot.
+If you want to use your personal ssh keys within the web container, that's possible. Use `ddev auth ssh` to add the keys from your ~/.ssh directory and provide a passphrase, and then those keys will be usable from within the web container. You generally only have to `ddev auth ssh` one time per computer reboot. This is a very popular approach for accessing private composer repositories, or for using drush aliases against remote servers.
 
 ### Log Access
 

docs/users/developer-tools.md

@@ -38,6 +38,10 @@ To execute a fully-featured `composer create-project` command, you can execute t
 
 `ddev exec composer create-project ...`
 
+DDEV-Local uses composer version 2 by default. If you want to roll back to version 1, `ddev config --composer-version=1 && ddev start`
+
+If your composer.json is not in the project root, you'll need to provide the `-d` argument expressing the **in-container** path to the directory where the composer.json is, for example, `ddev composer install -d /var/www/html/path/to/dir`.
+
 Note: if you run `ddev composer global require`, (or run `composer global require` inside the web container) the global packages will be installed in the in-container user's home directory ( ~/.composer) and will disappear on the next container restart, requiring rerun of the command. You may need an additional step of synchronizing created composer configuration and installed packages with the DDEV's [homeadditions folder](extend/in-container-configuration.md) on the host.
 
 <a name="windows-os-and-ddev-composer"></a>

docs/users/faq.md

@@ -54,5 +54,23 @@
   4. `ddev start`
   5. `ddev import-db --src=/path/to/db.sql.gz`
 
+* **How can I move a project from one directory to another?**
+  1. `ddev stop --unlist`
+  2. Move the directory
+  3. `ddev start`
+
+* **How can I move a project from one computer to another?**
+  1. `ddev start && ddev snapshot`
+  2. `ddev stop --unlist`
+  3. Move the project directory to another computer any way you want.
+  4. On the new computer, `ddev start && ddev snapshot restore --latest`
+  5. Optionally, on the old computer, `ddev delete --omit-snapshot` to get rid of the database there.
+
+* **How can I move a project from traditional Windows to WSL2?**
+  This is exactly the same as moving a project from one computer to another, see above. Make sure you move the project into a native filesystem in WSL2, most likely /home.
+
 * **DDEV-Local wants to add a hostname to /etc/hosts but I don't think it should need to**.  If you see "The hostname <hostname> is not currently resolvable" and you *can* `ping <hostname>`, it may be that DNS resolution is slow. DDEV doesn't have any control of your computer's name resolution, so doesn't have any way to influence how your browser gets an IP address from a hostname. It knows you have to be connected to the Internet to do that, and uses a test DNS lookup of <somethingrandom>.ddev.site as a way to guess whether you're connected to the internet. If it is unable to do a name lookup, or if the hostname associated with your project is *not* \*.ddev.site, it will try to create entries in /etc/hosts, since it's assuming you can't look up your project's hostname(s) via DNS. If your internet (and name resolution) is actually working, but DNS is slow, just `ddev config global --internet-detection-timeout-ms=3000` to set the timeout to 3 seconds (or higher). See[issue link](https://github.com/drud/ddev/issues/2409#issuecomment-662448025) for more details. (If DNS rebinding is disallowed on your network/router, this won't be solvable without network/router changes. Help [here](https://github.com/drud/ddev/issues/2409#issuecomment-675083658) and [here](https://github.com/drud/ddev/issues/2409#issuecomment-686718237).) For more detailed troubleshooting information please see the [troubleshooting section](troubleshooting.md#ddev-starts-fine-but-my-browser-cant-access-the-url-url-server-ip-address-could-not-be-found-or-we-cant-connect-to-the-server-at-url).
 * **How can I configure a project with the defaults without hitting <RETURN> a bunch of times?** Just use `ddev config --auto` and it will choose docroot and project type based on the discovered code.
+
+* **Why do I get a 403 or 404 on my project after `ddev launch`?**
+  The most likely reason for this is that the docroot is misconfigured, or there's no index.php or index.html file in the docroot. Take a look at your .ddev/config.yaml and see what is there for the docroot. It should be a relative path to where your index.php is.

docs/users/performance.md

@@ -24,14 +24,16 @@ The steps to set up NFS mounting on any operating system are:
 
 Note that you can use the NFS setup described for each operating system below (and the scripts provided) or you can set up NFS any way that works for you. For example, if you're already using NFS with vagrant on macOS,and you already have a number of exports, the default export here (your home directory) won't work, because you'll have overlaps in your /etc/exports. Or on Windows, you may want to use an NFS server other than Winnfsd, for example the [Allegro NFS Server](https://nfsforwindows.com). The setups provided below and the scripts provided below are only intended to get you started if you don't already use NFS.
 
+Note that NFS does not really add to performance on Linux, so it is not recommended.
+
 ### macOS NFS Setup
 
 Download, inspect, make executable, and run the [macos_ddev_nfs_setup.sh](https://raw.githubusercontent.com/drud/ddev/master/scripts/macos_ddev_nfs_setup.sh) script. Use `curl -O https://raw.githubusercontent.com/drud/ddev/master/scripts/macos_ddev_nfs_setup.sh && chmod +x macos_ddev_nfs_setup.sh && ./macos_ddev_nfs_setup.sh`. This stops running ddev projects, adds your home directory to the /etc/exports config file that nfsd uses, and enables nfsd to run on your computer. This is a one-time setup. Note that this shares your home directory via NFS to any NFS client on your computer, so it's critical to consider security issues; It's easy to make the shares in /etc/exports more limited as well, as long as they don't overlap (NFS doesn't allow overlapping exports).
 
 If your DDEV-Local projects are set up outside your home directory, you'll need to edit /etc/exports to add a line for that share as well.
 `sudo vi /etc/exports` and copy the line the script has just created (`/System/Volumes/Data/Users/username -alldirs -mapall=<your_user_id>:20 localhost`), editing it with the additional path, e.g: `/Volumes/SomeExternalDrive -alldirs -mapall=<your_uid>:20 localhost`.
 
-__Warning:__ You may need to temporarily give your terminal "Full disk access" before you (or the script provided) can edit /etc/exports. If you're using iterm2, here are [full instructions for iterm2](https://gitlab.com/gnachman/iterm2/wikis/fulldiskaccess). The basic idea is that in the System Preferences -> Security and Privacy -> Privacy you need to give "Full Disk Access" permissions to your terminal app. Note that the "Full Disk Access" privilege is only needed when the /etc/exports file is being edited by you, usually a one-time event.
+__Warning:__ You may need to temporarily give your terminal "Full disk access" before you (or the script provided) can edit /etc/exports. The basic idea is that in the System Preferences -> Security and Privacy -> Privacy you need to give "Full Disk Access" permissions to your terminal app. Note that the "Full Disk Access" privilege is only needed when the /etc/exports file is being edited by you, usually a one-time event. (Note that in more recent versions of macOS a prompt will do this automatically and temporarily for you.)
 
 __Warning:__ If the projects are in a subdirectory of the ~/Documents directory or on an external drive, it is necessary to grant the "Full Disk Access" permission to the `/sbin/nfsd` binary. Full details are [below](#upgrading-catalina).
 
@@ -43,35 +45,24 @@ The executable components required for Windows NFS (winnfsd and nssm) are packag
 
 Also see the debugging section below, and the special Windows debugging section.
 
-### Debian/Ubuntu Linux NFS Setup
-
-The nfs_mount_enabled feature does not really add performance on Linux systems because Docker on Linux is already quite fast. The primary reason for using it on a Linux system would be just to keep consistent with other team members working on other host OSs. However, since one can now set up NFS globally with `ddev config global --nfs-mount-enabled` it no longer needs to be set up on a project-by-project basis, so most teams can get by with just leaving NFS mounting out of the project-level config.yaml.
-
-Note that for all Linux systems, you can and should install and configure the NFS daemon and configure /etc/exports as you see fit and share the directories that you choose to share. The Debian/Ubuntu Linux script is just one way of accomplishing it.
-
-Download, inspect, and run the [debian_ubuntu_linux_ddev_nfs_setup.sh](https://raw.githubusercontent.com/drud/ddev/master/scripts/debian_ubuntu_linux_ddev_nfs_setup.sh)). This stops running ddev projects, adds your home directory to the /etc/exports config file that nfs uses, and installs nfs-kernel-server  on your computer. This is one-time setup.
-
-Note that the script sets up a very restrictive /etc/exports that is based on the primary IP address of the Linux system at the time the script is run. You may want to edit it to make it less restrictive, or make it very open and use your firewall to control access.
-
 ### Debugging `ddev start` failures with `nfs_mount_enabled: true`
 
 There are a number of reasons that the NFS mount can fail on `ddev start`:
 
+* Firewall issues
 * NFS Server not running
 * Trying to start more than one NFS server.
 * NFS exports overlap. This is typically an issue if you've had another NFS client setup (like vagrant). You'll need to reconfigure your exports paths so they don't overlap.
 * Path of project not shared in `/etc/exports` (or `~/.ddev/nfs_exports.txt` on Windows)
-* Primary IP address not properly listed in /etc/exports (Linux)
 * Project is in the ~/Documents directory or an external drive on macOS Catalina or higher (see macOS information below)
 
 Tools to debug and solve permission problems:
 
 * Try `ddev debug nfsmount` in a project directory to see if basic NFS mounting is working. If that works, it's likely that everything else will.
 * When debugging, please do `ddev restart` in between each change. Otherwise, you can have stale mounts inside the container and you'll miss any benefit you may find in the debugging process.
 * Inspect the /etc/exports (or `~/.ddev/nfs_exports.txt` on Windows).
-* Restart the server (`sudo nfsd restart` on macOS, `sudo nssm restart nfsd` on Windows, `sudo systemctl restart nfs-kernel-server` on Debian/Ubuntu, other commands for other Unixes).
-* `showmount -e` on macOS or Linux will show the shared mounts.
-* On Linux, the primary IP address needs to be in /etc/exports. Temporarily set the share in /etc/exports to `/home *`, which shares /home with any client, and `sudo systemctl restart nfs-kernel-server`. Then start a ddev project doing an nfs mount, and `showmount -a` and you'll find out what the primary IP address in use is. You can add that address to /etc/exports.
+* Restart the server (`sudo nfsd restart` on macOS, `sudo nssm restart nfsd` on Windows).
+* `showmount -e` on macOS will show the shared mounts.
 
 <a name="upgrading-catalina"></a>
 
@@ -93,6 +84,7 @@ You should then see nfsd in the list as shown:
 
 ### macOS-specific NFS debugging
 
+* Please temporarily disable any firewall or VPN.
 * Use `showmount -e` to find out what is exported via NFS. If you don't see a parent of your project directory in there, then NFS can't work.
 * If nothing is showing, use `nfsd checkexports` and read carefully for errors
 * Use `ps -ef | grep nfsd` to make sure nfsd is running
@@ -108,6 +100,8 @@ nfs.server.verbose = 3
 
 ### Windows-specific NFS debugging
 
+* Please temporarily disable any firewall or VPN.
+
 * You can only have one NFS daemon running, so if another application has installed one, you'll want to use that NFS daemon and reconfigure it to allow NFS mounts of your projects.
 
 1. Stop the running winnfsd service: `sudo nssm stop nfsd`

docs/users/special-environments.md

@@ -0,0 +1,14 @@
+## Special Environments
+
+### Mac M1 Apple Silicon and Docker Desktop Technical Preview
+
+The Apple Mac M1 with its arm64 architecture has arrived to great acclaim. People love it.
+
+As of early 2021, to use Docker on the Mac M1 you must install the [Docker Desktop Technical Preview for Mac M1](https://docs.docker.com/docker-for-mac/apple-m1/). You may encounter issues with it, and if so you'll want to get into the [Docker Desktop for Mac Issue Queue](https://github.com/docker/for-mac/issues).
+
+There are a few limitations of DDEV-Local on the Mac M1.
+
+* Because Oracle is not (yet?) publishing packages for MySQL on arm64, there are no MySQL images in library/mysql. This means that DDEV-Local does not allow you to choose mysql as a database type.
+* Because MariaDB does not publish arm64 packages or images for versions that are out of support, only MariaDB 10.1 through 10.5 are supported by DDEV-Local.
+
+NFS mounting is supported and works well on the Mac M1, and the [NFS setup](https://ddev.readthedocs.io/en/latest/users/performance/#macos-nfs-setup) remains the same.