Add docs

README.md

@@ -52,7 +52,7 @@ If you want to switch from Drupal 8 (default) to Drupal 7 on the initial install
 
 ## Quick Start Guide
 
-This Quick Start Guide will help you quickly build a Drupal 8 site on the Drupal VM using the included example Drush make file. You can also use the Drupal VM with a [Composer based installation](@TODO), with a [Local Drupal codebase](http://docs.drupalvm.com/en/latest/deployment/local-codebase/) or even a [Drupal multisite installation](http://docs.drupalvm.com/en/latest/deployment/multisite/).
+This Quick Start Guide will help you quickly build a Drupal 8 site on the Drupal VM using the included example Drush make file. You can also use the Drupal VM with a [Composer based installation](http://docs.drupalvm.com/en/latest/deployment/composer/), with a [Local Drupal codebase](http://docs.drupalvm.com/en/latest/deployment/local-codebase/) or even a [Drupal multisite installation](http://docs.drupalvm.com/en/latest/deployment/multisite/).
 
 ### 1 - Install Vagrant
 

default.config.yml

@@ -21,8 +21,8 @@ vagrant_public_ip: ""
 # http://docs.drupalvm.com/en/latest/extras/syncing-folders/ for more info.
 vagrant_synced_folders:
   # The first synced folder will be used for the default Drupal installation, if
-  # build_makefile or build_composer is 'true'. By default it's set to the
-  # drupal-vm folder.
+  # any of the build_* settings are 'true'. By default the folder is set to
+  # the drupal-vm folder.
   - local_path: .
     destination: /var/www/drupalvm
     type: nfs
@@ -47,8 +47,8 @@ drupal_composer_path: "{{ config_dir }}/drupal.composer.json"
 drupal_composer_install_dir: "/var/www/drupalvm/drupal"
 drupal_composer_dependencies: []
 
-# Set this to 'true' and 'build_makefile' as well as 'build_composer' to
-# 'false' you are using Composer's create-project as a site deployment strategy.
+# Set this to 'true' and 'build_makefile', 'build_composer' to 'false' if you
+# are using Composer's create-project as a site deployment strategy.
 build_composer_project: false
 drupal_composer_project_package: ""
 drupal_composer_project_options: "--prefer-dist --stability dev --no-interaction"

docs/deployment/composer.md

@@ -0,0 +1,48 @@
+Drupal VM is configured to use [Drush make](drush-make.md) by default but supports building Drupal from a custom composer.json or creating a project from a composer package (`composer create-project`).
+
+## Using composer.json
+
+Add a `drupal.composer.json` next to your `config.yml` and switch the build system by setting `build_makefile: false` and `build_composer: true` in your `config.yml`. By default Drupal VM expects the Drupal code to be installed within a `docroot/` directory, if you use a different webroot directory, you need to adjust `drupal_core_path`.
+
+```yaml
+build_makefile: false
+build_composer: true
+```
+
+_The file set in `drupal_composer_path` (which defaults to `drupal.composer.json`) will be copied from your host computer into the VM's `drupal_composer_install_dir` and renamed `composer.json`. If you already have a composer.json within that directory, you can set `drupal_composer_path: false`._
+
+## Using Composer when [Drupal VM is a composer dependency itself](../other/drupalv-composer-dependency.md)
+
+In the scenario where you already have an existing `composer.json` in the root of your project, follow the usual steps for installing with a composer.json but instead of creating a `drupal.composer.json` file, disable the transfering of the file by setting `drupal_composer_path` to `false`, and change `drupal_composer_install_dir` to point to the the directory where it will be located. If `drupal_composer_path` is not truthy, Drupal VM assumes it already exists.
+
+```yaml
+build_makefile: false
+build_composer: true
+drupal_composer_path: false
+drupal_composer_install_dir: "/var/www/drupalvm"
+```
+
+## Creating a project from a composer package: `composer create-project`
+
+There's a couple of things you need to configure in your `config.yml`:
+
+- Switch the build system by setting `build_makefile: false`, `build_composer: false` and `build_composer_project: true`.
+- Configure the composer package in `drupal_composer_project_package`.
+- Additionally you can adjust the create-project CLI options in `drupal_composer_project_options` as well as add additional dependencies in `drupal_composer_dependencies`.
+- Ensure that the webroot configured in the composer package matches the one set in `drupal_core_path`. The default is `docroot/`.
+
+With [drupal-composer/drupal-project](https://github.com/drupal-composer/drupal-project) as an example your `config.yml` overrides would be:
+
+```yaml
+build_makefile: false
+build_composer: false
+build_composer_project: true
+
+drupal_composer_project_package: "drupal-composer/drupal-project:8.x-dev"
+# Added `--no-dev` to avoid installing development dependencies.
+drupal_composer_project_options: "--prefer-dist --stability dev --no-interaction --no-dev"
+drupal_composer_dependencies:
+  - "drupal/devel:8.*"
+
+drupal_core_path: "{{ drupal_composer_install_dir }}/web"
+```

mkdocs.yml

@@ -12,6 +12,7 @@ pages:
   - Home: 'index.md'
   - Drupal Deployment Strategies:
     - 'Drush Make file': 'deployment/drush-make.md'
+    - 'Composer': 'deployment/composer.md'
     - 'Local Drupal codebase': 'deployment/local-codebase.md'
     - 'Drupal multisite': 'deployment/multisite.md'
   - Extra Software and Setup: