From 838524fb51daf2c380627b103da1356ba8b4cb1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oskar=20Sch=C3=B6ldstr=C3=B6m?= Date: Sat, 4 Jun 2016 10:00:20 -0400 Subject: [PATCH] Add docs --- README.md | 2 +- default.config.yml | 8 +++---- docs/deployment/composer.md | 48 +++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 4 files changed, 54 insertions(+), 5 deletions(-) create mode 100644 docs/deployment/composer.md diff --git a/README.md b/README.md index a2be814c3..9a81d8c56 100644 --- a/README.md +++ b/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 diff --git a/default.config.yml b/default.config.yml index c5b702d59..11119471d 100644 --- a/default.config.yml +++ b/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" diff --git a/docs/deployment/composer.md b/docs/deployment/composer.md new file mode 100644 index 000000000..d00a28b75 --- /dev/null +++ b/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" +``` diff --git a/mkdocs.yml b/mkdocs.yml index a802b3eee..681311816 100644 --- a/mkdocs.yml +++ b/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: