Merge pull request #1088 from oxyc/docs-makeover

Issue #1092: Docs makeover

default.config.yml

@@ -90,9 +90,6 @@ drupal_site_install_extra_args: []
 # Cron jobs are added to the vagrant user's crontab. Keys include name
 # (required), minute, hour, day, weekday, month, job (required), and state.
 drupalvm_cron_jobs: []
-  # - name: "Drupal Cron"
-  #   minute: "*/30"
-  #   job: "drush -r {{ drupal_core_path }} core-cron"
 
 # Drupal VM automatically creates a drush alias file in your ~/.drush folder if
 # this variable is 'true'.

docs/extras/mariadb.md → docs/configurations/databases-mariadb.md

@@ -25,4 +25,4 @@ mysql_socket: /var/lib/mysql/mysql.sock
 mysql_log_error: /var/log/mariadb/mariadb.log
 mysql_syslog_tag: mariadb
 mysql_pid_file: /var/run/mariadb/mariadb.pid
-```
+```

docs/extras/mysql.md → docs/configurations/databases-mysql.md

@@ -2,7 +2,7 @@ By default, this VM is set up so you can manage MySQL databases on your own. The
 
 ## Connect using Adminer
 
-If you have `adminer` listed as one of the `installed_extras` inside `config.yml`, you can use Adminer's web-based interface to interact with databases. With Drupal VM running, visit `http://adminer.drupalvm.dev/`, and log in with `drupal` as the username and the password you set in `config.yml` (`drupal_db_password`). Leave the "Server" field blank. The "Database" field is optional.
+If you have `adminer` listed as one of the `installed_extras` inside `config.yml`, you can use Adminer's web-based interface to interact with databases. With Drupal VM running, visit [http://adminer.drupalvm.dev/](http://adminer.drupalvm.dev/), and log in with `drupal` as the username and the password you set in `config.yml` (`drupal_db_password`). Leave the "Server" field blank. The "Database" field is optional.
 
 More about how to use Adminer: [Adminer website](http://www.adminer.org/).
 

docs/extras/postgresql.md → docs/configurations/databases-postgresql.md

@@ -6,4 +6,4 @@ To switch from MySQL to PostgreSQL, switch the `drupalvm_database` setting in yo
 drupalvm_database: pgsql
 ```
 
-For more PostgreSQL configuration options, see the README included with the [`geerlingguy.postgresql`](https://galaxy.ansible.com/geerlingguy/postgresql/) Ansible role.
+For more PostgreSQL configuration options, see the [`geerlingguy.postgresql` Ansible role's README](https://github.com/geerlingguy/ansible-role-postgresql#readme).

docs/configurations/webservers-apache.md

@@ -0,0 +1,37 @@
+Drupal VM's configuration works with multiple operating systems _and_ with multiple webservers. You can switch between Apache and Nginx (depending on which server you prefer) with ease. Apache is the webserver used out of the box.
+
+You have complete control over all aspects of Apache VirtualHosts using the `apache_vhosts` configuration. A few simple examples are shown in `default.config.yml`, but this configuration can be much more complex.
+
+See the examples included in the [`geerlingguy.apache` Ansible role's README](https://github.com/geerlingguy/ansible-role-apache#readme) for more info, as well as many other variables you can override to configure Apache exactly how you like it.
+
+## Enable SSL Support with Apache
+
+To enable SSL support for you virtual hosts you first need a certificate file. You can generate a self-signed certificate with a command like
+
+    openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout example.key -out example.crt
+
+_If you're using an actual production certificate you should of course **NOT** track it in git but transfer it to the VM before running `vagrant provision`_
+
+Add the following to your `config.yml`:
+
+```yaml
+apache_vhosts_ssl:
+  - servername: "{{ drupal_domain }}"
+    documentroot: "{{ drupal_core_path }}"
+    certificate_file: "/vagrant/example.crt"
+    certificate_key_file: "/vagrant/example.key"
+    extra_parameters: "{{ apache_vhost_php_fpm_parameters }}"
+```
+
+### Using Ubuntu's snakeoil certificate
+
+If you are using Ubuntu as your base OS and you want to get started quickly with a local development environment you can use the snakeoil certificate that is already generated.
+
+```yaml
+apache_vhosts_ssl:
+  - servername: "{{ drupal_domain }}"
+    documentroot: "{{ drupal_core_path }}"
+    certificate_file: "/etc/ssl/certs/ssl-cert-snakeoil.pem"
+    certificate_key_file: "/etc/ssl/private/ssl-cert-snakeoil.key"
+    extra_parameters: "{{ apache_vhost_php_fpm_parameters }}"
+```

docs/configurations/webservers-nginx.md

@@ -0,0 +1,41 @@
+To use Nginx instead of Apache, change the `drupalvm_webserver` variable inside your customized `config.yml`, from `apache` to `nginx`.
+
+Because Nginx server directives behave a little differently than Apache's VirtualHosts, Drupal VM includes a custom Drupal-optimized Nginx server block configuration, and you can control all the servers ('virtual hosts') Nginx will run using the `nginx_hosts` configuration. A few simple examples are shown in `default.config.yml`, but you have some extra flexibility if you need it. See the `nginx-vhost.conf.j2` template for more information.
+
+Also, see the examples included in the [`geerlingguy.nginx` Ansible role's README](https://github.com/geerlingguy/ansible-role-nginx#readme) for more info, as well as many other variables you can override to configure Nginx exactly how you like it.
+
+_Note: if you're using php-fpm, you may want to reflect your use of nginx by setting `php_fpm_pool_user` and `php_fpm_pool_group` in your `config.yml`._
+
+## Enable SSL Support with Nginx
+
+To enable SSL support for you virtual hosts you first need a certificate file. See the same section under the [Apache documentation](webservers-apache.md#enable-ssl-support-with-apache) for how to generate a self-signed certficiate.
+
+Modify your nginx host configuration by adding the following `extra_parameters` to the first entry in `nginx_hosts`:
+
+```yaml
+- server_name: "{{ drupal_domain }} www.{{ drupal_domain }}"
+  root: "{{ drupal_core_path }}"
+  is_php: true
+  extra_parameters: |
+        listen 443 ssl;
+        ssl_certificate     /vagrant/example.crt;
+        ssl_certificate_key /vagrant/example.key;
+        ssl_protocols       TLSv1.1 TLSv1.2;
+        ssl_ciphers         HIGH:!aNULL:!MD5;
+```
+
+### Using Ubuntu's snakeoil certificate
+
+If you are using Ubuntu as your base OS and you want to get started quickly with a local development environment you can use the snakeoil certificate that is already generated.
+
+```yaml
+- server_name: "{{ drupal_domain }} www.{{ drupal_domain }}"
+  root: "{{ drupal_core_path }}"
+  is_php: true
+  extra_parameters: |
+        listen 443 ssl;
+        ssl_certificate     /etc/ssl/certs/ssl-cert-snakeoil.pem;
+        ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
+        ssl_protocols       TLSv1.1 TLSv1.2;
+        ssl_ciphers         HIGH:!aNULL:!MD5;
+```

docs/other/drupalvm-composer-dependency.md → docs/deployment/composer-dependency.md

@@ -10,9 +10,9 @@ composer require --dev geerlingguy/drupal-vm
 
 ### Setup your configuration files
 
-Add and configure the `config.yml` anywhere you like, in this example we place it in a `config/` directory. If you're using `build_makefile` this will be the default location Drupal VM looks for the `drupal.make.yml` file.
+Add and configure the `config.yml` anywhere you like, in this example we place it in a `config/` directory.
 
-_Note: This will be the directory where Drupal VM looks for other local configuration files as well. Such as [`local.config.yml` and `Vagrantfile.local`](overriding-configurations.md)._
+_Note: This will be the directory where Drupal VM looks for other local configuration files as well. Such as `build_makefile`, `local.config.yml` and `Vagrantfile.local`._
 
 ```
 ├── composer.json
@@ -29,7 +29,7 @@ _Note: This will be the directory where Drupal VM looks for other local configur
         └── drupal-vm/
 ```
 
-Change the build strategy to use your `composer.json` file by setting:
+Change the [build strategy to use your `composer.json`](composer.md#using-composer-when-drupal-vm-is-a-composer-dependency-itself) file by setting:
 
 ```yaml
 build_composer_project: false
@@ -41,9 +41,11 @@ drupal_core_path: "{{ drupal_composer_install_dir }}/docroot"
 
 If you intened to use the devel module, it must be added as a requirement to your `composer.json` file. Alternatively, if you do not intend to use it remove it from `drupal_enabled_modules` in your `config.yml` file:
 
-`drupal_enabled_modules: []`
+```yaml
+drupal_enabled_modules: []
+```
 
-If you're using `pre_provision_scripts` or `post_provision_scripts` you also need to adjust their paths to take into account the new directory structure. The examples used in `default.config.yml` assume the files are located in the Drupal VM directory. If you use relative paths you need to the ascend the directory tree as far as the project root, but using the `config_dir` variable you get the absolute path of where you `config.yml` is located.
+If you're using `pre_provision_scripts` or `post_provision_scripts` you also need to adjust their paths to take into account the new directory structure. The examples used in `default.config.yml` assume the files are located in the Drupal VM directory. You can use the `config_dir` variable which is the absolute path of the directory where your `config.yml` is located.
 
 ```yaml
 post_provision_scripts:
@@ -101,9 +103,9 @@ vagrant up
 
 _Important: you should never issue `vagrant` commands through Drupal VM's own `Vagrantfile` from now on. If you do, it will create a secondary VM in that directory._
 
-## Drupal VM without composer
+## Drupal VM in a subdirectory without composer
 
-If you don't use `composer` in your project you can still download  Drupal VM (or add it as a git submodule) to any subdirectory in your project. As an example let's name that directory `box/`.
+If you're not using `composer` in your project you can still download  Drupal VM (or add it as a git submodule) to any subdirectory in your project. As an example let's name that directory `box/`.
 
 ```
 ├── docroot/

docs/deployment/composer-package.md

@@ -0,0 +1,18 @@
+Out of the box Drupal VM is configured to use `composer create-project` to build a Drupal 8 codebase.
+
+This is set up with the following variables in `config.yml`:
+
+  - Composer will build the project if `build_composer_project` is `true`, and `build_makefile` and `build_composer` are both `false`.
+  - The Composer package is defined by `drupal_composer_project_package`.
+  - 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 set to `web/`.
+
+With [acquia/lightning-project](https://github.com/acquia/lightning-project) as an example your `config.yml` settings would be:
+
+```yaml
+drupal_composer_project_package: "acquia/lightning-project:^8.1.0"
+drupal_composer_project_options: "--prefer-dist --stability rc --no-interaction"
+drupal_core_path: "{{ drupal_composer_install_dir }}/docroot"
+```
+
+_Opting for composer based installs will most likely increase your VM's time to provision considerably. Find out how you can [improve composer build performance](../other/performance.md#improving-composer-build-performance)._

docs/deployment/composer.md

@@ -1,6 +1,4 @@
-Drupal VM is configured to use `composer create-project` to build a Drupal 8 codebase by default but supports building Drupal from a custom composer.json or [Drush make file](drush-make.md).
-
-## Using composer.json
+Drupal VM is configured to use `composer create-project` to build a Drupal 8 codebase by default but supports building Drupal from a custom `composer.json` file as well.
 
 1. Copy `example.drupal.composer.json` to `drupal.composer.json` and modify it to your liking.
 2. Use the Composer build system by setting `build_composer: true` in your `config.yml` (make sure `build_makefile` and `build_composer_project` are set to `false`).
@@ -12,11 +10,11 @@ build_composer: true
 drupal_core_path: "{{ drupal_composer_install_dir }}/docroot"
 ```
 
-_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, set `drupal_composer_path: false`._
+_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`._
 
-## Using Composer when [Drupal VM is a composer dependency itself](../other/drupalvm-composer-dependency.md)
+## Using Composer when [Drupal VM is a composer dependency itself](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: 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.
+In the scenario where you 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: 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_composer_project: false
@@ -26,31 +24,4 @@ drupal_composer_install_dir: "/var/www/drupalvm"
 drupal_core_path: "{{ drupal_composer_install_dir }}/docroot"
 ```
 
-## Creating a project from a composer package: `composer create-project`
-
-This is the default Drupal VM build configuration, set up by the following settings in `config.yml`:
-
-  - Composer will build the project if `build_composer_project` is `true`, and `build_makefile` and `build_composer` are both `false`.
-  - The Composer package is defined by `drupal_composer_project_package`.
-  - 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 set to `web/`.
-
-With [acquia/lightning-project](https://github.com/acquia/lightning-project) as an example your `config.yml` settings would be:
-
-```yaml
-drupal_composer_project_package: "acquia/lightning-project:^8.1.0"
-drupal_composer_project_options: "--prefer-dist --stability rc --no-interaction"
-drupal_core_path: "{{ drupal_composer_install_dir }}/docroot"
-```
-
-## Improving composer build performance
-
-Opting for composer based installs will most likely increase your VM's time to provision considerably.
-
-If you manage multiple VM's own your computer, you can use the [`vagrant-cachier` plugin](http://fgrehm.viewdocs.io/vagrant-cachier/) to share Composer's package cache across all VM's. The first build will be as slow as before but subsequent builds with the same `vagrant_box` (eg `geerlingguy/ubuntu1604`) will be much faster.
-
-Install the plugin on your host computer: `vagrant plugin install vagrant-cachier`.
-
-Drupal VM's `Vagrantfile` includes the appropriate `vagrant-cachier` configuration to cache Composer and apt dependencies.
-
-_You can also use this plugin to share other package manager caches. For more information read the [documentation](http://fgrehm.viewdocs.io/vagrant-cachier/usage/)._
+_Opting for composer based installs will most likely increase your VM's time to provision considerably. Find out how you can [improve composer build performance](../other/performance.md#improving-composer-build-performance)._

docs/deployment/drush-make.md

@@ -1,6 +1,4 @@
-Drupal VM is configured to use Composer by default to build a Drupal site on the VM inside `/var/www/drupalvm/drupal/web` (in a folder that's synced to your local machine, so you can work with the Drupal codebase either locally or inside the VM).
-
-If you want to build a Drupal site using a [Drush make file](http://www.drush.org/en/master/make/) instead, set `build_composer_project: false`, `build_makefile: true` and either use the `example.drupal.make.yml` file as a base, or use your own Drush make file: just place it or symlink it into the root of the Drupal VM folder with the filename `drupal.make.yml`. You can also set a separate path to the makefile using the `drush_makefile_path` variable.
+If you want to build a Drupal site using a [Drush make file](http://www.drush.org/en/master/make/) instead of composer, set `build_composer_project: false`, `build_makefile: true` and either use the `example.drupal.make.yml` file as a base, or use your own Drush make file: just place it or symlink it into the root of the Drupal VM folder with the filename `drupal.make.yml`. You can also set a separate path to the makefile using the `drush_makefile_path` variable.
 
 ```yaml
 build_composer_project: false

docs/deployment/local-codebase.md

@@ -11,9 +11,11 @@ vagrant_synced_folders:
     type: nfs
 ```
 
+_If you have Drupal VM installed within your codebase, you can also set the `local_path` to a location relative to the `Vagrantfile`. This is the default setup in `default.config.yml`._
+
 ## Disable the Composer project build and site install
 
-Set all the `build_` variables and `install_site` to `false`:
+Set all the `build_*` variables and `install_site` to `false`:
 
 ```yaml
 build_makefile: false
@@ -39,13 +41,13 @@ This variable will be used for the document root of the webserver.
 
 By default the domain of your site will be `drupalvm.dev` but you can change it by setting `drupal_domain` to the domain of your choice:
 
-```
+```yaml
 drupal_domain: "local.my-drupal-site.com"
 ```
 
 If you prefer using your domain as the root of all extra packages installed, ie. `adminer`, `xhprof` and `pimpmylog`, set it as the value of `vagrant_hostname` instead.
 
-```
+```yaml
 vagrant_hostname: "my-drupal-site.com"
 drupal_domain: "{{ vagrant_hostname }}"
 ```
@@ -56,4 +58,4 @@ If you have your Drupal site configured to use a special database and/or user/pa
 
 ## Build the VM, import your database
 
-Run `vagrant up` to build the VM with your codebase synced into the proper location. Once the VM is created, you can [connect to the MySQL database](../extras/mysql.md) and import your site's database to the Drupal VM, or use a [command like `drush sql-sync`](../extras/drush.md#using-sql-sync) to copy a database from another server.
+Run `vagrant up` to build the VM with your codebase synced into the proper location. Once the VM is created, you can [connect to the MySQL database](../configurations/databases-mysql.md) and import your site's database to the Drupal VM, or use a [command like `drush sql-sync`](../extras/drush.md#using-sql-sync) to copy a database from another server.

docs/extending/ansible-args.md

@@ -0,0 +1,23 @@
+## Passing arguments to ansible during a provision
+
+You can specify an additional argument to the `ansible-playbook` command by using the `DRUPALVM_ANSIBLE_ARGS` environment variable. This can be useful when debugging a task failure.
+
+_Currently this feature has two quirks. It's only possible to pass on a single argument. You should not quote a flag's value as you would normally do in the shell._
+
+Display verbose ansible output:
+
+```sh
+DRUPALVM_ANSIBLE_ARGS='--verbose' vagrant provision
+```
+
+Begin the provisioning at a particular task:
+
+```sh
+DRUPALVM_ANSIBLE_ARGS='--start-at-task=*post-provision shell*' vagrant provision
+```
+
+Override a config variable:
+
+```sh
+DRUPALVM_ANSIBLE_ARGS='--extra-vars=drupalvm_database=pgsql' vagrant provision
+```