Merge pull request #1088 from oxyc/docs-makeover

Issue #1092: Docs makeover

Author: geerlingguy

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/other/base-os.md renamed to docs/configurations/base-os.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/mariadb.md renamed to docs/configurations/databases-mariadb.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/mysql.md renamed to docs/configurations/databases-mysql.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/extras/postgresql.md renamed to docs/configurations/databases-postgresql.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/other/php.md renamed to docs/configurations/php.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/configurations/webservers-apache.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/configurations/webservers-nginx.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)._