diff --git a/default.config.yml b/default.config.yml index ef61c425b..167c59797 100644 --- a/default.config.yml +++ b/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'. diff --git a/docs/other/base-os.md b/docs/configurations/base-os.md similarity index 100% rename from docs/other/base-os.md rename to docs/configurations/base-os.md diff --git a/docs/extras/mariadb.md b/docs/configurations/databases-mariadb.md similarity index 99% rename from docs/extras/mariadb.md rename to docs/configurations/databases-mariadb.md index 44ab0a268..b24a475be 100644 --- a/docs/extras/mariadb.md +++ b/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 -``` \ No newline at end of file +``` diff --git a/docs/extras/mysql.md b/docs/configurations/databases-mysql.md similarity index 81% rename from docs/extras/mysql.md rename to docs/configurations/databases-mysql.md index 73668dd9b..6b9cc3642 100644 --- a/docs/extras/mysql.md +++ b/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/). diff --git a/docs/extras/postgresql.md b/docs/configurations/databases-postgresql.md similarity index 68% rename from docs/extras/postgresql.md rename to docs/configurations/databases-postgresql.md index 68786bc93..823bda1d8 100644 --- a/docs/extras/postgresql.md +++ b/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). diff --git a/docs/other/php.md b/docs/configurations/php.md similarity index 100% rename from docs/other/php.md rename to docs/configurations/php.md diff --git a/docs/configurations/webservers-apache.md b/docs/configurations/webservers-apache.md new file mode 100644 index 000000000..2edce6b34 --- /dev/null +++ b/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 }}" +``` diff --git a/docs/configurations/webservers-nginx.md b/docs/configurations/webservers-nginx.md new file mode 100644 index 000000000..e2065229b --- /dev/null +++ b/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; +``` diff --git a/docs/other/drupalvm-composer-dependency.md b/docs/deployment/composer-dependency.md similarity index 83% rename from docs/other/drupalvm-composer-dependency.md rename to docs/deployment/composer-dependency.md index 02113678f..7209dcae7 100644 --- a/docs/other/drupalvm-composer-dependency.md +++ b/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/ diff --git a/docs/deployment/composer-package.md b/docs/deployment/composer-package.md new file mode 100644 index 000000000..816d56f31 --- /dev/null +++ b/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)._ diff --git a/docs/deployment/composer.md b/docs/deployment/composer.md index 3a53d1d43..d64f2ecf1 100644 --- a/docs/deployment/composer.md +++ b/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)._ diff --git a/docs/deployment/drush-make.md b/docs/deployment/drush-make.md index 7a167c17f..f7fce8a9c 100644 --- a/docs/deployment/drush-make.md +++ b/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 diff --git a/docs/deployment/local-codebase.md b/docs/deployment/local-codebase.md index 4f0e82f6f..607da6152 100644 --- a/docs/deployment/local-codebase.md +++ b/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. diff --git a/docs/extending/ansible-args.md b/docs/extending/ansible-args.md new file mode 100644 index 000000000..4d524aabe --- /dev/null +++ b/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 +``` diff --git a/docs/extras/scripts.md b/docs/extending/scripts.md similarity index 90% rename from docs/extras/scripts.md rename to docs/extending/scripts.md index c3c71cc45..af42cf40d 100644 --- a/docs/extras/scripts.md +++ b/docs/extending/scripts.md @@ -21,7 +21,7 @@ Place your pre and post provision scripts inside a `scripts` directory in the ro ## Ansible task files -To use an extra ansible task file, configure the path to the file (relative to `provisioning/files/`) in `config.yml`: +To use an extra ansible task file, configure the path to the file (relative to `provisioning/playbook.yml`) in `config.yml`: ```yaml pre_provision_tasks_dir: "../scripts/pre/*" @@ -34,7 +34,7 @@ The files matched will run in alphabetical order, and as with shell scripts, pre ## Ansible playbooks -Out of the box Drupal VM does not support running additional playbooks or adding your own roles but using [`Vagrantfile.local`](../other/overriding-configurations.md#extending-the-vagrantfile-with-vagrantfilelocal) you can add any number of additional provisioners to vagrant. +Out of the box Drupal VM does not support running additional playbooks or adding your own roles but using [`Vagrantfile.local` you can add any number of additional provisioners to vagrant](vagrantfile.md). As an example you might have a `local.playbook.yml` with it's own dependencies defined in `local.requirements.yml`. Place both of these next to your `config.yml` and add the following `Vagrantfile.local`. diff --git a/docs/other/overriding-configurations.md b/docs/extending/vagrantfile.md similarity index 52% rename from docs/other/overriding-configurations.md rename to docs/extending/vagrantfile.md index ac430a1d7..c7b96db7e 100644 --- a/docs/other/overriding-configurations.md +++ b/docs/extending/vagrantfile.md @@ -1,37 +1,4 @@ -## Overriding Drupal VM's `default.config.yml` with `config.yml` - -If available, Drupal VM will load a `config.yml` where you can override any of the defaults set in `default.config.yml`. Commonly this is a copy of `default.config.yml` with the values tweaked to your own project. For an easier upgrade path you would only set the values you are actually overriding. - -```yaml -vagrant_box: geerlingguy/centos7 -vagrant_hostname: my-custom-site.dev -vagrant_machine_name: my_custom_site -``` - -## Overriding variables with a `local.config.yml` - -If available, Drupal VM will also load a `local.config.yml` after having loaded the main `config.yml`. Using this file you can override variables previously defined in `config.yml`. For teams who are sharing a VM configuration, this is a good place to configure anything that's specific to your own environment. - -```yaml -# Increase the memory available to your Drupal site. -vagrant_memory: 1536 -php_memory_limit: "512M" - -# Override the synced folders to use rsync instead of NFS. -vagrant_synced_folders: - - local_path: . - destination: /var/www/drupalvm - type: rsync - create: true -``` - -_Note: The merge of the variables in these two files is shallow, so if you want to override a single item in a list, you will need to re-define all items in that list._ - -## Extending the `Vagrantfile` with `Vagrantfile.local` - -Out of the box Drupal VM supports having VirtualBox, Parallels as well as VMware as a provider. Besides these there are multitude of others available (for example `vagrant-aws`, `vagrant-digitalocean`). - -If you want to use an unsupported provider, or otherwise modify the vagrant configuration in a way that is not exposed by Drupal VM, you can create a `Vagrantfile.local` in the root directory of this project. +Out of the box Drupal VM supports having VirtualBox, Parallels as well as VMware as a provider. Besides these there are multitude of others available (for example `vagrant-aws`, `vagrant-digitalocean`). If you want to use an unsupported provider, or otherwise modify the vagrant configuration in a way that is not exposed by Drupal VM, you can create a `Vagrantfile.local` next to your `config.yml`. The file will be sourced at the end of the `Vagrant.configure` block so you will have access to Vagrant's `config.vm` object as well as the contents of the `config.yml` file within the `vconfig` hash. @@ -106,27 +73,3 @@ end ``` _For additional configuration options read [Vagrant Proxyconf's README](https://github.com/tmatilai/vagrant-proxyconf#readme)._ - -## 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 -``` diff --git a/docs/extras/adminer.md b/docs/extras/adminer.md new file mode 100644 index 000000000..54392c568 --- /dev/null +++ b/docs/extras/adminer.md @@ -0,0 +1,3 @@ +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. + +For a list of available role variables, see the [`geerlingguy.adminer` Ansible role's README](https://github.com/geerlingguy/ansible-role-adminer#readme). diff --git a/docs/extras/blackfire.md b/docs/extras/blackfire.md new file mode 100644 index 000000000..7f911959b --- /dev/null +++ b/docs/extras/blackfire.md @@ -0,0 +1,23 @@ +[Blackfire.io](https://blackfire.io/) is a service that allows code profiling to be stored and analyzed via an online profile on the Blackfire.io website. + +It doesn't require any additional Drupal modules to use, but once you've made sure `blackfire` is in the list of `installed_extras` in `config.yml` (and Drupal VM has been provisioned), you need to log into Drupal VM and [run the setup steps outlined on the Blackfire Ansible role's README](https://github.com/geerlingguy/ansible-role-blackfire#requirements). + +**Note**: You should only enable one code profiler at a time—e.g. when using [Blackfire](blackfire.md), disable [XHProf](xhprof.md), [Tideways](tideways.md) and [XDebug](xdebug.md). + +Once you've configured your environment for your own Blackfire account, you can profile a request with Blackfire by running something like the following example (within Drupal VM, after logging in with `vagrant ssh`): + +``` +$ blackfire curl http://drupalvm.dev/ +Profiling: [########################################] 10/10 +Blackfire cURL completed +Graph URL https://blackfire.io/profiles/[UUID]/graph + +Wall Time 151ms +CPU Time 130ms +I/O Time 20.9ms +Memory 1.5MB +Network n/a n/a - +SQL n/a - +``` + +For a list of available role variables, see the [`geerlingguy.blackfire` Ansible role's README](https://github.com/geerlingguy/ansible-role-blackfire#readme). diff --git a/docs/extras/drupal-console.md b/docs/extras/drupal-console.md index 82c24452f..98f75e3d5 100644 --- a/docs/extras/drupal-console.md +++ b/docs/extras/drupal-console.md @@ -36,3 +36,5 @@ Execute from host machine using the `--target` option. drupal --target=drupalvm.dev site:status For more details, see [Drupal Console's documentation](https://hechoendrupal.gitbooks.io/drupal-console/content/en/using/how-to-use-drupal-console-in-a-remote-installation.html) + +For a list of available role variables, see the [`geerlingguy.drupal-console` Ansible role's README](https://github.com/geerlingguy/ansible-role-drupal-console#readme). diff --git a/docs/extras/drush.md b/docs/extras/drush.md index c0b6ab96c..29fb98365 100644 --- a/docs/extras/drush.md +++ b/docs/extras/drush.md @@ -1,4 +1,4 @@ -If you have Drush and Ansible installed on your host workstation, and would like to interact with a Drupal site running inside Drupal VM, there are drush aliases automatically created by Drupal VM for each of the virtual hosts you have configured. +If you have [Drush](http://www.drush.org) and Ansible installed on your host workstation, and would like to interact with a Drupal site running inside Drupal VM, there are drush aliases automatically created by Drupal VM for each of the virtual hosts you have configured. With the example configuration, you can manage the example Drupal site using the Drush alias `@drupalvm.dev`. For example, to check if Drush can connect to the site in Drupal VM, run: @@ -39,7 +39,7 @@ You can disable Drupal VM's automatic Drush alias file management if you want to ## Using sql-sync -For sql-sync to work between two remotes make sure you are running Drush 8.0.3 or later on your host and your guest machine, as well as 7.1.0 or later on the remote. +_For sql-sync to work between two remotes make sure you are running Drush 8.0.3 or later on your host and your guest machine, as well as 7.1.0 or later on the remote._ If you're locked to an older version of Drush, it is likely that Drush will try to run the command from the `@destination` instead of from your host computer, which means you need to move your `@remote` alias to Drupal VM as well. You can place the file in any of the [directories Drush searches](https://github.com/drush-ops/drush/blob/5a1328d6e9cb919a286e70360df159d1b4b15d3e/examples/example.aliases.drushrc.php#L43:L51), for example `/home/vagrant/.drush/.aliases.drushrc.php`. @@ -48,3 +48,18 @@ If you're still having issues, you can avoid `sql-sync` entirely and pipe the my ``` drush @remote sql-dump | drush @drupalvm.drupalvm.dev sql-cli ``` + +## Running `drush core-cron` as a cron job. + +Using the `drupalvm_cron_jobs` list in `config.yml` you can configure your VM to automatically run cron tasks eg. every 30 minutes. + +```yaml +drupalvm_cron_jobs: + - name: "Drupal Cron" + minute: "*/30" + job: "{{ drush_path }} -r {{ drupal_core_path }} core-cron" +``` + +_Cron jobs are added to the vagrant user's crontab. Keys include name (required), minute, hour, day, weekday, month, job (required), and state._ + +For a list of available role variables, see the [`geerlingguy.drush` Ansible role's README](https://github.com/geerlingguy/ansible-role-drush#readme). diff --git a/docs/extras/elasticsearch.md b/docs/extras/elasticsearch.md index 8a7d98cb5..e57453e9d 100644 --- a/docs/extras/elasticsearch.md +++ b/docs/extras/elasticsearch.md @@ -1,11 +1,11 @@ [Elasticsearch](https://www.elastic.co/products/elasticsearch) is a search engine based on Lucene. It provides a distributed, multitenant-capable full-text search engine with an HTTP web interface and schema-free JSON documents. - To enable Elasticsearch in Drupal VM just make sure `elasticsearch` is in the list of `installed_extras` in your `config.yml`, and when you build Drupal VM, the latest version of Elasticsearch will be installed. +To enable Elasticsearch in Drupal VM just make sure `elasticsearch` is in the list of `installed_extras` in your `config.yml`, and when you build Drupal VM, the latest version of Elasticsearch will be installed. The URL to connect to the local elasticsearch server (assuming you're using the default `elasticsearch_http_port` of 9200) from Drupal is: http://localhost:9200 - + To access Elasticsearch from the host computer requires changing the IP address to listen on a specific interface, or 0.0.0.0 to listen on all interfaces. elasticsearch_network_host: 0.0.0.0 @@ -21,4 +21,4 @@ You can add configuration for Elasticsearch by setting the appropriate variables elasticsearch_network_host: localhost elasticsearch_http_port: 9200 -Consult the [geerlingguy.elasticsearch](https://github.com/geerlingguy/ansible-role-elasticsearch) role for additional variables available for configuration. +For a list of available role variables, see the [`geerlingguy.elasticsearch` Ansible role's README](https://github.com/geerlingguy/ansible-role-elasticsearch#readme). diff --git a/docs/extras/java.md b/docs/extras/java.md new file mode 100644 index 000000000..31b2fb26f --- /dev/null +++ b/docs/extras/java.md @@ -0,0 +1,4 @@ +Java will automatically be installed if you enabled any of the `installed_extras` that depend on it. +If you have any other use case for installing it, just make sure `java` is in the list of `installed_extras` in your `config.yml`. + +For a list of available role variables, see the [`geerlingguy.java` Ansible role's README](https://github.com/geerlingguy/ansible-role-java#readme). diff --git a/docs/extras/mailhog.md b/docs/extras/mailhog.md index 91e03d6a0..42f0c4f7f 100644 --- a/docs/extras/mailhog.md +++ b/docs/extras/mailhog.md @@ -1,11 +1,13 @@ -By default, Drupal VM redirects all PHP emails to [MailHog](https://github.com/mailhog/MailHog) (instead of sending them to the outside world). You can access the MailHog UI at `http://drupalvm.dev:8025/` (or whatever domain you have configured in `config.yml`). +By default, Drupal VM redirects all PHP emails to [MailHog](https://github.com/mailhog/MailHog) (instead of sending them to the outside world). You can access the MailHog UI at [http://drupalvm.dev:8025/](http://drupalvm.dev:8025) (or whatever domain you have configured in `config.yml`). ## Disable MailHog If you don't want to use MailHog, you can set the following override (back to PHP's default, as defined in the [`geerlingguy.php`](https://github.com/geerlingguy/ansible-role-php#role-variables) role) in your `config.yml` file: -``` +```yaml php_sendmail_path: "/usr/sbin/sendmail -t -i" ``` After doing this, you can also prevent MailHog's installation by removing `mailhog` from the `installed_extras` list. + +For a list of available role variables, see the [`geerlingguy.mailhog` Ansible role's README](https://github.com/geerlingguy/ansible-role-mailhog#readme). diff --git a/docs/extras/memcached.md b/docs/extras/memcached.md new file mode 100644 index 000000000..409c94170 --- /dev/null +++ b/docs/extras/memcached.md @@ -0,0 +1,17 @@ +[Memcached](https://memcached.org/) is an in-memory caching system, much like [Redis](redis.md). While [Varnish](varnish.md) is generally used to improve performance for anonymous users, `memcached` is used to improve the performance for logged in users. + +To enable Memcached in Drupal VM: + +1. Make sure `memcached` is in the list of `installed_extras` in your `config.yml`. +2. Install the [Memcache API](https://www.drupal.org/project/memcache) module. +3. Enable the module before you configure it in the next step. +4. Add the following to your `settings.php` + +```php +// Make memcache the default cache class. +$settings['cache']['default'] = 'cache.backend.memcache'; +``` + +There's a lot more configuration available and the best resource is generally the [Memcache API module's README](http://cgit.drupalcode.org/memcache/tree/README.txt?h=8.x-2.x). + +For a list of available role variables, see the [`geerlingguy.memcached` Ansible role's README](https://github.com/geerlingguy/ansible-role-memcached#readme). diff --git a/docs/extras/newrelic.md b/docs/extras/newrelic.md index 8d8ec1c1c..01a45b596 100644 --- a/docs/extras/newrelic.md +++ b/docs/extras/newrelic.md @@ -1,4 +1,4 @@ -The New Relic PHP agent monitors your application to help you identify and solve performance issues. +The [New Relic PHP agent](https://docs.newrelic.com/docs/agents/php-agent/getting-started/new-relic-php) monitors your application to help you identify and solve performance issues. ## Getting Started - Installing Prerequisites @@ -19,3 +19,5 @@ newrelic_license_key: yourkey ``` See [New Relic for PHP](https://docs.newrelic.com/docs/agents/php-agent/getting-started/new-relic-php) for help getting started. + +For a list of available role variables, see the [`franklinkim.newrelic` Ansible role's README](https://github.com/weareinteractive/ansible-newrelic#readme). diff --git a/docs/extras/nodejs.md b/docs/extras/nodejs.md index 0f5ece5a9..e6499eeb1 100644 --- a/docs/extras/nodejs.md +++ b/docs/extras/nodejs.md @@ -18,3 +18,5 @@ To install packages globally, you can add them to the list of `nodejs_npm_global nodejs_npm_global_packages: - name: phantomjs ``` + +For a list of available role variables, see the [`geerlingguy.nodejs` Ansible role's README](https://github.com/geerlingguy/ansible-role-nodejs#readme). diff --git a/docs/extras/pimpmylog.md b/docs/extras/pimpmylog.md index 46b0b69bc..93a17f08b 100644 --- a/docs/extras/pimpmylog.md +++ b/docs/extras/pimpmylog.md @@ -1,8 +1,8 @@ -[Pimp my Log](http://pimpmylog.com/) is a PHP-based web GUI for viewing log files on a given server. By default, it is installed on Drupal VM, and you can access it at the URL `http://pimpmylog.drupalvm.dev/` (as long as you have a hosts entry for that URL pointing at Drupal VM's IP address!). +[Pimp my Log](http://pimpmylog.com/) is a PHP-based web GUI for viewing log files on a given server. By default, it is installed on Drupal VM, and you can access it at the URL [http://pimpmylog.drupalvm.dev/](http://pimpmylog.drupalvm.dev) (as long as you have a hosts entry for that URL pointing at Drupal VM's IP address!). By default, it will find the default Apache 2 `access.log` and `error.log` files, but it will not find other logs, like MySQL or extra Apache virtualhost logs. -When configuring Pimp my Log (on the first visit to the `pimpmylog.drupalvm.dev` URL), you can add extra paths in the UI, or you can add them after the fact by manually editing the configuration file, which by default is stored at `/usr/share/php/pimpmylog/config.user.php`. You can also delete that file and re-configure Pimp my Log via the web UI. +When configuring Pimp my Log (on the first visit to [pimpmylog.drupalvm.dev](http://pimpmylog.drupalvm.dev)), you can add extra paths in the UI, or you can add them after the fact by manually editing the configuration file, which by default is stored at `/usr/share/php/pimpmylog/config.user.php`. You can also delete that file and re-configure Pimp my Log via the web UI. Some log files you may be interested in monitoring: @@ -16,3 +16,5 @@ Some log files you may be interested in monitoring: For MySQL logs, you might want to read through the PML docs on [MySQL](http://support.pimpmylog.com/kb/softwares/mysql). It might be necessary to grant read permissions to the other group (e.g. `chmod o+r /var/log/mysql.err`) on some log files in order for Pimp My Log to be able to parse them. + +For a list of available role variables, see the [`geerlingguy.pimpmylog` Ansible role's README](https://github.com/geerlingguy/ansible-role-pimpmylog#readme). diff --git a/docs/extras/profile-code.md b/docs/extras/profile-code.md deleted file mode 100644 index 321ce95b3..000000000 --- a/docs/extras/profile-code.md +++ /dev/null @@ -1,66 +0,0 @@ -You can profile your code using one of the supported profiling tools included in Drupal VM. - -As a prerequisite, you need to make sure the profiler you'd like to use is listed (and not commented out) in `installed_extras` inside `config.yml` (So the appropriate software is installed on Drupal VM). - -**Note**: You should only enable one code profiler at a time—e.g. when using Blackfire, disable XHProf and XDebug. - -## Blackfire - -[Blackfire.io](https://blackfire.io/) is a service that allows code profiling to be stored and analyzed via an online profile on the Blackfire.io website. - -It doesn't require any additional Drupal modules to use, but once you've made sure `blackfire` is in the list of `installed_extras` in `config.yml` (and Drupal VM has been provisioned), you need to log into Drupal VM and [run the setup steps outlined on the Blackfire Ansible role's README](https://github.com/geerlingguy/ansible-role-blackfire#requirements). - -Once you've configured your environment for your own Blackfire account, you can profile a request with Blackfire by running something like the following example (within Drupal VM, after logging in with `vagrant ssh`): - -``` -$ blackfire curl http://drupalvm.dev/ -Profiling: [########################################] 10/10 -Blackfire cURL completed -Graph URL https://blackfire.io/profiles/[UUID]/graph - -Wall Time 151ms -CPU Time 130ms -I/O Time 20.9ms -Memory 1.5MB -Network n/a n/a - -SQL n/a - -``` - -## XHProf - -[XHProf](http://xhprof.io/) allows easy code profiling and can be used in many different ways. Ensure `xhprof` is in the list of `installed_extras` inside `config.yml`. - -_Note: XHProf does currently not work with PHP 7.1._ - -### XHProf module - -The easiest way to use XHProf to profile your PHP code on a Drupal site is to install the [XHProf](https://www.drupal.org/project/xhprof) module, then in XHProf's configuration (at `/admin/config/development/xhprof`), check the 'Enable profiling of page views and drush requests' checkbox. - -The XHProf module doesn't include built-in support for callgraphs, but there's an issue to [add callgraph support](https://www.drupal.org/node/1470740). - -You can view callgraphs (and a listing of all stored runs) using Drupal VM's own XHProf installation by visiting `http://xhprof.drupalvm.dev/` and clicking on the relevant run, then clicking the "[View Full Callgraph]" link. - -### Devel module (deprecated) - -The Devel module also *used* to provide XHProf configuration, and setting the options below would allow Devel's XHProf integration to work correctly with Drupal VM's XHProf installation: - - - **xhprof directory**: `/usr/share/php` - - **XHProf URL**: `http://xhprof.drupalvm.dev` (assuming this domain is configured in `apache_vhosts` inside `config.yml`) - -## Tideways - -The XHProf PHP extension has barely been maintained since Facebook abandoned the project around 2015, so it's difficult to get it running under newer versions of PHP. - -The Tideways PHP Extension is a well-maintained fork of the XHProf code and works with either the [XHProf](https://www.drupal.org/project/xhprof) or [Tideways](https://www.drupal.org/project/tideways) module to profile page views. - -### Profiling with the XHProf Module - -To enable profiling of Drupal pages using the Tideways PHP Extension, follow the directions listed earlier for configuring the XHProf module, but choose the 'Tideways' extension under in the 'Profiling settings' section. - -### Profiling with the Tideways module - -Instructions for profiling with the Tideways module through the [tideways.io](https://tideways.io) service will be added after the following issue is resolved: [Can't install latest dev release on 8.x](https://www.drupal.org/node/2843481). - -## XDebug - -[XDebug](https://xdebug.org/) is a debugger and profiler for PHP. While most people use it only for debugging purposes, you can also use it for profiling. It's not as commonly used for profiling as either Blackfire or XHProf, but it works! diff --git a/docs/extras/redis.md b/docs/extras/redis.md new file mode 100644 index 000000000..2550860fa --- /dev/null +++ b/docs/extras/redis.md @@ -0,0 +1,17 @@ +[Redis](https://redis.io/) is an in-memory caching system, much like [Memcached](memcached.md). While [Varnish](varnish.md) is generally used to improve performance for anonymous users, `redis` is used to improve the performance for logged in users. + +To enable Redis in Drupal VM: + +1. Make sure `redis` is in the list of `installed_extras` in your `config.yml`. +2. Install the [Redis](https://www.drupal.org/project/redis) module. +3. Enable the module before you configure it in the next step. +4. Add the following to your `settings.php` + +```php +// Make redis the default cache class. +$settings['cache']['default'] = 'cache.backend.redis' +``` + +There's a lot more configuration available and the best resource is generally the [Redis module's README](http://cgit.drupalcode.org/redis/tree/README.md). + +For a list of available role variables, see the [`geerlingguy.redis` Ansible role's README](https://github.com/geerlingguy/ansible-role-redis#readme). diff --git a/docs/extras/ruby.md b/docs/extras/ruby.md new file mode 100644 index 000000000..c4522b185 --- /dev/null +++ b/docs/extras/ruby.md @@ -0,0 +1,15 @@ +Ruby is used for many different purposes, but with Drupal, it is most often used as part of a toolset for Front End development or certain CI tasks. + +Drupal VM includes built-in support for Ruby—all you need to do is make sure `ruby` is listed in the list of `installed_extras` inside `config.yml` before your provision Drupal VM. + +## Installing gems + +To install ruby gems, you can add them to the list of `ruby_install_gems` in `config.yml`. + +```yaml +ruby_install_gems: + - sass + - compass +``` + +For a list of available role variables, see the [`geerlingguy.ruby` Ansible role's README](https://github.com/geerlingguy/ansible-role-ruby#readme). diff --git a/docs/extras/behat.md b/docs/extras/selenium.md similarity index 97% rename from docs/extras/behat.md rename to docs/extras/selenium.md index 7d5e6b767..4b19228b5 100644 --- a/docs/extras/behat.md +++ b/docs/extras/selenium.md @@ -101,3 +101,5 @@ There are many different ways you can run Behat tests via PhantomJS and other dr - [Trying to achieve a Visual Regression Testing Strategy](https://github.com/geerlingguy/drupal-vm/issues/421) Also, see Acquia's [BLT](https://github.com/acquia/blt) project for a good example of Behat test integration with Drupal VM. + +For a list of available role variables, see the [`arknoll.selenium` Ansible role's README](https://github.com/arknoll/ansible-role-selenium#readme). diff --git a/docs/extras/solr.md b/docs/extras/solr.md index 75dbce641..ebc7a1e8d 100644 --- a/docs/extras/solr.md +++ b/docs/extras/solr.md @@ -25,4 +25,6 @@ post_provision_scripts: ## Extra Solr configuration -You can add extra configuration for Solr, like the minimum and maximum memory allocation for the JVM (`solr_xms` and `solr_xmx`), and even the `solr_version`, by setting the appropriate variables inside `config.yml` before you build Drupal VM. \ No newline at end of file +You can add extra configuration for Solr, like the minimum and maximum memory allocation for the JVM (`solr_xms` and `solr_xmx`), and even the `solr_version`, by setting the appropriate variables inside `config.yml` before you build Drupal VM. + +For a list of available role variables, see the [`geerlingguy.solr` Ansible role's README](https://github.com/geerlingguy/ansible-role-solr#readme). diff --git a/docs/extras/ssl.md b/docs/extras/ssl.md deleted file mode 100644 index 8feb0039f..000000000 --- a/docs/extras/ssl.md +++ /dev/null @@ -1,82 +0,0 @@ -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 - -Place the files in your project directory and edit your `config.yml`. - -_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`_ - -### Apache - -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 }}" -``` - -For a list of all configuration options see the [`geerlingguy.apache` Ansible role's README](https://github.com/geerlingguy/ansible-role-apache#readme). - -### Nginx - -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; -``` - -For a list of all configuration options see the [`geerlingguy.nginx` Ansible role's README](https://github.com/geerlingguy/ansible-role-nginx#readme). - -## 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. - -#### Apache - -```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 }}" -``` - -#### Nginx - -```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; -``` - -## Tips & Tricks - -To automatically add a SSL virtual host for every Apache host defined in `apache_vhosts` you can add the following to your `config.yml`: - -```yaml -apache_vhost_ssl_parameters: - certificate_file: "/etc/ssl/certs/ssl-cert-snakeoil.pem" - certificate_key_file: "/etc/ssl/private/ssl-cert-snakeoil.key" - -# Generate a SSL virtual host for every regular vhost. -apache_vhosts_ssl: "{% set vhosts = [] %}{% for vhost in apache_vhosts %}{% if vhosts.append(vhost|combine(apache_vhost_ssl_parameters)) %}{% endif %}{% endfor %}{{ vhosts }}" -``` diff --git a/docs/extras/tideways.md b/docs/extras/tideways.md new file mode 100644 index 000000000..8953c0fa4 --- /dev/null +++ b/docs/extras/tideways.md @@ -0,0 +1,15 @@ +The Tideways PHP Extension is a well-maintained fork of the XHProf code and works with either the [XHProf](https://www.drupal.org/project/xhprof) or [Tideways](https://www.drupal.org/project/tideways) module to profile page views. + +**Note**: You should only enable one code profiler at a time—e.g. when using [Blackfire](blackfire.md), disable [XHProf](xhprof.md), [Tideways](tideways.md) and [XDebug](xdebug.md). + +### Profiling with the XHProf Module + +To enable profiling of Drupal pages using the Tideways PHP Extension, follow the directions for [configuring the XHProf and the XHProf module](xhprof.md#xhprof-module), but choose the _Tideways_ extension under in the _Profiling settings_ section. + +As with the XHProf extension, you can view callgraphs (and a listing of all stored runs) using Drupal VM's own XHProf UI installation by visiting [http://xhprof.drupalvm.dev/](http://xhprof.drupalvm.dev) and clicking on the relevant run, then clicking the _[View Full Callgraph]_ link. + +### Profiling with the Tideways module + +Instructions for profiling with the Tideways module through the [tideways.io](https://tideways.io) service will be added after the following issue is resolved: [Can't install latest dev release on 8.x](https://www.drupal.org/node/2843481). + +For a list of available role variables, see the [`geerlingguy.tideways` Ansible role's README](https://github.com/geerlingguy/ansible-role-tideways#readme). diff --git a/docs/extras/upload-progress.md b/docs/extras/upload-progress.md new file mode 100644 index 000000000..da364b98d --- /dev/null +++ b/docs/extras/upload-progress.md @@ -0,0 +1,3 @@ +To enable the Upload progress PHP extension make sure `upload-progress` is listed in the list of `installed_extras` inside `config.yml` before your provision Drupal VM. + +For a list of available role variables, see the [`thom8.php-upload-progress` Ansible role's README](https://github.com/thom8/ansible-role-php-upload-progress#readme). diff --git a/docs/extras/varnish.md b/docs/extras/varnish.md index 38b0cf677..b39f6e817 100644 --- a/docs/extras/varnish.md +++ b/docs/extras/varnish.md @@ -29,4 +29,6 @@ $settings['reverse_proxy'] = TRUE; $settings['reverse_proxy_addresses'] = array('127.0.0.1'); ``` -If you don't set these values, Drupal will think all requests are coming from `127.0.0.1`. There are other settings you can change to make Drupal not store copies of cached pages in the Database (since Varnish is caching everything, this is redundant), but those other settings are not covered here. \ No newline at end of file +If you don't set these values, Drupal will think all requests are coming from `127.0.0.1`. There are other settings you can change to make Drupal not store copies of cached pages in the Database (since Varnish is caching everything, this is redundant), but those other settings are not covered here. + +For a list of available role variables, see the [`geerlingguy.varnish` Ansible role's README](https://github.com/geerlingguy/ansible-role-varnish#readme). diff --git a/docs/extras/xdebug.md b/docs/extras/xdebug.md index 51a419010..b0e85d344 100644 --- a/docs/extras/xdebug.md +++ b/docs/extras/xdebug.md @@ -1,4 +1,4 @@ -XDebug is a useful tool for debugging PHP applications, but it uses extra memory and CPU for every request, so is disabled by default. +[XDebug](https://xdebug.org/) is a useful tool for debugging PHP applications, but it uses extra memory and CPU for every request, so is disabled by default. To enable XDebug, do the following in `config.yml`: @@ -7,7 +7,7 @@ To enable XDebug, do the following in `config.yml`: If you don't need to use XDebug, you can comment it out or remove it from `installed_extras` before you `vagrant up` Drupal VM. -## PHPStorm and XDebug with Drupal VM +### PHPStorm and XDebug with Drupal VM To use XDebug with PHPStorm, change the `php_xdebug_idekey` variable as shown below in `config.yml`, and then run `vagrant provision` to reconfigure the VM: @@ -15,7 +15,7 @@ To use XDebug with PHPStorm, change the `php_xdebug_idekey` variable as shown be php_xdebug_idekey: PHPSTORM ``` -## Sublime Text and XDebug with Drupal VM +### Sublime Text and XDebug with Drupal VM To use XDebug with Sublime Text, change the `php_xdebug_idekey` variable as shown below in `config.yml`, and then run `vagrant provision` to reconfigure the VM: @@ -23,10 +23,18 @@ To use XDebug with Sublime Text, change the `php_xdebug_idekey` variable as show php_xdebug_idekey: sublime.xdebug ``` -## NetBeans and XDebug with Drupal VM +### NetBeans and XDebug with Drupal VM To use XDebug with NetBeans, change the `php_xdebug_idekey` variable as shown below in `config.yml`, and then run `vagrant provision` to reconfigure the VM. ```yaml php_xdebug_idekey: netbeans-xdebug ``` + +## Profiling code with XDebug + +While most people use XDebug only for debugging purposes, you can also use it for profiling. It's not as commonly used for profiling as either Blackfire or XHProf, but it works! + +**Note**: You should only enable one code profiler at a time—e.g. when using [Blackfire](blackfire.md), disable [XHProf](xhprof.md), [Tideways](tideways.md) and [XDebug](xdebug.md). + +For a list of available role variables, see the [`geerlingguy.php-xdebug` Ansible role's README](https://github.com/geerlingguy/ansible-role-php-xdebug#readme). diff --git a/docs/extras/xhprof.md b/docs/extras/xhprof.md new file mode 100644 index 000000000..af0dc6b00 --- /dev/null +++ b/docs/extras/xhprof.md @@ -0,0 +1,20 @@ +[XHProf](http://xhprof.io/) allows easy code profiling and can be used in many different ways. Ensure `xhprof` is in the list of `installed_extras` inside `config.yml`. + +_Note: XHProf does currently not work with PHP 7.1. The PHP extension has barely been maintained since Facebook abandoned the project around 2015, so it's difficult to get it running under newer versions of PHP. If you require support for PHP 7.1 you should use [Tideways](tideways.md) instead._ + +### XHProf module + +The easiest way to use XHProf to profile your PHP code on a Drupal site is to install the [XHProf](https://www.drupal.org/project/xhprof) module, then in XHProf's configuration (at `/admin/config/development/xhprof`), check the 'Enable profiling of page views and drush requests' checkbox. + +The XHProf module doesn't include built-in support for callgraphs, but there's an issue to [add callgraph support](https://www.drupal.org/node/1470740). + +You can view callgraphs (and a listing of all stored runs) using Drupal VM's own XHProf installation by visiting [http://xhprof.drupalvm.dev/](http://xhprof.drupalvm.dev) and clicking on the relevant run, then clicking the _[View Full Callgraph]_ link. + +### Devel module (deprecated) + +The Devel module also *used* to provide XHProf configuration, and setting the options below would allow Devel's XHProf integration to work correctly with Drupal VM's XHProf installation: + + - **xhprof directory**: `/usr/share/php` + - **XHProf URL**: `http://xhprof.drupalvm.dev` (assuming this domain is configured in `apache_vhosts` inside `config.yml`) + +**Note**: You should only enable one code profiler at a time—e.g. when using [Blackfire](blackfire.md), disable [XHProf](xhprof.md), [Tideways](tideways.md) and [XDebug](xdebug.md). diff --git a/docs/getting-started/configure-drupalvm.md b/docs/getting-started/configure-drupalvm.md new file mode 100644 index 000000000..a4d4c6190 --- /dev/null +++ b/docs/getting-started/configure-drupalvm.md @@ -0,0 +1,48 @@ +If you only need a simple Drupal VM environment up and running there are no required configurations. The [configurations used by default are listed in `default.config.yml`](https://github.com/geerlingguy/drupal-vm/blob/master/default.config.yml) and you can override them with a number of optional configuration files. + +_Note: The merge of variables in these files is shallow, if you want to override a single item in a list, you will need to re-define all items in that list._ + +Configurations files are read in the following order: + +#### 1. default.config.yml + +Drupal VM's default configurations which you should not edit directly. + +#### 2. config.yml + +The main configuration file of a project. Commonly this is a copy of `default.config.yml` with the values tweaked to your own project. For an easier upgrade path you would only set the values you are actually overriding. + +```yaml +vagrant_box: geerlingguy/centos7 +vagrant_hostname: my-custom-site.dev +vagrant_machine_name: my_custom_site + +php_version: "5.6" +``` + +#### 3. local.config.yml + +Local development overrides. Commonly this file is ignored from VCS so that each team member can make local customizations. + +```yaml +# Increase the memory available to your Drupal site. +vagrant_memory: 1536 +php_memory_limit: "512M" + +# Override the synced folders to use rsync instead of NFS. +vagrant_synced_folders: + - local_path: . + destination: /var/www/drupalvm + type: rsync + create: true +``` + +### 4. vagrant.config.yml + +Environment specific overrides. When you run Drupal VM through _Vagrant_, the environment will be set to `vagrant` and this file is loaded when available. If you're doing something more advanced, such as running Drupal VM on a [production environment](../other/production.md), you can use a different environment configuration file, eg `prod.config.yml`. + +_Note: In addition to the variables listed in `default.config.yml`, you can also override the variables set by any of the ansible roles. In the "Installed extras" section of this documentation, each role has a link to the available variables._ + +## Additional resources + +- Jeff Geerling's DrupalDC talk "[Drupal VM Tips and Tricks for Drupal 8 development](https://www.youtube.com/watch?v=_wV6MDsT42Y)" diff --git a/docs/other/linux.md b/docs/getting-started/installation-linux.md similarity index 93% rename from docs/other/linux.md rename to docs/getting-started/installation-linux.md index 9ab7fd61d..ec9ff0a5f 100644 --- a/docs/other/linux.md +++ b/docs/getting-started/installation-linux.md @@ -1,9 +1,11 @@ +Please read through the [Quick Start Guiden the README](https://github.com/geerlingguy/drupal-vm#quick-start-guide) to get started. + +For a quick introduction to setting up Drupal VM, the [macOS video tutorial](installation-macos.md) applies somwhat to Linux as well. + There are a few caveats when using Drupal VM on Linux, and this page will try to identify the main gotchas or optimization tips for those wishing to use Drupal VM on a Linux host. ## Platform-specific Install Instructions -### All Linux flavors - Always make sure your workstation is up to date (e.g. `apt-get update && apt-get upgrade` on Debian-like systems, or `dnf upgrade` or `yum upgrade` on Fedora/RedHat-like systems). There are sometimes bugs in the base OS packages (e.g. [this NFS-related bug](https://bugs.launchpad.net/ubuntu/+source/linux/+bug/1508510)) that can be resolved by a simple upgrade. ### Ubuntu @@ -37,7 +39,7 @@ Arch Linux uses Python 3 as the default while Ansible requires Python 2. To get ansible_python_interpreter: "/usr/bin/env python2" ``` -## Synced Folders +## Troubleshooting Vagrant Synced Folders Most issues have to do synced folders. These are the most common ones: diff --git a/docs/getting-started/installation-macos.md b/docs/getting-started/installation-macos.md new file mode 100644 index 000000000..e08561e32 --- /dev/null +++ b/docs/getting-started/installation-macos.md @@ -0,0 +1,5 @@ +Please read through the [Quick Start Guiden the README](https://github.com/geerlingguy/drupal-vm#quick-start-guide) to get started. + + + +_In this quick overview, Jeff Geerling will show you where you can learn more about Drupal VM, then show you a simple Drupal VM setup._ diff --git a/docs/other/windows.md b/docs/getting-started/installation-windows.md similarity index 74% rename from docs/other/windows.md rename to docs/getting-started/installation-windows.md index c0e72acc0..1cca0f7f1 100644 --- a/docs/other/windows.md +++ b/docs/getting-started/installation-windows.md @@ -1,3 +1,9 @@ +Please read through the [Quick Start Guiden the README](https://github.com/geerlingguy/drupal-vm#quick-start-guide) to get started. + + + +_In this video, Jeff Geerling walk you through getting a Drupal 8 website built on your Windows 10 laptop using Drupal VM 3._ + There are a few caveats when using Drupal VM on Windows, and this page will try to identify the main gotchas or optimization tips for those wishing to use Drupal VM on a Windows host. ## Windows Subsystem for Linux / Ubuntu bash @@ -22,17 +28,11 @@ If you're not on Windows 10, or if you don't want to install the WSL, you can us - [Cmder](http://cmder.net/) includes built-in git and SSH support, so you can do most things that you need without any additional plugins. - [Cygwin](https://www.cygwin.com/) allows you to install a large variety of linux packages inside its bash environment, though it can be a little more tricky to manage and is less integrated into the Windows environment. -## Synced Folders +## Troubleshooting Vagrant Synced Folders Most issues have to do synced folders. These are the most common ones: -### Performance - -By default, if you use the 'NFS' synced folder type, Vagrant will ignore this directive and use the native (usually slow) VirtualBox shared folder system instead. You can get higher performance by doing one of the following (all of these steps require a full VM reload (`vagrant reload`) to take effect): - - 1. **Install the `vagrant-winnfsd` plugin**. See the 'NFS' section later for more details and caveats. - 2. **Use `smb` for the synced folder's type.** - 2. **Use `rsync` for the synced folder's type.** This requires that you have `rsync` available on your Windows workstation, which you can get if you install a substitute CLI like [Cygwin](https://www.cygwin.com/) or [Cmder](http://cmder.net/). +_Read the following to [improve the performance of synced folders by using NFS, samba or rsync](../other/performance.md#improving-performance-on-windows)._ ### Symbolic Links @@ -53,28 +53,6 @@ You should probably disable Git's `fileMode` option inside the VM and on your ho git config core.fileMode false -### NFS - -You can use the [vagrant-winnfsd](https://github.com/GM-Alex/vagrant-winnfsd) plugin to get NFS support on windows. Be aware that there are multiple issues logged against both the plugin and the winnfsd project, so no guarantees. - -#### Using WinNFSD without `vagrant-winnfsd` - -Another option for the more adventurous is to manually install and configure WinNFSD, and manually mount the shares within your VM. This requires a bit more work, but could be more stable on Windows; see this blog post for more details: [Windows + Vagrant + WinNFSD without file update problems](https://hollyit.net/blog/windowsvagrantwinnfsd-without-file-update-problems). - -GuyPaddock's [fork of `vagrant-winnfsd`](https://github.com/GuyPaddock/vagrant-winnfsd) adds logging and debug messages. You can replace the vagrant-winnfsd gem inside `.vagrant.d\gems\gems` to use it instead. For further caveats, please read through [vagrant-winnfsd issue #12](https://github.com/winnfsd/vagrant-winnfsd/issues/12#issuecomment-78195957), and make the following changes to `config.yml`: - - vagrant_synced_folder_default_type: "" - -Add `mount_options` to your synced folder to avoid an error: - - type: nfs - mount_options: ["rw","vers=3","udp","nolock"] - -In a custom `Vagrantfile.local`, add user access to Vagrant: - - config.winnfsd.uid=900 - config.winnfsd.gid=900 - ### "Authentication failure" on vagrant up Some Windows users have reported running into an issue where an authentication failure is reported once the VM is booted (e.g. `drupalvm: Warning: Authentication failure. Retrying...` — see [#170](https://github.com/geerlingguy/drupal-vm/issues/170)). To fix this, do the following: diff --git a/docs/extras/syncing-folders.md b/docs/getting-started/syncing-folders.md similarity index 79% rename from docs/extras/syncing-folders.md rename to docs/getting-started/syncing-folders.md index 824fb4410..3f121fe7b 100644 --- a/docs/extras/syncing-folders.md +++ b/docs/getting-started/syncing-folders.md @@ -1,6 +1,6 @@ You can share folders between your host computer and the VM in a variety of ways; the most commonly-used method is an NFS share. If you use Windows and encounter any problems with NFS, try switching to `smb`. The `default.config.yml` file contains an example `nfs` share that would sync the entire drupal-vm directory (configured as the relative path `.`) on your host into the `/var/www/drupalvm` folder on Virtual Machine. -If you want to use a different synced folder method (e.g. `smb`), you can change `type` to: +If you want to use a different synced folder method (e.g. `smb`), you can change `type`: ```yaml vagrant_synced_folders: @@ -36,38 +36,10 @@ options_override: ] ``` -## Synced Folder Performance - -Using different synced folder mechanisms can have a dramatic impact on your Drupal site's performance. Please read through the following blog posts for a thorough overview of synced folder performance: - - - [Comparing filesystem performance in Virtual Machines](http://mitchellh.com/comparing-filesystem-performance-in-virtual-machines) - - [NFS, rsync, and shared folder performance in Vagrant VMs](http://www.jeffgeerling.com/blogs/jeff-geerling/nfs-rsync-and-shared-folder) - -Generally speaking: - - - NFS offers a decent tradeoff between performance and ease of use - - SMB offers a similar tradeoff, but is a bit slower than NFS - - Rsync offers the best performance inside the VM, but sync is currently one-way-only (from host to VM), which can make certain development workflows burdensome - - Native shared folders offer abysmal performance; only use this mechanism as a last resort! - -If you are using rsync, it is advised to exclude certain directories so that they aren't synced. These include version control directories, database exports and Drupal's files directory. - -```yaml -vagrant_synced_folders: - - local_path: . - destination: /var/www/drupalvm - type: rsync - create: true - excluded_paths: - - drupal/private - - drupal/public/.git - - drupal/public/sites/default/files - - drupal/tmp -``` +## Synced Folder Troubleshooting -This example assumes that you have Drupal in a directory called `drupal/public`. +_Read the following [overview on the performance of the different synced folder mechanisms](../other/performance.md#synced-folder-performance)._ -## Synced Folder Troubleshooting There are a number of issues people encounter with synced folders from time to time. The most frequent issues are listed below with possible solutions: diff --git a/docs/index.md b/docs/index.md index a10ae6c37..0206d5da2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,7 +2,11 @@ [Drupal VM](https://www.drupalvm.com/) is A VM for local Drupal development, built with Vagrant + Ansible. -Welcome to Drupal VM's documentation site! Please read through the [Quick Start Guide](https://github.com/geerlingguy/drupal-vm#quick-start-guide) to get started, and then browse the rest of this project's documentation in the sidebar. +Welcome to Drupal VM's documentation site! Get started by reading the installation instructions for you platform: + +- [macOS](getting-started/installation-macos.md) +- [Windows](getting-started/installation-windows.md) +- [Linux](getting-started/installation-linux.md) ## Contributing to Drupal VM diff --git a/docs/other/performance.md b/docs/other/performance.md new file mode 100644 index 000000000..ca6afd58d --- /dev/null +++ b/docs/other/performance.md @@ -0,0 +1,73 @@ +## 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/)._ + +## Synced Folder Performance + +Using different synced folder mechanisms can have a dramatic impact on your Drupal site's performance. Please read through the following blog posts for a thorough overview of synced folder performance: + + - [Comparing filesystem performance in Virtual Machines](http://mitchellh.com/comparing-filesystem-performance-in-virtual-machines) + - [NFS, rsync, and shared folder performance in Vagrant VMs](http://www.jeffgeerling.com/blogs/jeff-geerling/nfs-rsync-and-shared-folder) + +Generally speaking: + + - NFS offers a decent tradeoff between performance and ease of use + - SMB offers a similar tradeoff, but is a bit slower than NFS + - Rsync offers the best performance inside the VM, but sync is currently one-way-only (from host to VM), which can make certain development workflows burdensome + - Native shared folders offer abysmal performance; only use this mechanism as a last resort! + +If you are using rsync, it is advised to exclude certain directories so that they aren't synced. These include version control directories, database exports and Drupal's files directory. + +```yaml +vagrant_synced_folders: + - local_path: . + destination: /var/www/drupalvm + type: rsync + create: true + excluded_paths: + - drupal/private + - drupal/public/.git + - drupal/public/sites/default/files + - drupal/tmp +``` + +_This example assumes that you have Drupal in a directory called `drupal/public`._ + + +## Improving performance on Windows + +By default, if you use the _NFS_ synced folder type, Vagrant will ignore this directive and use the native (usually slow) VirtualBox shared folder system instead. You can get higher performance by doing one of the following (all of these steps require a full VM reload (`vagrant reload`) to take effect): + + 1. **Install the `vagrant-winnfsd` plugin**. See the 'NFS' section later for more details and caveats. + 2. **Use `smb` for the synced folder's type.** + 2. **Use `rsync` for the synced folder's type.** This requires that you have `rsync` available on your Windows workstation, which you can get if you install a substitute CLI like [Cygwin](https://www.cygwin.com/) or [Cmder](http://cmder.net/). + +### NFS + +You can use the [vagrant-winnfsd](https://github.com/GM-Alex/vagrant-winnfsd) plugin to get NFS support on windows. Be aware that there are multiple issues logged against both the plugin and the winnfsd project, so no guarantees. + +#### Using WinNFSD without `vagrant-winnfsd` + +Another option for the more adventurous is to manually install and configure WinNFSD, and manually mount the shares within your VM. This requires a bit more work, but could be more stable on Windows; see this blog post for more details: [Windows + Vagrant + WinNFSD without file update problems](https://hollyit.net/blog/windowsvagrantwinnfsd-without-file-update-problems). + +GuyPaddock's [fork of `vagrant-winnfsd`](https://github.com/GuyPaddock/vagrant-winnfsd) adds logging and debug messages. You can replace the vagrant-winnfsd gem inside `.vagrant.d\gems\gems` to use it instead. For further caveats, please read through [vagrant-winnfsd issue #12](https://github.com/winnfsd/vagrant-winnfsd/issues/12#issuecomment-78195957), and make the following changes to `config.yml`: + + vagrant_synced_folder_default_type: "" + +Add `mount_options` to your synced folder to avoid an error: + + type: nfs + mount_options: ["rw","vers=3","udp","nolock"] + +In a custom `Vagrantfile.local`, add user access to Vagrant: + + config.winnfsd.uid=900 + config.winnfsd.gid=900 diff --git a/docs/other/production.md b/docs/other/production.md index 94aee40d6..c9eea4a25 100644 --- a/docs/other/production.md +++ b/docs/other/production.md @@ -74,14 +74,7 @@ You now have Drupal VM configured for production by default. This is the recomme ### Customize `vagrant.config.yml` for local development -To re-use the same setup for local development, copy `default.config.yml` to `vagrant.config.yml` and configure it so that you override the security hardening configurations that were added in `config.yml`. - -When you run `vagrant up` or `vagrant provision` the order of the configuration files read will be: - -- `default.config.yml` -- `config.yml` -- `local.config.yml` -- `vagrant.config.yml` +To re-use the same setup for local development, copy `default.config.yml` to `vagrant.config.yml` and configure it so that you override the security hardening configurations that were added in `config.yml`. Read about how configuration files are read under [Configuring Drupal VM](../getting-started/configure-drupalvm.md) ### Customize `inventory` for production @@ -112,7 +105,7 @@ Run the following command within Drupal VM's root directory (the folder containi ansible-playbook -i examples/prod/inventory provisioning/playbook.yml --sudo --ask-sudo-pass -_Note: If you have installed [Drupal VM as a Composer dependency](drupalvm-composer-dependency.md) you also need to specify the path of the config directory where you have your `config.yml` located._ +_Note: If you have installed [Drupal VM as a Composer dependency](../deployment/composer-dependency.md) you also need to specify the path of the config directory where you have your `config.yml` located._ ansible-playbook -i config/prod/inventory vendor/geerlingguy/drupal-vm/provisioning/playbook.yml -e "config_dir=$(pwd)/config" --sudo --ask-sudo-pass diff --git a/docs/other/webservers.md b/docs/other/webservers.md deleted file mode 100644 index b78744e28..000000000 --- a/docs/other/webservers.md +++ /dev/null @@ -1,19 +0,0 @@ -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. - -All you need to do is change the `drupalvm_webserver` variable inside your customized `config.yml`, choosing either `apache` or `nginx`. - -Because the webservers are configured somewhat differently, there are a few things you should configure depending on which webserver you use. - -## Using Apache - -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. - -## Using 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`. diff --git a/mkdocs.yml b/mkdocs.yml index 7bc403bb7..2169c2271 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,39 +13,60 @@ markdown_extensions: 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: - - 'Syncing Folders': 'extras/syncing-folders.md' - - 'Connect to the MySQL Database': 'extras/mysql.md' - - 'Use Apache Solr for Search': 'extras/solr.md' - - 'Use Drush with Drupal VM': 'extras/drush.md' - - 'Use Drupal Console with Drupal VM': 'extras/drupal-console.md' - - 'Use Varnish with Drupal VM': 'extras/varnish.md' - - 'Use MariaDB instead of MySQL': 'extras/mariadb.md' - - 'Use PostgreSQL instead of MySQL': 'extras/postgresql.md' - - 'Use Node.js and NPM': 'extras/nodejs.md' - - 'Use SSL vhosts with Apache/Nginx': 'extras/ssl.md' - - 'View Logs with Pimp my Log': 'extras/pimpmylog.md' - - 'Profile Code - XHProf, Blackfire, Xdebug': 'extras/profile-code.md' - - 'Debug Code with XDebug': 'extras/xdebug.md' - - 'Catch Emails with MailHog': 'extras/mailhog.md' - - 'Test with Behat and Selenium': 'extras/behat.md' - - 'Add Pre- and Post-Provision Scripts': 'extras/scripts.md' + - Getting Started: + - Installation: + - 'macOS': 'getting-started/installation-macos.md' + - 'Windows': 'getting-started/installation-windows.md' + - 'Linux': 'getting-started/installation-linux.md' + - 'Configuring Drupal VM': 'getting-started/configure-drupalvm.md' + - 'Syncing Folders': 'getting-started/syncing-folders.md' + - Building your codebase: + - 'Using a local Drupal codebase': 'deployment/local-codebase.md' + - 'Using a composer package': 'deployment/composer-package.md' + - 'Using composer.json': 'deployment/composer.md' + - 'Using a Drush Make file': 'deployment/drush-make.md' + - 'Drupal VM as a Composer Dependency': 'deployment/composer-dependency.md' + - Basic configurations: + - 'Using different base OSes': 'configurations/base-os.md' + - 'Using a different PHP version': 'configurations/php.md' + - Webservers: + - 'Apache': 'configurations/webservers-apache.md' + - 'Nginx': 'configurations/webservers-nginx.md' + - Databases: + - 'Connect to the MySQL Database': 'configurations/databases-mysql.md' + - 'Use MariaDB instead of MySQL': 'configurations/databases-mariadb.md' + - 'Use PostgreSQL instead of MySQL': 'configurations/databases-postgresql.md' + - Installed extras: + - 'adminer (Database UI)': 'extras/adminer.md' + - 'blackfire (Profiling tool)': 'extras/blackfire.md' + - 'drupalconsole (Drupal CLI)': 'extras/drupal-console.md' + - 'drush (Drupal CLI)': 'extras/drush.md' + - 'elasticsearch (Search engine)': 'extras/elasticsearch.md' + - 'java': 'extras/java.md' + - 'mailhog (Mail catcher)': 'extras/mailhog.md' + - 'memcached (In-memory cache)': 'extras/memcached.md' + - 'newrelic (Performance monitoring)': 'extras/newrelic.md' + - 'nodejs': 'extras/nodejs.md' + - 'pimpmylog (Log viewer)': 'extras/pimpmylog.md' + - 'redis (In-memory database)': 'extras/redis.md' + - 'ruby': 'extras/ruby.md' + - 'selenium (BDD with Behat)': 'extras/selenium.md' + - 'solr (Search engine)': 'extras/solr.md' + - 'tidways (Profiling tool)': 'extras/tideways.md' + - 'upload-progress': 'extras/upload-progress.md' + - 'varnish (Caching reverse proxy)': 'extras/varnish.md' + - 'xdebug (Debugging tool)': 'extras/xdebug.md' + - 'xhprof (Profiling tool)': 'extras/xhprof.md' + - Extending Drupal VM: + - 'Adding Vagrant plugins Vagrantfile.local': 'extending/vagrantfile.md' + - 'Passing on CLI arguments to ansible': 'extending/ansible-args.md' + - 'Pre- and Post-Provision Scripts': 'extending/scripts.md' - Other Information: - - 'Using Different Base OSes': 'other/base-os.md' - - 'Using Different Webservers': 'other/webservers.md' - - 'Overriding configurations': 'other/overriding-configurations.md' - - 'Installing Drupal VM as a Composer Dependency': 'other/drupalvm-composer-dependency.md' - - 'Using other versions of PHP': 'other/php.md' - - 'BigPipe with Drupal VM': 'other/bigpipe.md' - - 'Drupal VM Management Tools': 'other/management-tools.md' - - 'Deploying Drupal VM to a production environment': 'other/production.md' - 'Networking Notes': 'other/networking.md' + - 'Vagrant and VirtualBox': 'other/vagrant-virtualbox.md' + - 'Improving Performance': 'other/performance.md' + - 'BigPipe with Drupal VM': 'other/bigpipe.md' + - 'Drupal multisite': 'deployment/multisite.md' - 'Drupal 6 Notes': 'other/drupal-6.md' - - 'Linux Notes': 'other/linux.md' - - 'Windows Notes': 'other/windows.md' - - 'Vagrant and VirtualBox Tips': 'other/vagrant-virtualbox.md' + - 'Drupal VM Management Tools': 'other/management-tools.md' + - 'Deploying to a production environment': 'other/production.md'