docs: revise docs for dolphin (#64)

docs/arch/dolphin.md

@@ -0,0 +1,29 @@
+# Dolphin
+
+Dolphin is the next step forward in Mage2Docker local development environments. It's all the things you liked, without all the things you hated. We're using Dolphin to move forward to meet the original promise of "it just 'works' on all machines".
+
+## The Problem
+
+For the longest time, Graycore engineers (and external users who use Mage2Docker) have had to suffer mechanical differences between local Magento 2 environments depending upon which operating system that developer happens to be using.
+
+For example, MacOS developers had to either have both PHP and Composer installed in their host environments or [suffer the wrath of Docker-for-Mac file system performance issues.](https://github.com/docker/roadmap/issues/7)
+
+Developers working on Windows had to use WSL2 in order to get started. While WSL2 is a wonderful product, it adds additional complexity on top of an already complicated setup, further the barrier to entry to Magento development.
+
+Finally, for all three platforms, file-system permissions as a result of file mounting behaviors per platform were **the norm not the exception**, ultimately frustrating everyone involved.
+
+What had started as a "clone once, run everywhere" system was overly complicated and the abstraction behind it was extremely leaky.
+
+Queue 2021. Github CodeSpaces have become more and more common, and many users who previously leveraged PHPStorm to develop Magento 2 are happily switching over to VSCode because, for your average Magento user, the utility was the same (or greater), without the associated recurring license fee.
+
+As such, we feel like it is time to attempt to solve our cross-platform local development environment problems a different way.
+
+## The solution
+
+With the Mage2Docker Dolphin project, we've managed to finally abstract away the platform problem by leveraging VSCode's [Devcontainers](https://code.visualstudio.com/docs/remote/containers) or (if you have access to it) [Github Codespaces](https://github.com/features/codespaces).
+
+You can now TRULY develop cross-platform without concerning yourself with the underlying system behavior as you actually work directly inside the docker container, taking the guarantee of reproducible environments that were previously relegated to production environments to your local environment .
+
+## Trying it out
+
+So, that's a lot of talk and, as devs, we know [that the proof is in the pudding - let's get started](../stories/dolphin.md).

docs/stories/debugging/vscode/launch.json.dolphin

@@ -0,0 +1,23 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Listen for XDebug",
+            "hostname": "localhost",
+            "type": "php",
+            "request": "launch",
+            "port": 9003,
+            "pathMappings": {
+                "/var/www/html": "${workspaceRoot}"
+            },
+            "xdebugSettings": {
+                "max_data": 1000,
+                "max_children": 50,
+                "max_depth": 3
+            }
+        }
+    ]
+}

docs/stories/dolphin.md

@@ -0,0 +1,82 @@
+### Prerequisites
+
+* Docker
+* Git
+* VSCode
+
+### Clone Mage2Docker
+
+Mage2Docker defines a `docker-compose` environment for you. As such, we start by cloning the environment in your terminal of choice.
+
+```bash
+git clone https://www.github.com/graycoreio/mage2docker \
+    && cd mage2docker
+```
+
+### Setting up your Magento Account
+[The process of creating a Magento account is fully documented by Magento and you should follow their process](https://docs.magento.com/m2/ce/user_guide/magento/magento-account-create.html). 
+
+### Configuring Composer
+In case you have not done so, we will add your Magento composer authentication credentials to your user's local `auth.json`.
+
+First check to see if you have a credentials file under `~/.composer/auth.json`.
+
+```bash
+cat ~/.composer/auth.json
+```
+
+If you have a `auth.json` file here, you have most likely already configured your credentials and can skip to the next step.
+
+If you don't see your credentials there, [you can follow the Magento 2 guide to find your credentials](https://devdocs.magento.com/guides/v2.3/install-gde/prereq/connect-auth.html) and copy the `auth.json.sample` [found in the Magento 2 repo](https://github.com/magento/magento2/blob/2.4-develop/auth.json.sample) to your user's `auth.json` file: `~/.composer/auth.json` file and fill out the required credentials.
+
+```bash
+cp /path/to/magento/project/auth.json.sample ~/.composer/auth.json
+``` 
+
+### Per-project configuration
+We recommend using `auth.json` in your user's directory, but when you're working on multiple Magento 2 applications at once, you may need multiple `auth.json`. You can simply add the `auth.json` to the root of your Magento 2 project after project creation, and composer will use those credentials instead.
+
+### Configuring Docker Compose
+Mage2Docker comes with a basic environment configuration file `.env.sample`, you can utilize this file to tailor your environment to your needs. 
+
+#### Copy this file into a new `.env` file.**
+
+```bash
+cp .env.sample .env
+```
+
+You will need to uncomment the following configurations and select the [appropriate configurations](./configuring.md) for your environment. We've configured some basic defaults for out-of-the-box behavior.
+
+```bash
+COMPOSE_PROJECT_NAME
+```
+
+> For long-time users, you may note that COMPOSE_FILE is distinctly missing. Don't worry - all the old configuration behaviors previous supported by merging `yml` files together still work with Dolphin and `devcontainer`. This isn't documented quite yet, but we guarantee it will still work!
+
+> If you have multiple Magento projects on your system, **please ensure that the COMPOSE_PROJECT_NAME value is unique**, otherwise you will find out that you've accidentally shared data between different projects and you'll be in for a world of pain.
+
+### Configuring Your Hosts File
+Add the following entry to your **host** system's `/etc/hosts` file.
+
+```bash
+127.0.0.1 magento2.test
+```
+
+If you're using [WSL2, use this instead.](https://github.com/microsoft/WSL/issues/4983) Be sure to do this on the Windows host. 
+```bash
+127.0.0.1 magento2.test
+[::1] magento2.test
+```
+
+### Install the recommended VSCode Workspace extensions and the `devcontainer-cli`
+* [Install Recommended Extensions](../../.vscode/extensions.json)
+* [Install the devcontainer cli](https://code.visualstudio.com/docs/remote/devcontainer-cli)
+
+### Start your environment
+From your `mage2docker` repo:
+
+```bash
+devcontainer open
+```
+### See the Setup Page
+Now, you should be able to visit `https://magento2.test` in your browser and see a fresh Luma Magento store with Venia Sample data!

docs/stories/existing-project.md

@@ -96,6 +96,8 @@ docker-compose exec magento2 bin/magento setup:config:set --cache-backend=redis
 docker-compose exec magento2 bin/magento setup:config:set --page-cache=redis --page-cache-redis-server=fullpagecache --page-cache-redis-db=0
 docker-compose exec magento2 bin/magento setup:config:set --session-save=redis --session-save-redis-host=sessioncache --session-save-redis-db=0
 docker-compose exec magento2 bin/magento setup:config:set --amqp-host="message_queue" --amqp-port="5672" --amqp-user="guest" --amqp-password="guest"
+
+bin/magento deploy:mode:set developer
 ```
 
 ## Taking the Environment Down

docs/stories/reinstalling.md

@@ -7,8 +7,10 @@ Sometimes things go wrong and you have to rebuild your local environment from sc
 ## Delete the docker environment
 
 ```bash
-docker-compose down
-docker volume prune
+export $(grep -v '^#' .env | xargs)
+docker container stop $(docker container ls -aq --filter name=$COMPOSE_PROJECT_NAME*)
+docker container rm $(docker container ls -aq --filter name=$COMPOSE_PROJECT_NAME*)
+docker volume rm $(docker volume ls -q --filter name=$COMPOSE_PROJECT_NAME*)
 ```
 
 ## This time with feeling