Update project docs for new devsetup.

README.md.dist

@@ -3,40 +3,79 @@ developed by drunomics GmbH, [email protected]
 
 This project is maintained using composer. Please refer to the documentation provided at https://github.com/drupal-composer/drupal-project and https://www.drupal.org/node/2471553.
 
-## Project setup
+## Prerequesites
 
- * Run `vagrant up` (see Vagrant section below).
- * Initialize settings.php and dotenv:
-   ```
-   composer install
-   ./vendor/bin/phapp setup vagrant
-   ```
+ * Install docker and [docker-compose](https://docs.docker.com/compose/install/) - use version 1.22.0 or later.
 
- * If you cannot use the drunomics vagrant environment, you need to customize
-   the provided settings.php. Instead of linking the settings.vagrant.php, copy
-   it to settings.php and customize it to your needs. Usually, you'd have to
-   customize the database connection and the 'trusted_host_patterns'.
+ * Install phapp (see tools) - or use the project-local version if preferred:
 
-## drunomics setup notes
+        composer install-phar-tools
+        export PATH=./vendor/bin/:$PATH
 
-- The vagrant setup is added in the project, thus no special setup is required.
-- The drunomics drush extension is *not* added to the project. It's deprecated.
-- For managing the project use the respective phapp comands, see
-  http://github.com/drunomics/phapp-cli and or run `./vendor/bin/phapp list` for
-  an overview.
+ * If your user ID is not 1000, run the following commands to
+   automatically set a suitable environment variable on every startup:
+
+        # Check ID:
+        id -u $USER
+        # If not 1000, run:
+        echo "# Allow docker-compose setup to switch to the correct user." >> ~/.bashrc
+        echo "export COMPOSE_DEFAULT_USER=$(id -u $USER)" >> ~/.bashrc
+        bash
+
+## Project devsetup
+
+To setup the project, ensure you have all prerequesites fullfilled and follow next steps:
+
+ * Optional: Drop container and data from previous runs:
+
+        docker-compose down -v
+
+ * Initialize setup and run docker compose
+
+        phapp setup localdev
+        phapp build
+        docker-compose up -d --build
+
+* Build the app:
+
+        phapp build
+
+ * Run `phapp init` to quickly initialize the application.
+
+         docker-compose exec cli phapp init --no-build
+
+## Localdev project URLs
+
+| Url | Webroot | Description |
+| --- | ------- | ----------- |
+| http://example.{{ project }}.localdev.space/ | web | the Example site |
+
+## Docker-compose - IMPORTANT NOTES.
+
+For now most phapp and drush must be from inside the docker container.
+Do so via
+
+    docker-compose exec cli phapp init --no-build
+    docker-compose exec cli drush cr
+
+However, the exception is `phapp build`. Run it on the host so that your SSH key(s)
+are picked up and you can access private repositories:
+
+    phapp build
+
+During development it's convenient to permanently switch to the docker cli container:
+
+    docker-compose exec cli bash
+    drush cr
 
 ## Command line tools
 
 ### Phapp
-Version 0.6.2 or later is required. Either install it globally and run `phapp`
+Version 0.6.7 or later is required. Either install it globally and run `phapp`
 or execute the embedded phapp version from the root repository directory:
 
 ```./vendor/bin/phapp ```
 
-*Note*:
-If phapp is not installed globally, `./vendor/bin/phapp` must be used instead of
-just `phapp` always.
-
 Refer to [the project page](http://github.com/drunomics/phapp-cli) for
 instructions on how to install phapp globally.
 
@@ -54,62 +93,46 @@ instructions on how to install phapp globally.
 - Commands for setting up or updating the project:
 
 ```
-# Initialize the setup.
-phapp setup vagrant
+# Get in the docker web container (where you can use the phapp commands)
+docker-compose exec cli bash
 
-# Initialize the application, after building it:
-phapp init
+# Quick-install the application for development:
+docker-compose exec cli phapp init --no-build
 
 # Update the build and run updates after switching branches:
-phapp update
+phapp build
+docker-compose exec cli phapp update --no-build
 
-# Install from scratch.
-phapp install
+# Install the app from scratch:
+docker-compose exec cli phapp install
 ```
-
-If composer install has been run and one wants to skip building again during
-init or update, one can pass the --no-build option like so:
-
-```
-composer install
-phapp init --no-build
-phapp update --no-build
-```
-
 The commands executed can be found in `phapp.yml`.
 
-*Note*: If phapp is not installed globally or missing, refer to the "Phapp"
-section under "Command line tools" above.
-
 - During development, some useful commands are:
 
 ```
 # Config export (export your config changes):
-drush cex -y
+docker-compose exec cli drush cex -y
 
 # Config import (manual import of config files):
-drush cim -y
+docker-compose exec cli drush cim -y
 
 # Cache clear/rebuild:
-drush cr
+docker-compose exec cli drush cr
 ```
 
 ## Running tests
 
-Tests are implemented using behat. To run all tests, a recent chrome browser
-(59+) that is used for headless tests.
+Tests are implemented using behat and use a headless chrome browser for javascript enabled tests:
 
-To run the tests in the vagrant environment the following commands can be used:
+To run the tests:
 
     ./tests/behat/run.sh
 
 Any further arguments are forwarded to behat:
 
     ./tests/behat/run.sh --tags=javascript
 
-By default chrome is shown. To run it in headless mode use:
-
-    HEADLESS=1 ./tests/behat/run.sh
 
 ## Coding style
 
@@ -140,24 +163,3 @@ Configure the following settings:
   - Show sniff name "true"
   - Coding standard: "custom", make it point to the phpcs.xml.dist file in the
     vcs root.
-
-## Vagrant
-
-The following describes the local development using Vagrant.
-
-### Prerequesites
-
- - Make sure latest docker and vagrant versions are installed.
- - Make sure necessary vagrant plugins are installed:
-
-       vagrant plugin install vagrant-hosts-provisioner
-
-### Using vagrant
-
-  You can access the site http://{{ project }}.local. The project name is
-  defined in devsetup/project.yml.
-
- * vagrant up - Starts the container.
- * vagrant halt - Stops the container
- * vagrant reload - Restarts the container.
- * vagrant provision - Provisions the container again.