agaric/agaric-coop
10
1
Fork 0
Code Issues 102 Pull requests Projects Releases Packages Wiki Activity

Add all files needed to bring up VM and run agaric.com locally

Browse source
This commit is contained in:
benjamin melançon 2018-08-20 10:45:20 -04:00
parent 52c8b60bac
commit 4d2bc0ee24
742 changed files with 24037 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

50
box/docs/configurations/base-os.md Normal file
View file

@ -0,0 +1,50 @@
Drupal VM's configuration is designed to work with RedHat and Debian-compatible operating systems. Therefore, if you switch the `vagrant_box` in `config.yml` to any compatible OS, Drupal VM and all it's configuration should _Just Work™_... but that's not always the case.
Currently-supported OSes are:
- Ubuntu 16.04 'Xenial' (default)
- Ubuntu 14.04 'Precise'
- RedHat Enterprise Linux / CentOS 7
- RedHat Enterprise Linux / CentOS 6 (limited support)
- Debian 9 'Stretch'
- Debian 8 'Jessie'
For certain OSes, there are a couple other caveats and tweaks you may need to perform to get things running smoothly—the main features and latest development is only guaranteed to work with the default OS as configured in `default.config.yml`.
Some other OSes should work, but are not regularly tested with Drupal VM, including Debian 8/Jessie (`debian/jessie64`) and Debian 7/Wheezy (`debian/wheezy64`).
## Ubuntu 16.04 Xenial LTS
Everything should work out of the box with Ubuntu 16.04.
## Ubuntu 14.04 Trusty LTS
Everything should work out of the box with Ubuntu 14.04.
## RedHat Enterprise Linux / CentOS 7
Everything should work out of the box with RHEL 7.
## RedHat Enterprise Linux / CentOS 6
- **Apache without FastCGI**: If you want to use Apache with CentOS 6 on Drupal VM, you will need to modify the syntax of your `apache_vhosts` and remove the `extra_parameters: "{{ apache_vhost_php_fpm_parameters }}"` line from each one. Alternatively, you can use Nginx with the default configuration by setting `drupalvm_webserver: nginx` inside `config.yml`.
- **PHP OpCache**: PHP's OpCache (if you're using PHP > 5.5) requires the following setting to be configured in `config.yml` (see upstream bug: [CentOS (6) needs additional php-opcache package](https://github.com/geerlingguy/ansible-role-php/issues/39)):
```yaml
php_opcache_enabled_in_ini: false
```
- **Firewalld**: [Firewalld](http://www.firewalld.org/) is not available on CentOS 6, so the Drupal VM setting `firewall_disable_firewalld`, which defaults to `true`, must be overridden in `config.yml` and set to `false`:
```yaml
firewall_disable_firewalld: false
```
## Debian 9 Stretch
Everything should work out of the box with Debian 9.
## Debian 8 Jessie
Everything should work out of the box with Debian 8.

28
box/docs/configurations/databases-mariadb.md Normal file
View file

@ -0,0 +1,28 @@
Since Drupal VM is built in a modular fashion, and the upstream Ansible Role that installs and configures MySQL is built in a way that works with any MySQL-compatible replacement, you can easily swap out MySQL for MariaDB.
The simplest way is to add the following lines after the `# MySQL Configuration.` line in `config.yml`:
```yaml
mysql_packages:
- mariadb-client
- mariadb-server
- python-mysqldb
```
This set of packages works out of the box with Ubuntu 14.04 as well as the default Ubuntu 16.04 installation that comes with Drupal VM.
Alternatively, if you want to use RedHat 7 or CentOS 7 instead of Ubuntu, you can set the following variables to install and configure MariaDB instead of MySQL:
```yaml
mysql_packages:
- mariadb
- mariadb-server
- mariadb-libs
- MySQL-python
- perl-DBD-MySQL
mysql_daemon: mariadb
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
```

20
box/docs/configurations/databases-mysql.md Normal file
View file

@ -0,0 +1,20 @@
By default, this VM is set up so you can manage MySQL databases on your own. The default root MySQL user credentials are `drupal` for username and password, but you can change the password via `config.yml` (changing the `drupal_db_password` variable). I use [Sequel Pro](http://www.sequelpro.com/) (macOS-only) to connect to and manage databases, and Drush to sync databases (sometimes I'll just do a dump and import, but Drush is usually quicker, and is easier to do over and over again when you need it).
## 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.test/](http://adminer.drupalvm.test/), 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/).
## Connect using Sequel Pro (or a similar client):
1. Use the SSH connection type.
2. Set the following options:
- MySQL Host: `127.0.0.1`
- Username: `drupal`
- Password: `drupal` (or the password configured in `config.yml`)
- SSH Host: `192.168.88.88` (or the IP configured in `config.yml`)
- SSH User: `vagrant`
- SSH Key: (browse to your `~/.vagrant.d/` folder and choose `insecure_private_key`)
You should be able to connect as the root user and add, manage, and remove databases and users.

9
box/docs/configurations/databases-postgresql.md Normal file
View file

@ -0,0 +1,9 @@
Since Drupal VM is built in a modular fashion, you can swap out the database engine and use [PostgreSQL](https://www.postgresql.org/) instead of MySQL (as long as the version of Drupal you're using supports it!).
To switch from MySQL to PostgreSQL, switch the `drupal_db_backend` setting in your local `config.yml` to `pgsql`:
```yaml
drupal_db_backend: pgsql
```
For more PostgreSQL configuration options, see the [`geerlingguy.postgresql` Ansible role's README](https://github.com/geerlingguy/ansible-role-postgresql#readme).

22
box/docs/configurations/php.md Normal file
View file

@ -0,0 +1,22 @@
Drupal VM defaults to PHP 7.1, but you can also install and use 5.6, 7.0 or 7.2.
## Ubuntu
Ondřej Surý's PPA for PHP is used to install PHP 7.1, but you can switch version by changing `php_version` inside `config.yml` to `"5.6"`, `"7.0"` or `"7.2"`.
If you're using Apache with `mod_php` you should also add `libapache2-mod-php5.6` or `libapache2-mod-php7.0` to the `extra_packages` list.
_Note: XHProf does currently not work with PHP 7.1+, make sure you don't have it listed in `installed_extras`._
## RedHat/CentOS 7
Remi's RPM repository is included with Drupal VM, and you can make the following changes to use it to install a different version of PHP than 7.1:
1. Make sure you've followed the directions for switching to CentOS 7 in the [use a different base OS](base-os.md) guide.
2. Change `php_version` inside `config.yml` to `"5.6"`, `"7.0"` or `"7.2"`.
## Using default distribution packages
If you want parity with your production environment and wish to install the default distribution packages, set `php_version: ''` inside your `config.yml` to avoid adding Remi's or Ondřej's repositories. Doing this will use the default packages set in the [`geerlingguy.php`](https://github.com/geerlingguy/ansible-role-php) Ansible role.
_Note: If you're using a base OS with a PHP version older than what's assumed in the `geerlingguy.php` role, you will also need to override some of the default variables set by that role in your `config.yml`. See the [`geerlingguy.php` Ansible role's README](https://github.com/geerlingguy/ansible-role-php-#readme) for more information._

37
box/docs/configurations/webservers-apache.md Normal file
View file

@ -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 }}"
```

81
box/docs/configurations/webservers-nginx.md Normal file
View file

@ -0,0 +1,81 @@
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_vhosts` 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_vhosts`:
```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;
```
## Customizing server block configuration
If you can't customize via variables because an option isn't exposed, you can override the template used to generate the the virtualhost configuration file.
```yaml
nginx_vhost_template: "{{ config_dir }}/templates/nginx-vhost.conf.j2"
```
You can either copy and modify the provided `nginx-vhost.conf.j2` template, or extend it and use [template inheritace](http://jinja.pocoo.org/docs/2.9/templates/#template-inheritance) to override the specific template block you need to change.
_If you extend Drupal VM's provided base template, the path referenced should to be relative to playbook.yml._
```
{% extends 'templates/nginx-vhost.conf.j2' %}
{% block location_primary %}
location / {
try_files $uri @rewrite; # For Drupal <= 6
}
{% endblock %}
{% block location_image_styles %}
location ~ ^/sites/.*/files/imagecache/ {
try_files $uri @rewrite; # For Drupal <= 6
}
{% endblock %}
```
If you need to append or prepend content to a block, you can use the `{{ super() }}` Jinja2 function to return the original block content from the base template.
```
{% block location_deny %}
{{ super() }}
location ~* \.(txt|log)$ {
allow 192.168.0.0/16;
deny all;
}
{% endblock %}
```

141
box/docs/deployment/composer-dependency.md Normal file
View file

@ -0,0 +1,141 @@
To make future Drupal VM updates easier to integrate with an existing project, you might consider the more complex setup of installing Drupal VM as a `composer` dependency. Using a delegating `Vagrantfile` you are able to run `vagrant` commands anywhere in your project as well as separate your custom configuration files from Drupal VM's own files.
### Add Drupal VM as a Composer dependency
Add Drupal VM as a development dependency to your `composer.json`.
```
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.
_Note: This will be the directory where Drupal VM looks for other local configuration files as well. Such as `drupal_build_makefile` and `local.config.yml`._
```
├── composer.json
├── config/
│ ├── config.yml
│ ├── local.config.yml
│ └── Vagrantfile.local
├── docroot/
│ ├── ...
│ └── index.php
└── vendor/
├── ...
└── geerlingguy/
└── drupal-vm/
```
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
drupal_build_composer_project: false
drupal_build_composer: true
drupal_composer_path: false
drupal_composer_install_dir: "/var/www/drupalvm"
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:
```yaml
drupal_enabled_modules: []
```
### Create a delegating `Vagrantfile`
Create a delegating `Vagrantfile` that will catch all your `vagrant` commands and send them to Drupal VM's own `Vagrantfile`. Place this file in your project's root directory.
```ruby
# The absolute path to the root directory of the project. Both Drupal VM and
# the config file need to be contained within this path.
ENV['DRUPALVM_PROJECT_ROOT'] = "#{__dir__}"
# The relative path from the project root to the config directory where you
# placed your config.yml file.
ENV['DRUPALVM_CONFIG_DIR'] = "config"
# The relative path from the project root to the directory where Drupal VM is located.
ENV['DRUPALVM_DIR'] = "vendor/geerlingguy/drupal-vm"
# Load the real Vagrantfile
load "#{__dir__}/#{ENV['DRUPALVM_DIR']}/Vagrantfile"
```
When you issue `vagrant` commands anywhere in your project tree this file will be detected and used as a delegator for Drupal VM's own Vagrantfile.
Your project structure should now look like this:
```
├── Vagrantfile
├── composer.json
├── config/
│ ├── config.yml
│ ├── local.config.yml
│ └── Vagrantfile.local
├── docroot/
│ ├── ...
│ └── index.php
└── vendor/
├── ...
└── geerlingguy/
└── drupal-vm/
```
### Provision the VM
Finally provision the VM using the delegating `Vagrantfile`.
```sh
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 in a subdirectory without composer
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/
│ ├── ...
│ └── index.php
└── box/
├── ...
├── default.config.yml
└── Vagrantfile
```
Configure your `config.yml` as mentioned in the [`composer` section](#setup-your-configuration-files) above.
```yaml
post_provision_scripts:
# The default provided in `default.config.yml`:
- "../../examples/scripts/configure-solr.sh"
# With Drupal VM in a toplevel subdirectory
- "{{ config_dir }}/../examples/scripts/configure-solr.sh"
```
Your directory structure should now look like this:
```
├── Vagrantfile
├── config/
│ ├── config.yml
│ ├── local.config.yml
│ └── Vagrantfile.local
├── docroot/
│ ├── ...
│ └── index.php
└── box/
├── ...
├── default.config.yml
└── Vagrantfile
```
Provision the VM using the delegating `Vagrantfile`.
```sh
vagrant up
```

18
box/docs/deployment/composer-package.md Normal file
View file

@ -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 `drupal_build_composer_project` is `true`, and `drupal_build_makefile` and `drupal_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)._

28
box/docs/deployment/composer.md Normal file
View file

@ -0,0 +1,28 @@
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 `drupal_build_composer: true` in your `config.yml` (make sure `drupal_build_makefile` and `drupal_build_composer_project` are set to `false`).
3. Ensure `drupal_core_path` points to the webroot directory: `drupal_core_path: {{ drupal_composer_install_dir }}/web`
```yaml
drupal_build_makefile: false
drupal_build_composer_project: false
drupal_build_composer: true
drupal_core_path: "{{ drupal_composer_install_dir }}/web"
```
_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](composer-dependency.md)
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
drupal_build_composer_project: false
drupal_build_composer: true
drupal_composer_path: false
drupal_composer_install_dir: "/var/www/drupalvm"
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)._

16
box/docs/deployment/drush-make.md Normal file
View file

@ -0,0 +1,16 @@
If you want to build a Drupal site using a [Drush make file](http://www.drush.org/en/master/make/) instead of composer, set `drupal_build_composer_project: false`, `drupal_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
drupal_build_composer_project: false
drupal_build_makefile: true
```
Have a look at the defaults in `default.config.yml` and tweak the settings as you'd like in your `config.yml`, then run `vagrant up` as in the Quick Start Guide. Within a few minutes, you should have your site running and available at the `drupal_domain` configured in `config.yml`, falling back to the default `http://drupalvm.test` set in `default.config.yml`.
With the default settings the Drupal site will be built on the VM inside `/var/www/drupalvm/drupal/web` but the `web/` subdirectory is only required for `composer` based projects and you can simplify this directory structure by setting `drupal_core_path` to `/var/www/drupalvm/drupal`.
```yaml
drupal_build_composer_project: false
drupal_build_makefile: true
drupal_core_path: "/var/www/drupalvm/drupal"
```

25
box/docs/deployment/git.md Normal file
View file

@ -0,0 +1,25 @@
You can deploy a codebase directly inside Drupal VM via Git. You can deploy a Git-based Drupal site directly into a shared folder, or you can even deploy inside Drupal VM's own filesystem. The latter option offers better performance than any of the other deployment methods, since Drupal VM can use native filesystem caches and disk access.
This is also the recommended method for deploying Drupal sites to Drupal VM when used [in production](../other/production.md)
## Deploying Drupal via Git
Drupal VM uses the [`geerlingguy.drupal`](https://github.com/geerlingguy/ansible-role-drupal) Ansible role to deploy and manage Drupal codebases.
To deploy your Drupal project inside Drupal VM during provisioning, you need to set the following variables inside `config.yml`:
drupal_deploy: true
drupal_deploy_repo: "git@github.com:username/example.git"
drupal_deploy_dir: /var/www/drupal
The above settings assume you want to deploy a Drupal codebase in the GitHub repository `username/example.git` (or any other valid Git URL to which you have access). And it will place that codebase inside `/var/www/drupal`, which you might have mounted as a shared folder, or if you want even better performance, you could configure a 'reverse mount' or just work on the codebase inside the VM.
If you want to disable Drupal VM's default synced folder, set the following variable in `config.yml`:
vagrant_synced_folders: []
When you run `vagrant provision` or deploy Drupal VM to a production server, the `geerlingguy.drupal` role will check out the Git repository into the `drupal_deploy_dir`.
> Note: For private repositories, you can use your own SSH key if you use `ssh-agent`. On Mac or Linux, you can run `ssh-add -K` to add your default private key to the SSH Agent, or on Windows you can either use [Pageant](https://winscp.net/eng/docs/ui_pageant), an SSH agent built into your CLI emulator, or if you're on Windows 10, the SSH Agent that's installed with Ubuntu Bash.
For more information about this technique, please read Jeff Geerling's blog post, [Drupal VM on Windows - a fast container for BLT project development](https://www.jeffgeerling.com/blog/2017/drupal-vm-on-windows-fast-container-blt-project-development). Note that this technique is great for better performance on Windows, but it can be used on any platform where Drupal VM is used.

61
box/docs/deployment/local-codebase.md Normal file
View file

@ -0,0 +1,61 @@
If you already have a Drupal codebase on your host machine (e.g. in `~/Sites/my-drupal-site`), and don't want or need to build your Drupal site with a Drush make file, make the following changes to `config.yml` before building Drupal VM:
## Sync your Drupal codebase to the VM
Update the `vagrant_synced_folders` configuration to sync your local Drupal codebase to a folder within the machine:
```yaml
vagrant_synced_folders:
- local_path: ~/Sites/my-drupal-site
destination: /var/www/my-drupal-site
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 `drupal_build_*` variables and `install_site` to `false`:
```yaml
drupal_build_makefile: false
drupal_build_composer: false
drupal_build_composer_project: false
...
drupal_install_site: false
```
If you aren't copying back a database, and want to have Drupal VM run `drush si` for your Drupal site, you can leave `drupal_install_site` set to `true` and it will run a site install on your Drupal codebase using the `drupal_*` config variables.
## Update `drupal_core_path`
Set `drupal_core_path` to the same value as the `destination` of the synced folder you configured earlier:
```yaml
drupal_core_path: "/var/www/my-drupal-site"
```
This variable will be used for the document root of the webserver.
## Set the domain
By default the domain of your site will be `drupalvm.test` 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 }}"
```
## Update MySQL info
If you have your Drupal site configured to use a special database and/or user/password for local development (e.g. through a `settings.local.php` file), you can update the values for `mysql_databases` and `mysql_users` as well.
## 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](../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.

44
box/docs/deployment/multisite.md Normal file
View file

@ -0,0 +1,44 @@
For multisite installations, make the changes outlined in the [Local Drupal codebase](local-codebase.md) guide, but, using the `apache_vhosts` variable (or `nginx_vhosts` if using Nginx), configure as many domains pointing to the same docroot as you need:
```yaml
drupal_core_path: "/var/www/my-drupal-site"
...
apache_vhosts:
# Drupal VM's default domain, evaluating to whatever `vagrant_hostname` is set to (drupalvm.test by default).
- servername: "{{ drupal_domain }}"
serveralias: "www.{{ drupal_domain }}"
documentroot: "{{ drupal_core_path }}"
extra_parameters: "{{ apache_vhost_php_fpm_parameters }}"
- servername: "local.second-drupal-site.com"
documentroot: "{{ drupal_core_path }}"
extra_parameters: "{{ apache_vhost_php_fpm_parameters }}"
- servername: "local.third-drupal-site.com"
documentroot: "{{ drupal_core_path }}"
extra_parameters: "{{ apache_vhost_php_fpm_parameters }}"
```
If you need additional databases and database users, add them to the list of `mysql_databases` and `mysql_users`:
```yaml
mysql_databases:
- name: drupal
encoding: utf8
collation: utf8_general_ci
- name: drupal_two
encoding: utf8
collation: utf8_general_ci
mysql_users:
- name: drupal
host: "%"
password: drupal
priv: "drupal.*:ALL"
- name: drupal-two
host: "%"
password: drupal-two
priv: "drupal_two.*:ALL"
```

38
box/docs/extending/ansible-args.md Normal file
View file

@ -0,0 +1,38 @@
## Run a specific set of tagged tasks
You can filter which part of the provisioning process to run by specifying a set of tags using the `DRUPALVM_ANSIBLE_TAGS` environment variable.
```sh
# E.g. xdebug, drupal, webserver, database, cron...
DRUPALVM_ANSIBLE_TAGS=xdebug vagrant provision
# Or combine them (e.g. if adding new databases and virtualhosts).
DRUPALVM_ANSIBLE_TAGS=webserver,database vagrant provision
```
## 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.
> Note the following caveats:
>
> - Passing more than one argument may require special formatting. Read the [Ansible provisioner's `raw_arguments` docs](https://www.vagrantup.com/docs/provisioning/ansible_common.html#raw_arguments) for more info.
> - 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 "drupal_db_backend=pgsql"' vagrant provision
```

48
box/docs/extending/scripts.md Normal file
View file

@ -0,0 +1,48 @@
Drupal VM allows you to run extra shell scripts and ansible task files in the beginning and at the end of the provisioning process, in case you need to do extra setup, further configure the VM, or install extra software outside the purview of Drupal VM.
## Shell scripts
To use an extra script, configure the path to the script (relative to `provisioning/playbook.yml`) in `config.yml`:
```yaml
pre_provision_scripts:
- "../scripts/pre-provision.sh"
post_provision_scripts:
- "../scripts/post-provision.sh"
```
The above example results in a `pre-provision.sh` script running before the provisioning starts and a `post-provision.sh` script running after the main Drupal VM setup is complete. Pre and post provision scripts run after the first `vagrant up`, and then any time you run Vagrant provisioning (e.g. `vagrant provision` or `vagrant up --provision`).
_Note: The pre provision scripts run before any other packages are installed. If you want to use commands such as `git`, you need to install the packages yourself._
You can define as many scripts as you would like, and any arguments after the path will be passed to the shell script itself (e.g. `"- "../scripts/setup-paths.sh --option"`).
Place your pre and post provision scripts inside a `scripts` directory in the root of your Drupal VM project directory; this directory is gitignored, so you can continue to update Drupal VM without overwriting your scripts.
## Ansible task files
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/*"
post_provision_tasks_dir: "../scripts/post-provision.yml"
```
The path will be evaluated as a [glob pattern](https://docs.python.org/2/library/glob.html) so you can point to a single file or a directory matching a set of files.
The files matched will run in alphabetical order, and as with shell scripts, pre-provision task files will run before any other packages are installed.
## Ansible playbooks
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`.
```rb
config.vm.provision 'ansible' do |ansible|
ansible.playbook = "#{host_config_dir}/local.playbook.yml"
ansible.galaxy_role_file = "#{host_config_dir}/local.requirements.yml"
end
```
When you run `vagrant provision` this playbook will run after Drupal VM's own playbook.

86
box/docs/extending/vagrantfile.md Normal file
View file

@ -0,0 +1,86 @@
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.
To add a configuration just create a `Vagrantfile.local` in the root like so:
```ruby
config.vm.provider :virtualbox do |v|
# Enable GUI mode instead of running a headless machine.
v.gui = true
# Cap the host CPU execution at 50% usage.
v.customize ["modifyvm", :id, "--cpuexecutioncap", "50"]
end
```
### Automatically install Vagrant plugins
Drupal VM can be configured to ensure Vagrant plugins are installed by adding them to the `vagrant_plugins` list in your `config.yml` file.
```yaml
vagrant_plugins:
- name: vagrant-vbguest
- name: vagrant-hostsupdater
- name: vagrant-aws
```
### Example: Using the `vagrant-aws` provider
Add the following variables to your `config.yml`.
```yaml
aws_keypair_name: 'keypair'
aws_ami: 'ami-7747d01e'
aws_tags_name: 'Drupal VM'
aws_ssh_username: 'ubuntu'
aws_ssh_private_key: '~/.ssh/aws.pem'
```
Create a `Vagrantfile.local` in the root directory of your project.
```ruby
config.vm.provider :aws do |aws, override|
override.nfs.functional = false
aws.access_key_id = ENV['AWS_ACCESS_KEY_ID']
aws.secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
aws.keypair_name = vconfig['aws_keypair_name']
aws.tags['Name'] = vconfig['aws_tags_name']
aws.ami = vconfig['aws_ami']
override.ssh.username = vconfig['aws_ssh_username']
override.ssh.private_key_path = vconfig['aws_ssh_private_key']
end
```
Add the `AWS_ACCESS_KEY_ID` and the `AWS_SECRET_ACCESS_KEY` environment variables to your shell.
Then run `vagrant up --provider=aws` to provision the instance.
_For additional configuration options read the [Vagrant AWS Provider's README](https://github.com/mitchellh/vagrant-aws#readme)._
### Example: Using Drupal VM behind a corporate proxy with `vagrant-proxyconf`
Add the following variables to your `config.yml`.
```yaml
proxy_http: 'http://192.168.0.2:3128/'
proxy_https: 'http://192.168.0.2:3128/'
proxy_ftp: 'http://192.168.0.2:3128/'
proxy_none: 'localhost,127.0.0.1,{{ drupal_domain }}'
```
Create a `Vagrantfile.local` in the root directory of your project.
```ruby
if Vagrant.has_plugin?('vagrant-proxyconf')
config.proxy.http = vconfig['proxy_http']
config.proxy.https = vconfig['proxy_https']
config.git_proxy.http = vconfig['proxy_http']
config.proxy.no_proxy = vconfig['proxy_none']
config.proxy.ftp = vconfig['proxy_ftp']
end
```
_For additional configuration options read [Vagrant Proxyconf's README](https://github.com/tmatilai/vagrant-proxyconf#readme)._

3
box/docs/extras/adminer.md Normal file
View file

@ -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.test/](http://adminer.drupalvm.test/), 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).

23
box/docs/extras/blackfire.md Normal file
View file

@ -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.test/
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).

60
box/docs/extras/drupal-console.md Normal file
View file

@ -0,0 +1,60 @@
[Drupal Console](https://drupalconsole.com/) is a modern CLI for interacting with Drupal and scaffolding a site. It works only with Drupal 8+, and is built on top of the Symfony Console component.
To have Drupal Console installed globally inside Drupal VM, make sure `drupalconsole` is in the list of `installed_extras` in your `config.yml` file. If you're adding it to an existing Drupal VM, run `vagrant provision` so it gets installed. You also (or instead) might want to add Drupal Console as a dependency of your Drupal project—if you do this, you may not need to add `drupalconsole` to Drupal VM globally.
To use Drupal Console with a Drupal 8 site (in this case, using the default configuration that ships with Drupal VM):
1. Log into the VM with `vagrant ssh`.
2. Change directory to the Drupal site's document root: `cd /var/www/drupalvm/drupal/web`.
3. Use Drupal console (e.g. `drupal cache:rebuild all`).
You should see an output like:
```
vagrant@drupalvm:/var/www/drupalvm/drupal/web$ drupal cache:rebuild all
[+] Rebuilding cache(s), wait a moment please.
[+] Done clearing cache(s).
The command was executed successfully!
```
## Remote command execution using `--target`
To run commands on your host computer but execute them on the VM, add a new sites file `~/.console/sites/drupalvm.yml` on your host computer:
```yaml
dev:
root: /var/www/drupalvm/drupal
host: 192.168.88.88
user: vagrant
password: vagrant
```
Execute from host machine using the `--target` option.
drupal --target=drupalvm.test site:status
For more details, see [Drupal Console's documentation](https://docs.drupalconsole.com/en/alias/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).
## Remote command execution using `vagrant-exec`
You can use [`vagrant-exec`](https://github.com/p0deje/vagrant-exec) to execute commands remotely through Vagrant, and if you can't get Console to work with `--target`, you might want to try doing this (it's more convenient than logging into the VM just to run a Drupal VM command!).
First, install the plugin:
vagrant plugin install vagrant-exec
Add the following to a `Vagrantfile.local` in your project (set `directory` to your drupal docroot):
```ruby
if Vagrant.has_plugin?('vagrant-exec')
config.exec.commands '*', directory: '/var/www/drupal'
end
```
Now you can execute any Drupal Console command—even interactive ones!—from the host:
vagrant exec bin/drupal generate:module

81
box/docs/extras/drush.md Normal file
View file

@ -0,0 +1,81 @@
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.test`. For example, to check if Drush can connect to the site in Drupal VM, run:
```
$ drush @drupalvm.test status
Drupal version : 8.0.0-dev
Site URI : drupalvm.test
Database driver : mysql
Database hostname : localhost
Database port :
Database username : drupal
Database name : drupal
Database : Connected
Drupal bootstrap : Successful
Drupal user : Anonymous
Default theme : bartik
Administration theme : seven
PHP executable : /usr/bin/php
PHP configuration : /etc/php5/cli/php.ini
PHP OS : Linux
Drush script : /usr/local/share/drush/drush.php
Drush version : 7.0-dev
Drush temp directory : /tmp
Drush configuration :
Drush alias files :
Drupal root : /var/www/drupalvm/drupal
Site path : sites/default
File directory path : sites/default/files
Temporary file : /tmp
directory path
Active config path : [...]
Staging config path : [...]
```
Drupal VM automatically generates a drush alias file in `~/.drush/drupalvm.aliases.drushrc.php` with an alias for every site you have defined in the `apache_vhosts` variable.
If you want to customize the generated alias file you can override the `drush_aliases_host_template` and `drush_aliases_guest_template` variables in your `config.yml`.
```yaml
drush_aliases_host_template: "{{ config_dir }}/templates/drupalvm.aliases.drushrc.php.j2"
```
Eg. to only print the alias for your main domain, and not the subdomain you can override the file using a [Jinja2 child template](http://jinja.pocoo.org/docs/2.9/templates/#child-template).
```php
{% extends 'templates/drupalvm.aliases.drushrc.php.j2' %}
{% block aliases %}
{{ alias('drupalvm.test', drupal_core_path) }}
{% endblock %}
```
You can disable Drupal VM's automatic Drush alias file management if you want to manage drush aliases on your own. Just set the `configure_drush_aliases` variable in `config.yml` to `false`.
## 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._
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/<remote-alias>.aliases.drushrc.php`.
If you're still having issues, you can avoid `sql-sync` entirely and pipe the mysqldump output yourself with:
```
drush @remote sql-dump | drush @drupalvm.drupalvm.test 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).

24
box/docs/extras/elasticsearch.md Normal file
View file

@ -0,0 +1,24 @@
[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.
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
The Elasticsearch server can then be accessed at the configured domain:
http://drupalvm.test:9200
## Elasticsearch configuration
You can add configuration for Elasticsearch by setting the appropriate variables inside `config.yml` before you build Drupal VM.
elasticsearch_network_host: localhost
elasticsearch_http_port: 9200
For a list of available role variables, see the [`geerlingguy.elasticsearch` Ansible role's README](https://github.com/geerlingguy/ansible-role-elasticsearch#readme).

4
box/docs/extras/java.md Normal file
View file

@ -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).

13
box/docs/extras/mailhog.md Normal file
View file

@ -0,0 +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.test:8025/](http://drupalvm.test: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).

17
box/docs/extras/memcached.md Normal file
View file

@ -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).

23
box/docs/extras/newrelic.md Normal file
View file

@ -0,0 +1,23 @@
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
To make New Relic available globally for all your projects within Drupal VM, make the following changes inside `config.yml`, then run `vagrant up` (or `vagrant provision` if the VM is already built):
```yaml
# Make sure newrelic is not commented out in the list of installed_extras:
installed_extras:
[...]
- newrelic
[...]
# Set vars for your New Relic account:
# `newrelic` must be in installed_extras for this to work.
newrelic_license_key: yourkey
# Customize any additional vars relevant to your project needs.
# See all vars: https://github.com/weareinteractive/ansible-newrelic#variables
```
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).

30
box/docs/extras/nodejs.md Normal file
View file

@ -0,0 +1,30 @@
Node.js 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 Node.js—all you need to do is make sure `nodejs` is listed in the list of `installed_extras` inside `config.yml` before your provision Drupal VM.
## Choosing a version of Node.js
You can choose a version of Node.js to install using the `nodejs_version` variable in `config.yml`. See the [`geerlingguy.nodejs` Ansible role's README](https://github.com/geerlingguy/ansible-role-nodejs#readme) for all the currently-available versions for your OS.
```yaml
nodejs_version: "0.12"
```
## Installing global packages via NPM
To install packages globally, you can add them to the list of `nodejs_npm_global_packages` in `config.yml`. As an example, many developers use `phantomjs` as a ghost web driver for Behat tests inside Drupal VM. To install it globally, add it to the list:
```yaml
nodejs_npm_global_packages:
- phantomjs
```
You can even specify a specific version to install:
```yaml
nodejs_npm_global_packages:
- name: phantomjs
version: 2.1.7
```
For a list of available role variables, see the [`geerlingguy.nodejs` Ansible role's README](https://github.com/geerlingguy/ansible-role-nodejs#readme).

20
box/docs/extras/pimpmylog.md Normal file
View file

@ -0,0 +1,20 @@
[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.test/](http://pimpmylog.drupalvm.test) (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 [pimpmylog.drupalvm.test](http://pimpmylog.drupalvm.test)), 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:
- `/var/log/apache2/access.log`
- `/var/log/apache2/error.log` (this log will show Apache and PHP notices/warnings/errors)
- `/var/log/apache2/other_vhosts_access.log`
- `/var/log/mysql.err` (MySQL error log)
- `/var/log/mysql-slow.log` (MySQL slow query log)
- `/var/log/syslog` (enable the Drupal syslog module to route watchdog log entries to this file)
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).

17
box/docs/extras/redis.md Normal file
View file

@ -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).

15
box/docs/extras/ruby.md Normal file
View file

@ -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).

105
box/docs/extras/selenium.md Normal file
View file

@ -0,0 +1,105 @@
Behat is an open source behavior-driven development tool for PHP. You can use Behat to build and run automated tests for site functionality on your Drupal sites, and Drupal VM has excellent built-in support for Behat, using Selenium to run tests in a headless instance of either Google Chrome (default) or Firefox.
## Getting Started - Installing Prerequisites
To make Behat available globally for all your projects within Drupal VM, make the following changes inside `config.yml`, then run `vagrant up` (or `vagrant provision` if the VM is already built):
```yaml
# Make sure selenium is not commented out in the list of installed_extras:
installed_extras:
[...]
- selenium
[...]
# Add the following package to composer_global_packages or your Drupal project:
composer_global_packages:
- { name: drupal/drupal-extension, release: '*' }
```
After Drupal VM is finished provisioning, you should be able to log in and run the following command to make sure Behat is installed correctly:
```
$ behat --version
behat version 3.0.15
```
_You can also include `drupal/drupal-extension` directly in your project's `composer.json` file, and install the dependencies per-project._
## Setting up Behat for your project
Using the default Drupal site as an example (it's installed in `/var/www/drupalvm/drupal` by default, and is shared to the `./drupal` folder inside the drupal-vm directory on your host machine), the following steps will help you get your first Behat tests up and running!
1. Create a `behat.yml` file inside the docroot of your site (e.g. create this file alongside the rest of the Drupal codebase at `/var/www/drupalvm/drupal/behat.yml`), with the following contents:
default:
suites:
web_features:
paths: [ %paths.base%/features/web ]
contexts:
- WebContext
- Drupal\DrupalExtension\Context\DrupalContext
- Drupal\DrupalExtension\Context\MinkContext
- Drupal\DrupalExtension\Context\MessageContext
- Drupal\DrupalExtension\Context\DrushContext
extensions:
Behat\MinkExtension:
goutte: ~
javascript_session: selenium2
selenium2:
wd_host: http://drupalvm.test:4444/wd/hub
base_url: http://drupalvm.test
Drupal\DrupalExtension:
blackbox: ~
api_driver: 'drupal'
drupal:
drupal_root: '/var/www/drupalvm/drupal/web'
region_map:
content: "#content"
2. Log into Drupal VM with `vagrant ssh`, change directory to the Drupal site root (`cd /var/www/drupalvm/drupal`), then run `behat --init` to initialize the `features` folder where you will place test cases.
3. From either inside the VM or on the host machine, open up the new `features/web` folder Behat just created. Inside _that_ folder, create `HomeContent.feature` with the following contents:
Feature: Test DrupalContext
In order to prove Behat is working correctly in Drupal VM
As a developer
I need to run a simple interface test
Scenario: Viewing content in a region
Given I am on the homepage
Then I should see "No front page content has been created yet" in the "content"
4. Now, inside Drupal VM, change directory to `/var/www/drupalvm/drupal` again, and run the command `behat` (which runs all the tests you've created—which should just be one so far).
If everything was done correctly, you should see:
```console
$ behat
Feature: Test DrupalContext
In order to prove Behat is working correctly in Drupal VM
As a developer
I need to run a simple interface test
Scenario: Viewing content in a region # features/drupal/HomeContent.feature:6
Given I am on the homepage # Drupal\DrupalExtension\Context\MinkContext::iAmOnHomepage()
Then I should see "No front page content has been created yet" in the "content" # Drupal\DrupalExtension\Context\MinkContext::assertRegionText()
1 scenario (1 passed)
2 steps (2 passed)
0m0.56s (26.48Mb)
```
Hooray! Now you're ready to get started testing ALL THE THINGS! Check out the following resources for more information about Behat and Drupal:
- [Behat 3.0 Documentation](http://behat.readthedocs.org/en/v3.0/)
- [Drupal Extension Documentation](https://behat-drupal-extension.readthedocs.org/en/3.0/)
## Debugging issues
There are many different ways you can run Behat tests via PhantomJS and other drivers, and some people have encountered issues and workarounds with different approaches. Here are some relevant issues you can read through for more background:
- [Selenium Questions](https://github.com/geerlingguy/drupal-vm/issues/367)
- [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).

32
box/docs/extras/solr.md Normal file
View file

@ -0,0 +1,32 @@
Drupal VM makes using Apache Solr easy; just make sure `solr` is in the list of `installed_extras` in your `config.yml`, and when you build Drupal VM, the latest version of Apache Solr will be installed.
Inside of Drupal, you can use any of the available Apache Solr integration modules (e.g. [Apache Solr Search](https://www.drupal.org/project/apachesolr) or [Search API Solr Search](https://www.drupal.org/project/search_api_solr)), and when you configure the modules, follow the installation instructions included with the module.
The URL to connect to the local solr server (assuming you're using the default `solr_port` of 8983) from Drupal is:
http://localhost:8983/solr/collection1
This will connect to the default search core (`collection1`) set up by Solr. If you are using a multisite installation and want to have a search core per Drupal site, you can add more cores through Apache Solr's admin interface (visit `http://drupalvm.test:8983/solr/`), then connect to each core by adding the core name to the end of the above URL (e.g. `core2` would be `http://localhost:8983/solr/core2`).
## Using Different Solr versions
Drupal VM installs Apache Solr 5.x by default, but you can use 6.x, 4.x, or other versions instead. To do this, [see the version-specific test examples](https://github.com/geerlingguy/ansible-role-solr/tree/master/tests) in the `geerlingguy.solr` role.
One important note: If you use Solr 5.x or 6.x (or later), you need to make sure your VM has Java 8+. By default, many of the supported OSes only install Java 7. To install Java 8, see the `geerlingguy.java` role examples for [installing Java 8 on RHEL/CentOS or Ubuntu < 16.04](https://github.com/geerlingguy/ansible-role-java#example-playbook-install-openjdk-8).
## Configuring the Solr search core for Drupal
Before Drupal content can be indexed correctly into Apache Solr, you will need to copy the Drupal Apache Solr Search or Search API Apache Solr configuration into place, and restart Apache Solr. Drupal VM comes with an example post provision script for automating this. Simply add it to `post_provision_scripts`:
```yaml
post_provision_scripts:
- "../examples/scripts/configure-solr.sh"
```
Note that for Drupal 8, this script will create a new search core named `d8` (rather than modifying the default core `collection1`).
## 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.
For a list of available role variables, see the [`geerlingguy.solr` Ansible role's README](https://github.com/geerlingguy/ansible-role-solr#readme).

17
box/docs/extras/tideways.md Normal file
View file

@ -0,0 +1,17 @@
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.
To use Tideways make sure `tideways` is in the list of `installed_extras`.
**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 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.test/](http://xhprof.drupalvm.test) 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.php-tideways` Ansible role's README](https://github.com/geerlingguy/ansible-role-php-tideways#readme).

3
box/docs/extras/upload-progress.md Normal file
View file

@ -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).

64
box/docs/extras/varnish.md Normal file
View file

@ -0,0 +1,64 @@
[Varnish](https://www.varnish-software.com/) is an advanced reverse proxy and HTTP accelerator. At a basic level, it can act as a lightweight, very fast, and highly configurable static cache in front of your Drupal site. It also works as a load balancer and has some other tricks up it's sleeve, but for Drupal VM's purposes, you can think of it as a simple way to supercharge your site via proxy caching.
To enable Varnish, make sure `varnish` is in the list of your `installed_extras` in `config.yml`, and run `vagrant provision`.
There are a few varnish configuration variables further down in `default.config.yml` that you may wish to configure. You can use your own `.vcl` file template (instead of the generic Drupal 7-focused generic one) by editing the `varnish_default_vcl_template_path`, and you can use a different port for Varnish by changing `varnish_listen_port`.
If you'd like to use Varnish on port 80, and switch Apache to a different backend port, you can do so pretty easily; just make sure you have the following values set in your `config.yml` file, and run `vagrant provision` to have Ansible make the necessary changes:
```yaml
apache_listen_port: "81"
varnish_listen_port: "80"
varnish_default_backend_port: "81"
```
## Required Drupal Changes
In order for Varnish to actually do anything helpful (instead of just pass through requests and responses to/from the Apache backend), you need to set a few settings in Drupal:
- On the `/admin/config/development/performance` page:
- Check the 'Cache pages for anonymous users' setting (if it's not already enabled).
- Set both the 'Minimum Cache Lifetime' and 'Expiration of cached pages' values to something reasonable (e.g. 5, 10, or 15 minutes—or much more if you don't update the content on the site much!).
You will also need to make a few small changes to your site's `settings.php` configuration to make Drupal work correctly behind a reverse proxy like Varnish:
```php
$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.
## Extending the base `drupalvm.vcl.j2` template
If you can't customize via variables because an option isn't exposed, you can extend the base `drupalvm.vcl.j2` through [Jinja2 template inheritance](http://jinja.pocoo.org/docs/2.9/templates/#template-inheritance).
```yaml
varnish_default_vcl_template_path: "{{ config_dir }}/templates/drupalvm.vcl.j2"
```
Either copy the `drupalvm.vcl.j2` and modify it to your liking, or extend it and override the blocks you need to adjust.
_If you extend Drupal VM's provided base template, the path referenced should to be relative to playbook.yml._
```
{% extends 'templates/drupalvm.vcl.j2' %}
{% block backend -%}
{{ super() }}
.connect_timeout = 1s;
{% endblock %}
{% block vcl_deliver -%}
unset resp.http.X-Url;
unset resp.http.X-Host;
unset resp.http.Purge-Cache-Tags;
# Do not set X-Varnish-Cache headers.
{% endblock %}
```
The [`{{ super() }}` Jinja2 function](http://jinja.pocoo.org/docs/2.9/templates/#super-blocks) returns the original block content from the base template.
For a list of available role variables, see the [`geerlingguy.varnish` Ansible role's README](https://github.com/geerlingguy/ansible-role-varnish#readme).

78
box/docs/extras/xdebug.md Normal file
View file

@ -0,0 +1,78 @@
[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`:
- Change `php_xdebug_default_enable` (and, optionally, `php_xdebug_coverage_enable` to get code coverage reports) to `1`
- Make sure `xdebug` is in the list of `installed_extras`
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
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:
```yaml
php_xdebug_idekey: PHPSTORM
```
### 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:
```yaml
php_xdebug_idekey: sublime.xdebug
```
To configure a Sublime Text project to use XDebug when debugging, add the following `settings` key to your project's `.sublime-project` file:
```json
"settings": {
"xdebug": {
"path_mapping": {
"/var/www/projectname/docroot" : "/Users/geerlingguy/Sites/projectname/docroot",
},
"url": "http://local.projectname.com/",
"super_globals": true,
"close_on_stop": true
}
}
```
This assumes you have already installed [SublimeTextXdebug](https://github.com/martomo/SublimeTextXdebug) via Package Control.
### 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
```
### XDebug over SSH/Drush
As long as `xdebug` is listed in `installed_extras` Drupal VM is configured to accept the `PHP_IDE_CONFIG`, `XDEBUG_CONFIG` and `PHP_OPTIONS` environment variables over SSH and this can be used to set up some IDE's as well as enable XDebug on a per request basis:
```
PHP_OPTIONS="-d xdebug.default_enable=1" drush @drupalvm.drupalvm.test migrate-import
```
To send the environment variables when using `vagrant ssh`, [create a `Vagrantfile.local`](../extending/vagrantfile.md) with:
```
config.ssh.forward_env = ['PHP_IDE_CONFIG', 'XDEBUG_CONFIG', 'PHP_OPTIONS']
```
And you can run:
```
XDEBUG_CONFIG="-d default_enable=1" vagrant ssh -c 'php /var/www/drupalvm/drupal/web/core/scripts/run-tests.sh --url http://drupalvm.test --all'
XDEBUG_CONFIG="-d default_enable=1" vagrant ssh -c 'cd /var/www/drupalvm/drupal/web/core; php ../../vendor/bin/phpunit tests/Drupal/Tests/Core/Password/PasswordHashingTest.php'
```
## 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).

20
box/docs/extras/xhprof.md Normal file
View file

@ -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 or newer, 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.test/](http://xhprof.drupalvm.test) 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.test`
**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).

48
box/docs/getting-started/configure-drupalvm.md Normal file
View file

@ -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. 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._
#### 4. 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
```
## Additional resources
- Jeff Geerling's DrupalDC talk "[Drupal VM Tips and Tricks for Drupal 8 development](https://www.youtube.com/watch?v=_wV6MDsT42Y)"

78
box/docs/getting-started/installation-linux.md Normal file
View file

@ -0,0 +1,78 @@
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
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
Ubuntu 15.10 for Desktop (and some other versions) doesn't include NFS support by default, so if you get a message like `It appears your machine doesn't support NFS`, then you should do the following to install NFS server: `sudo apt-get install -y nfs-server`.
### Fedora
Under Fedora, you might encounter a message like the following upon the first time you use VirtualBox or Vagrant:
```
$ vagrant status
VirtualBox is complaining that the kernel module is not loaded. Please
run `VBoxManage --version` or open the VirtualBox GUI to see the error
message which should contain instructions on how to fix this error.
```
In this case, you need to install your system's appropriate kernel module, and you'll also need to install `gcc` and run a specific VirtualBox installation script (or reinstall VirtualBox entirely) so the kernel module is loaded correctly. Do the following:
1. `sudo dnf install "kernel-devel-uname-r == $(uname -r)"`
2. `sudo dnf install gcc`
3. `sudo /var/lib/vboxdrv.sh setup`
Periodically, when you upgrade your system's Linux kernel, you might need to run steps 2 and 3 above again, or you can uninstall and reinstall VirtualBox (e.g. `sudo dnf remove VirtualBox && sudo dnf install VirtualBox`).
### Arch Linux
Arch Linux uses Python 3 as the default while Ansible requires Python 2. To get around parse errors you need to specify that the `python2` binary should be used instead of the default `python`. Add the following to your `config.yml`:
```
ansible_python_interpreter: "/usr/bin/env python2"
```
## Troubleshooting Vagrant Synced Folders
Most issues have to do synced folders. These are the most common ones:
### 'Mounting NFS shared folders...' hangs
There are a few different reasons this particular problem can occur. You may run into the error below during `vagrant up`:
```
The following SSH command responded with a non-zero exit status.
Vagrant assumes that this means the command failed!
mount -o '' 192.168.88.1:'/Users/myusername/Sites/drupalvm' /var/www/drupalvm
Stdout from the command:
Stderr from the command:
stdin: is not a tty
mount.nfs: Connection timed out
```
If the directory you are trying to mount is within an encrypted folder or volume, NFS will very often fail with the above message as well as `exportfs: /home/myusername/Sites/drupalvm does not support NFS export`. There is no workaround other than sharing a directory that is not encrypted.
If encryption is not the issue then it's likely that either NFS isn't running correctly on your host, certain ports or protocols are being blocked by the system firewall, or you need to add additional mount options to your `vagrant_synced_folders` configuration. Try the following fixes:
1. On Ubuntu, if you get a message like `It appears your machine doesn't support NFS`, run `sudo apt-get install -y nfs-server`.
1. Make sure the `vboxnet` interfaces are not being blocked by your system firewall. For Fedora (and many flavors of Linux), check out this guide for more: [Get Vagrant's NFS working under Fedora 20](https://web.archive.org/web/20150706105420/http://blog.bak1an.so/blog/2014/03/23/fedora-vagrant-nfs/).
1. Add `mount_options: ['vers=3']` to your synced folder definition in config.yml after the other options like `local_path`, `destination`, and `type`.
After attempting any of the above fixes, run `vagrant reload --provision` to restart the VM and attempt mounting the synced folder again, or `vagrant destroy -f && vagrant up` to rebuild the VM from scratch.
## Intel VT-x virtualization support
On some laptops, Intel VT-x virtualization (which is built into most modern Intel processors) is enabled by default. This allows VirtualBox to run virtual machines efficiently using the CPU itself instead of software CPU emulation. If you get a message like "VT-x is disabled in the bios for both all cpu modes" or something similar, you may need to enter your computer's BIOS or UEFI settings and enable this virtualization support.

5
box/docs/getting-started/installation-macos.md Normal file
View file

@ -0,0 +1,5 @@
Please read through the [Quick Start Guide](https://github.com/geerlingguy/drupal-vm#quick-start-guide) to get started.
<iframe width="560" height="315" src="https://www.youtube.com/embed/PR9uh_GGZhI" frameborder="0" allowfullscreen></iframe>
_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._

77
box/docs/getting-started/installation-windows.md Normal file
View file

@ -0,0 +1,77 @@
Please read through the [Quick Start Guide in the README](https://github.com/geerlingguy/drupal-vm#quick-start-guide) to get started.
<iframe width="560" height="315" src="https://www.youtube.com/embed/mNio_aXMLos" frameborder="0" allowfullscreen></iframe>
_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
If you are running Windows 10 (Anniversary edition) or later, you can install the Windows Subsytem for Linux, which allows you to install an Ubuntu-based CLI inside of Windows. With this installed, you can then manage and run Drupal VM inside the Linux-like environment. Follow these steps to use Drupal VM in the WSL:
1. Install Vagrant and VirtualBox in Windows (links in the [Drupal VM Quick Start Guide](https://github.com/geerlingguy/drupal-vm#quick-start-guide)).
2. [Install/Enable the Windows Subsystem for Linux](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide).
1. Create an admin account for the Ubuntu Bash environment when prompted.
3. In a local copy of Drupal VM (downloaded or Git cloned into a path that's in the Windows filesystem, e.g. `/mnt/c/Users/yourusername/Sites/drupal-vm`), run `wrun vagrant up`.
If you need to run any other `vagrant` commands (with the exception of `vagrant ssh`—for now, that must be run in a different environment; see [Vagrant: Use Linux Subsystem on Windows](https://github.com/mitchellh/vagrant/issues/7731)), you can do so by prefixing them with `wrun`.
> Note: using `wrun`, interactive prompts don't seem to work (e.g. if you run `vagrant destroy` without `-f`, you have to Ctrl-C out of it because it just hangs).
>
> Note 2: that the WSL is still in beta, and tools like `cbwin` are still undergoing rapid development, so some of these instructions are subject to change!
## Command line environment
If you're not on Windows 10, or if you don't want to install the WSL, you can use PowerShell, Git Bash, Git Shell, or other PowerShell-based environments with Drupal VM and Vagrant; however you might want to consider using a more POSIX-like environment so you can more easily work with Drupal VM:
- [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.
## Troubleshooting Vagrant Synced Folders
Most issues have to do synced folders. These are the most common ones:
_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
Creating symbolic links in a shared folder will fail with a permission or protocol error.
There are two parts to this:
1. VirtualBox does not allow gets VMs to create symlinks in synced folders by default.
2. Windows does not allow the creation of symlinks unless your local policy allows it; see [TechNet article](https://technet.microsoft.com/en-us/library/dn221947%28v=ws.10%29.aspx). Even if local policy allows it, many users experience problems in the creation of symlinks.
Using Ubuntu bash under Windows 10 _can_ make this easier, but there are still issues when creating and managing symlinks between the bash environment and the guest Vagrant operating system.
### Git and File permissions
If you're using a synced folder for your project, you should choose to either work _only_ inside the VM, or _only_ on the host machine. Don't commit changes both inside the VM and on the host unless you know what you're doing and have Git configured properly for Unix vs. Windows line endings. File permissions and line endings can be changed in ways that can break your project if you're not careful!
You should probably disable Git's `fileMode` option inside the VM and on your host machine if you're running Windows and making changes to a Git repository:
git config core.fileMode false
### "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:
1. Delete `~/.vagrant.d/insecure_private_key`
2. Run `vagrant ssh-config`
3. Restart the VM with `vagrant reload`
### Windows 7 requires PowerShell upgrade
If you are running Windows 7 and `vagrant up` hangs, you may need to upgrade PowerShell. Windows 7 ships with PowerShell 2.0, but PowerShell 3.0 or higher is required. For Windows 7, you can upgrade to PowerShell 4.0 which is part of the [Windows Management Framework](http://www.microsoft.com/en-us/download/details.aspx?id=40855).
## Hosts file updates
If you install either the `vagrant-hostsupdater` (installed by default unless removed from `vagrant_plugins` in your `config.yml`) or `vagrant-hostmanager` plugin, you might get a permissions error when Vagrant tries changing the hosts file. On a macOS or Linux workstation, you're prompted for a sudo password so the change can be made, but on Windows, you have to do one of the following to make sure hostsupdater works correctly:
1. Run PowerShell or whatever CLI you use with Vagrant as an administrator. Right click on the application and select 'Run as administrator', then proceed with `vagrant` commands as normal.
2. Change the permissions on the hosts file so your account has permission to edit the file (this has security implications, so it's best to use option 1 unless you know what you're doing). To do this, open `%SystemRoot%\system32\drivers\etc` in Windows Explorer, right-click the `hosts` file, and under Security, add your account and give yourself full access to the file.
## Intel VT-x virtualization support
On some laptops, Intel VT-x virtualization (which is built into most modern Intel processors) is enabled by default. This allows VirtualBox to run virtual machines efficiently using the CPU itself instead of software CPU emulation. If you get a message like "VT-x is disabled in the bios for both all cpu modes" or something similar, you may need to enter your computer's BIOS settings and enable this virtualization support.

102
box/docs/getting-started/syncing-folders.md Normal file
View file

@ -0,0 +1,102 @@
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`:
```yaml
vagrant_synced_folders:
- local_path: .
destination: /var/www/drupalvm
type: smb
create: true
```
You can add as many synced folders as you'd like, and you can configure [any type of share](https://www.vagrantup.com/docs/synced-folders/index.html) supported by Vagrant; just add another item to the list of `vagrant_synced_folders`.
## Options
The synced folder options exposed are `type`, `excluded_paths` (when using rsync), `id`, `create`, `mount_options` and `nfs_udp`. Besides these there are some sane defaults set when using rsync. For example all files synced with rsync will be writable by everyone, thus allowing the web server to create files.
### Overriding defaults
If you feel the need to fine-tune some of the options not exposed, the entire options hash passed to Vagrant can be overriden using `options_override`.
The merge of the default options and `options_override` is shallow, so you can use it to remove flags from eg. `rsync__args`.
One scenario where this might be useful is when you are moving generated code from the virtual machine back to your local machine and you want the files to have appropriate permissions instead of the default 666/777.
```yaml
options_override:
owner: vagrant
group: www-data
rsync__args: [
"--verbose", "--archive", "--delete",
"--chmod=gu=rwX,o=rX", # 664 for files, 775 for directories
]
```
## Synced Folder Troubleshooting
_Read the following [overview on the performance of the different synced folder mechanisms](../other/performance.md#synced-folder-performance)._
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:
### Using Native Synced Folders
You can use a native synced folder, which should work pretty flawlessly on any platform, but with a potential serious performance downside (compared to other synced folder methods). Just set `type` to `""`.
```yaml
vagrant_synced_folders:
- local_path: .
destination: /var/www/docroot
type: ""
create: true
```
See [this issue](https://github.com/geerlingguy/drupal-vm/issues/67) for more information.
### Permissions-related errors
If you're encountering errors where Drupal or some other software inside the VM is having permissions issues creating or deleting files inside a synced folder, you might need to either make sure the file permissions are correct on your host machine (if a folder is not readable by you, it probably also won't be readable when mounted via NFS!), or add extra configuration to the synced folders item (if using a sync method like `rsync`):
```yaml
vagrant_synced_folders:
- local_path: .
destination: /var/www/drupalvm
type: ""
create: true
mount_options: ["dmode=775", "fmode=664"]
options_override:
owner: "vagrant"
group: "www-data"
```
See [this issue](https://github.com/geerlingguy/drupal-vm/issues/66) for more details.
### Using [`vagrant-bindfs`](https://github.com/gael-ian/vagrant-bindfs) to work around permissions-related errors
If you're using NFS synced folders the mounted directories will use the same numeric permissions on the guest VM as on the host OS. If you're on OSX for instance, your files within the VM would be owned by 501:20. To correct these permissions you can use the [`vagrant-bindfs` plugin](https://github.com/gael-ian/vagrant-bindfs) to mount your NFS folders to a temporary location and then re-mount them to the actual destination with the correct ownership.
First install the plugin with `vagrant plugin install vagrant-bindfs` and then add a `Vagrantfile.local` with the following:
```rb
vconfig['vagrant_synced_folders'].each do |synced_folder|
case synced_folder['type']
when "nfs"
guest_path = synced_folder['destination']
host_path = File.expand_path(synced_folder['local_path'])
config.vm.synced_folders[guest_path][:guestpath] = "/var/nfs#{host_path}"
config.bindfs.bind_folder "/var/nfs#{host_path}", guest_path,
u: 'vagrant',
g: 'www-data',
perms: 'u=rwX:g=rwD',
o: 'nonempty'
config.nfs.map_uid = Process.uid
config.nfs.map_gid = Process.gid
end
end
```
### Other NFS-related errors
If you're having other weird issues, and none of the above fixes helps, you might want to try a different synced folder method (see top of this page), or something like File Conveyor or a special rsync setup (see [here](http://wolfgangziegler.net/auto-rsync-local-changes-to-remote-server#comments) for some examples).

BIN
box/docs/images/drupal-vm-logo.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 2.9 KiB

13
box/docs/index.md Normal file
View file

@ -0,0 +1,13 @@
<p align="center"><img src="images/drupal-vm-logo.png" alt="Drupal VM Logo" /></p>
[Drupal VM](https://www.drupalvm.com/) is A VM for local Drupal development, built with Vagrant + Ansible.
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
Please feel free to edit any of the pages in this documentation via the 'Edit on GitHub' link at the top right. If you would like to help improve Drupal VM, feel free to submit new issues or pull requests to the [Drupal VM](https://github.com/geerlingguy/drupal-vm) project on GitHub!

44
box/docs/js/fix_search.js Normal file
View file

@ -0,0 +1,44 @@
(function (){
var MutationObserver = (function () {
var prefixes = ['WebKit', 'Moz', 'O', 'Ms', '']
for (var i=0; i < prefixes.length; i++) {
if (prefixes[i] + 'MutationObserver' in window) {
return window[prefixes[i] + 'MutationObserver'];
}
}
return false;
}());
/*
* RTD messes up MkDocs' search feature by tinkering with the search box defined in the theme, see
* https://github.com/rtfd/readthedocs.org/issues/1088. This function sets up a DOM4 MutationObserver
* to react to changes to the search form (triggered by RTD on doc ready). It then reverts everything
* the RTD JS code modified.
*
* @see https://github.com/rtfd/readthedocs.org/issues/1088#issuecomment-224715045
*/
$(document).ready(function () {
if (!MutationObserver) {
return;
}
var target = document.getElementById('rtd-search-form');
var config = {attributes: true, childList: true};
var observer = new MutationObserver(function(mutations) {
// if it isn't disconnected it'll loop infinitely because the observed element is modified
observer.disconnect();
var form = $('#rtd-search-form');
var path = window.location.pathname;
var branch = path.split('/')[2];
form.empty();
form.attr('action', window.location.origin + '/en/' + branch + '/search.html');
$('<input>').attr({
type: "text",
name: "q",
placeholder: "Search docs"
}).appendTo(form);
});
observer.observe(target, config);
});
}());

1
box/docs/other/acquia.md Normal file
View file

@ -0,0 +1 @@
To emulate the default Acquia Cloud environment with Drupal VM you should create a `config.yml` and override a few defaults from `default.config.yml`. For an up-to-date example, use [BLT's `config.yml`](https://github.com/acquia/blt/blob/8.x/scripts/drupal-vm/config.yml). Some of the variables in the BLT example are customized for BLT and you should be looking specifically at `vagrant_box`, `php_version`, and `php_packages_extra`.

43
box/docs/other/bigpipe.md Normal file
View file

@ -0,0 +1,43 @@
[BigPipe](https://www.drupal.org/documentation/modules/big_pipe) is a Drupal module that was added as an 'experimental' module in Drupal 8.1. BigPipe allows PHP responses to be streamed in-progress so authenticated end users can recieve a cached response very quickly, with placeholders for more dynamic (harder to cache) content that are filled in during the same request.
To do this, BigPipe requires an environment configured to allow the authenticated request response to be streamed from PHP all the way through to the client. All parts of the web stack that intermediate the connection have to have output buffering disabled so the response stream can flow through.
Drupal VM's default configuration uses Apache with the `mod_proxy_fastcgi` module to connect to PHP-FPM, which isn't the most optimal configuration for BigPipe, and requires gzip compression to be disabled, so you should either switch to Nginx or consider further customizing the Apache configuration.
Drupal VM's Varnish configuration works with BigPipe out of the box, as it allows the backend response to be streamed whenever BigPipe is enabled (it outputs a `Surrogate-Control: BigPipe/1.0` header to tell Varnish when to stream the response).
## PHP configuration
BigPipe doesn't require any particular modifications to PHP in Drupal VM's default configuration. However, for some scenarios, you might want to disable php's `output_buffering` entirely by setting `php_output_buffering: "Off"` in `config.yml`, or change the `output_buffering` level from it's default of `4096` bytes.
## Nginx configuration
There is no extra configuration required to get BigPipe working with Nginx.
Nginx is the recommended way to use BigPipe, for the following reasons:
- It's easier to configure Nginx to handle hundreds (or more) concurrent connections through to PHP-FPM than `mod_php`, and more widely used than the other compatible Apache CGI modules `mod_fcgid` and `mod_fastcgi`
- Nginx intelligently disables output buffering and gzip if the `X-Accel-Buffering: no` header is present (BigPipe sets this header automatically). This means gzip and buffering can be enabled for most requests, and disabled on-the-fly by BigPipe.
## Apache configuration
Apache has three primary means of interacting with PHP applications like Drupal: `mod_php`, `mod_fastcgi`, and `mod_proxy_fcgi`. Drupal VM uses `mod_proxy_fcgi`, which is the most widely used and supported method of using Apache with PHP-FPM for the best scalability and memory management with Apache + PHP.
For all of these methods, you have to make sure `mod_deflate` gzip compression is disabled; you can do this by modifying the VirtualHost's `extra_parameters` parameter in the `apache_vhosts` list inside `config.yml`:
apache_vhosts:
- servername: "{{ drupal_domain }}"
serveralias: "www.{{ drupal_domain }}"
documentroot: "{{ drupal_core_path }}"
extra_parameters: |
{{ apache_vhost_php_fpm_parameters }}
SetEnv no-gzip 1
This will disable the `mod_deflate` module for any requests inside that directory.
If you want to switch Apache to use `mod_php` instead of proxying requests through PHP-FPM, you can make the following changes in `config.yml`:
1. Add `libapache2-mod-php7.1` to `extra_packages` in `config.yml`.
2. Delete the `extra_parameters` under any Drupal site in the list of `apache_vhosts` (so there is no `SetHandler` rule).
You can also disable PHP-FPM and remove the two `proxy` entries from `apache_mods_enabled` if you don't want to use PHP-FPM with Apache at all, but that's optional; it won't break anything to run Apache with `mod_php` and `mod_proxy_fastcgi` at the same time.

166
box/docs/other/docker.md Normal file
View file

@ -0,0 +1,166 @@
Drupal VM can be used with [Docker](https://www.docker.com) instead of or in addition to Vagrant:
- You can quickly install a Drupal site (any version) using the official [`geerlingguy/drupal-vm`](https://hub.docker.com/r/geerlingguy/drupal-vm/) image.
- You can build a customized local instance using Docker, pulling the official [`geerlingguy/drupal-vm`](https://hub.docker.com/r/geerlingguy/drupal-vm/) image.
- You can 'bake your own' customized Drupal VM Docker image and reuse it or share it with your team.
> **Docker support is currently experimental**, so unless you're already familiar with Docker, it might be best to wait until later versions of Drupal VM are released with more stable support.
## Managing your hosts file
Before using Docker to run Drupal VM, you should [edit your hosts file](https://support.rackspace.com/how-to/modify-your-hosts-file/) and add the following line:
192.168.89.89 drupalvm.test
(Substitute the IP address and domain name you'd like to use to access your Drupal VM container.)
You can also add other subdomains if you're using other built-in services, e.g. `adminer.drupalvm.test`, `xhprof.drupalvm.com`, etc.
> If you're using Docker for Mac, you need to perform one additional step to ensure you can access Drupal VM using a unique IP address:
>
> 1. Add an alias IP address on the loopback interface: `sudo ifconfig lo0 alias 192.168.89.89/24`
> 2. When you're finished using the container, delete the alias: `sudo ifconfig lo0 -alias 192.168.89.89` (or restart your Mac).
>
> You'll have to create the alias again after restarting your Mac. See [this Docker (moby) issue](https://github.com/moby/moby/issues/22753#issuecomment-246054946) for more details.
## Method 1: Get a quick Drupal site installed with Drupal VM's Docker image
If you just want a quick, easy Drupal site for testing, you can run an instance of Drupal VM and install Drupal inside using the provided script.
1. Run an instance of Drupal VM: `docker run -d -p 80:80 -p 443:443 --name=drupalvm --privileged geerlingguy/drupal-vm`
2. Install Drupal on this instance: `docker exec drupalvm install-drupal` (you can choose a version using `install-drupal [version]`, using versions like `8.4.x`, `7.55`, `7.x`, etc.).
You should be able to access the Drupal site at `http://localhost`. If you need to share a host directory into the VM, you can do so by adding another `-v` parameter, like `-v /path/on/host:/path/in/container.
If you only need a simple container to run your site, and you want to package up the container configuration with your project, you can add a simple Docker Compose file to your project's docroot like the following:
```yaml
version: "3"
services:
myproject:
image: geerlingguy/drupal-vm
container_name: myproject
ports:
- 80:80
- 443:443
privileged: true
volumes:
- ./:/var/www/drupalvm/drupal/web/:rw,delegated
- /var/lib/mysql
command: /lib/systemd/systemd
```
Then, run `docker-compose up -d` to bring up the container.
For an example use of the simple approach for a contributed module's local development environment, see the Honeypot module, where this approach was added in [Add local test environment configuration](https://www.drupal.org/node/2885488).
If you need more flexibility, though, you use one of the other Docker container methods on this page.
## Method 2: Build a default Drupal VM instance with Docker
The [`geerlingguy/drupal-vm`](https://hub.docker.com/r/geerlingguy/drupal-vm/) image on Docker Hub contains a pre-built copy of Drupal VM, with all the latest Drupal VM defaults. If you need to quickly run your site in a container, or don't need to customize any of the components of Drupal VM, you can use this image.
> For a reference installation that has configuration for running the local environment on _either_ Vagrant or Docker, see the [Drupal VM Live Site Repository](https://github.com/geerlingguy/drupalvm-live).
### (Optional) Add a `Dockerfile` for customization
If you need to make small changes to the official `drupal-vm` image (instead of baking your own fully-custom image), you can create a `Dockerfile` to make those changes. In one site's example, ImageMagick was required for some media handling functionality, and so the following `Dockerfile` was placed in the project's root directory (alongside the `docker-compose.yml` file):
FROM geerlingguy/drupal-vm:latest
LABEL maintainer="Jeff Geerling"
# Install imagemagick.
RUN apt-get install -y imagemagick
EXPOSE 80 443 3306 8025
You can customize the official image in many other ways, but if you end up doing more than a step or two in a `Dockerfile`, it's probably a better idea to 'bake your own' Drupal VM Docker image.
### Add a `docker-compose.yml` file
Copy the `example.docker-compose.yml` file out of Drupal VM (or grab a copy from GitHub [here](https://github.com/geerlingguy/drupal-vm/blob/master/example.docker-compose.yml)), rename it `docker-compose.yml`, and place it in your project root.
- _If you are using your own `Dockerfile` to further customize Drupal VM_, comment out the `image: drupal-vm` line, and uncomment the `build: .` line (this tells Docker Compose to build a new image based on your own `Dockerfile`).
For the `volume:` definition in `docker-compose.yml`, Drupal VM's default docroot is `/var/www/drupalvm/drupal/web`, which follows the convention of a typical Drupal project built with Composer. If you don't get your site when you attempt to access Drupal VM, you will either need to modify the `volume:` definition to match your project's structure, or use a custom `Dockerfile` and copy in a customized Apache `vhosts.conf` file.
You should also add a volume for MySQL data, otherwise MySQL may not start up correctly. By default, you should have a volume for `/var/lib/mysql` (no need to sync it locally). See Drupal VM's example docker-compose file for reference.
### Run Drupal VM
Run the command `docker-compose up -d` (the `-d` tells `docker-compose` to start the containers and run in the background).
This command takes the instructions in the Docker Compose file and does two things:
1. Creates a custom Docker network that exposes Drupal VM on the IP address you have configured in `docker-compose.yml` (by default, `192.168.89.89`).
2. Runs Drupal VM using the configuration in `docker-compose.yml`.
After the Drupal VM container is running, you should be able to see the Dashboard page at the VM's IP address (e.g. `http://192.168.89.89`), and you should be able to access your site at the hostname you have configured in your hosts file (e.g. `http://drupalvm.test/`).
> Note: If you see Drupal's installer appear when accessing the site, that means the codebase was found, but either the database connection details are not in your local site configuration, or they are, but you don't have the default database populated yet. You may need to load in the database either via `drush sql-sync` or by importing a dump into the container. The default credentials are `drupal` and `drupal` for username and password, and `drupal` for the database name.
You can stop the container with `docker-compose stop` (and start it again with `docker-compose start`), or remove all the configuration with `docker-compose down` (warning: this will also wipe out the database and other local container modifications).
### Using Drush inside Docker
Currently, the easiest way to use Drupal VM's `drush` inside a Docker container is to use `docker exec` to run `drush` internally. There are a few other ways you can try to get Drush working with a codebase running on a container, but the easiest way is to run a command like:
docker exec drupal-vm bash -c "drush --uri=drupalvm.test --root=/var/www/drupalvm/drupal/web status"
## Method 3: 'Bake and Share' a custom Drupal VM Docker image
If you need a more customized Drupal VM instance, it's best to build your own with Drupal VM's built-in Docker scripts.
### Building ('baking') a Docker container with Drupal VM
After you've configured your Drupal VM settings in `config.yml` and other configuration files, run the following command to create and provision a new Docker container:
composer docker-bake
This will bake a Docker images using Drupal VM's default settings for distro, IP address, hostname, etc. You can override these options (all are listed in the `provisioning/docker/bake.sh` file) by prepending them to the `composer` command:
DRUPALVM_IP_ADDRESS='192.168.89.89' DISTRO='debian9' composer docker-bake
This process can take some time (it should take a similar amount of time as it takes to build Drupal VM normally, using Vagrant and VirtualBox), and at the end, you should see a message like:
```
PLAY RECAP *********************************************************************
localhost : ok=210 changed=94 unreachable=0 failed=0
...done!
Visit the Drupal VM dashboard: http://192.168.89.89:80
```
Once the build is complete, you can view the dashboard by visiting the URL provided.
### Saving the Docker container to an image
If you are happy with the way the container was built, you can run the following command to convert the container into an image:
composer docker-save-image
You can override the default values for the image creation by overriding the following three variables inside `config.yml`:
docker_container_name: drupal-vm
docker_image_name: drupal-vm
docker_image_path: ~/Downloads
Using the default settings, this command will tag your current version of the container as `drupal-vm:latest` (on your local computer), then store an archive of the image in an archive file, in the path "`docker_image_path`/`docker_image_name`.tar.gz".
### Loading the Docker container from an image
On someone else's computer (or your own, if you have deleted the existing `drupal-vm` image), you can load an archived image by placing it in the path defined by "`docker_image_path`/`docker_image_name`.tar.gz" in your `config.yml` file. To do this, run the command:
composer docker-load-image
### Using a baked Drupal VM image with `docker-compose.yml`
Drupal VM includes an `example.docker-compose.yml` file. To use the file, copy it to `docker-compose.yml` and customize as you see fit, making sure to change the `image` to the value of `docker_image_name` (the default is `drupal-vm`). Once you've configured the exposed ports and settings as you like, run the following command to bring up the network and container(s) according to the compose file:
docker-compose up -d
(The `-d` tells `docker-compose` to start the containers and run in the background.) You can stop the container with `docker-compose stop` (and start it again with `docker-compose start`), or remove all the configuration with `docker-compose down` (warning: this will also wipe out the database and other local container modifications).

4
box/docs/other/drupal-6.md Normal file
View file

@ -0,0 +1,4 @@
If you'd like to use the included configuration and Drush make file to install a Drupal 6 site using an older version of Drush (< 7.x), you may need to make some changes, namely:
1. Drush < 7.x does not support .yml makefiles; if using Drush 5.x or 6.x, you will need to create the make file in the INI-style format.
2. In your customized `config.yml` file, you will need to use the `default` installation profile instead of `standard` (for the `drupal_install_profile` variable).

63
box/docs/other/management-tools.md Normal file
View file

@ -0,0 +1,63 @@
There are some upstream tools which aid in the creation and management of Drupal VM instances. Some of the more popular tools are listed here.
If you know of any other tools to help manage Drupal VM, please add them to this page!
## Lunchbox
[Lunchbox](https://github.com/LunchboxDevTools/lunchbox) is a wrapper for the Drupal VM project to manage your Drupal development process. It is a Node.js-based GUI to assist in setting up Drupal VM and creating and managing instances.
## Acquia BLT
[BLT (Build and Launch Tool)](https://github.com/acquia/blt) is a project from Acquia that builds a Drupal project repository, and can optionally include Drupal VM as part of the project. There is an open PR that may [use Composer to add Drupal VM as a project dependency automatically](https://github.com/acquia/blt/pull/93).
## Drupal VM Config Generator
[Drupal VM Config Generator](https://github.com/opdavies/drupal-vm-config-generator) is a Symfony Console application that manages and customises configuration files for Drupal VM projects.
You can either use the interactive console UI to build configurations, or pass options directly to the `drupalvm-generate` command.
Examples:
```
drupalvm-generate \
--hostname=example.com \
--machine-name=example \
--ip-address=192.168.88.88 \
--cpus=1 \
--memory=512 \
--webserver=nginx \
--domain=example.com \
--path=../site \
--destination=/var/www/site \
--docroot=/var/www/site/drupal \
--drupal-version=8 \
--build-makefile=no \
--install-site=true \
--installed-extras=xdebug,xhprof \
--force
```
## Drupal VM Generator
[generator-drupalvm](https://github.com/kevinquillen/generator-drupalvm) is a Yeoman generator for quickly spawning configured VMs or new projects using Drupal VM.
Examples:
```
# Generate a new Drupal VM instance in the current directory.
$ yo drupalvm
```
## Newd
[`newd`](https://gist.github.com/rgoodie/9966f30b404a4daa59e1) is a bash function that quickly clones the Drupal VM repo wherever you need it, configures important bits, and then kicks off `vagrant up`.
Examples:
```
# Create a new Drupal VM named 'test-fieldformatter' with Drupal 7.
$ newd 7 test-fieldformatter
# Create a new Drupal VM named 'drupal8test' with Drupal 8.
$ newd 8 drupal8test
```

12
box/docs/other/networking.md Normal file
View file

@ -0,0 +1,12 @@
Since Vagrant manages internal network connections for Drupal VM, and since every person's network setup is unique, there are sometimes networking issues that require some adjustments to your Drupal VM configuration or a computer reboot.
## Network Route Collision
Drupal VM comes configured with the default IP address `192.168.88.88`. If you're connected to a LAN with the same private IP address range (e.g. `192.168.x.x`), then VirtualBox or VMware will not be able to set up the VM with the default IP address, because that would conflict with the `192.168.x.x` network your computer is using.
In this case, you have two options:
1. Switch the `vagrant_ip` in `config.yml` to a different private IP address, e.g. `172.16.0.88` or `10.0.1.88`.
2. Install the `vagrant-auto_network` plugin (`vagrant plugin install vagrant-auto_network`), and set the `vagrant_ip` to `0.0.0.0`.
Another cause of route collisions is the use of multiple VM providers on your computer. If you have both VirtualBox and VMware Fusion, and you have VMs running in both, and you attempt to use the same IP range in both providers, you'll hit a networking conflict. In this case, the only easy way to restore connectivity is to restart your host machine.

118
box/docs/other/performance.md Normal file
View file

@ -0,0 +1,118 @@
## 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:
- private
- .git
- web/sites/default/files
- tmp
```
### Mixing synced folder types
You can also mix the synced folder types and use a fast one-way rsync for your primary codebase and then a slower but two-way sync for Drupal's configuration sync directory.
```yaml
vagrant_synced_folders:
- local_path: .
destination: /var/www/drupal
type: rsync
create: true
excluded_paths:
- private
- .git
- web/sites/default/files
- tmp
# Exclude the second synced folder.
- config/drupal
# Use a slower but two-way sync for configuration sync directory.
- local_path: config/drupal
destination: /var/www/drupal/config/drupal
type: "" # Or smb/nfs if available
create: true
```
## 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. **Use PhpStorm or a reverse-mounted synced folder for working from inside the VM.** Read [Drupal VM on Windows - a fast container for BLT project development](https://www.jeffgeerling.com/blog/2017/drupal-vm-on-windows-fast-container-blt-project-development) for instructions and recommendations.
1. **Install the `vagrant-winnfsd` plugin**. See the 'NFS' section later for more details and caveats.
1. **Use `smb` for the synced folder's type.**
1. **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
### Better performance: Sharing from Drupal VM to your PC
The fastest option for Drupal VM is to install the Drupal codebase entirely inside Drupal VM, without using a Vagrant shared folder. This method ensures the code runs as fast as it would if it were natively running on your PC, but it requires some other form of codebase synchronization, and means there is at least a tiny bit of lag between saving files in your editor and seeing the changes inside Drupal VM.
If you use one of these techniques, it's recommended you use the [Git deployment technique](../deployment/git.md) to clone your Drupal codebase into Drupal VM from a Git repository.
#### Syncing files via rsync or SSH
If you use an IDE like PhpStorm, you can configure it to synchronize a local codebase with the code inside Drupal VM using SSH (SFTP). There are also tools that mount directories into Windows Explorer using plain SSH and SFTP, though configuring these tools can be difficult.
If at all possible, make sure your IDE is configured to automatically synchronize changes.
#### Share files using Samba inside Drupal VM
Though it's not supported natively by Vagrant, you can mount a Samba share _from the VM guest_ to your host PC. To do this, you have to:
1. Install Samba inside the VM.
2. Configure Samba (through `smb.conf`) to share a directory inside the VM.
3. Open firewall ports `137`, `138`, `139`, and `445`.
4. Mount the Samba shared folder within Windows Explorer (e.g. visit `\\drupalvm.test\share_name`)
Read this blog post for further detail in creating a Samba share: [Configure a reverse-mounted Samba shared folder](https://www.jeffgeerling.com/blog/2017/drupal-vm-on-windows-fast-container-blt-project-development#reverse-share).

155
box/docs/other/production.md Normal file
View file

@ -0,0 +1,155 @@
Drupal VM supports deploying Drupal VM to a production environment. The security of your servers is _your_ responsibility.
(See companion blog post to this documentation: [Soup to Nuts: Using Drupal VM to build local and prod](https://www.jeffgeerling.com/blog/2017/soup-nuts-using-drupal-vm-build-local-and-prod).)
## Production specific overrides.
Drupal VM supports loading configuration files depending on the environment variable `DRUPALVM_ENV` and using this feature you can have different configurations between development and production environments.
```sh
# Loads vagrant.config.yml if available (default).
vagrant provision
# Loads prod.config.yml if available.
DRUPALVM_ENV=prod vagrant provision --provisioner=aws
```
If you're issuing a provision directly through `ansible-playbook` as you would do for most production environments you can either set the `DRUPALVM_ENV` variable on your host, or on the remote production machine.
```sh
# By default it doesn't try to load any other config file.
ansible-playbook -i examples/prod/inventory provisioning/playbook.yml --become --ask-become-pass
# Loads prod.config.yml if available.
DRUPALVM_ENV=prod ansible-playbook -i examples/prod/inventory provisioning/playbook.yml --become --ask-become-pass
```
If you add `DRUPALVM_ENV=prod` to the `/etc/environment` file on your production environment:
```sh
# Loads prod.config.yml if available.
ansible-playbook -i examples/prod/inventory provisioning/playbook.yml --become --ask-become-pass
```
_Note: Having the variable set locally takes precedence over having it on the remote machine._
As a precaution not to accidentally provision a production server with insecure configurations, you should set your security hardening configurations in `config.yml`, your local development overrides in `vagrant.config.yml` and finally any additional production specific overrides in `prod.config.yml`. This way, a production environment will never be provisioned with development tools, even if the `prod.config.yml` is not read.
## Ansible Vault support
Drupal VM will include a `secrets.yml` file included in your VM's configuration directory (alongside `config.yml`, `local.config.yml`, etc.) that you can use to store sensitive variables (e.g. MySQL's root password, Drupal's admin password). For extra security, you can encrypt this file, and require a password whenever the variable is used.
First, you'd create an Ansible Vault encrypted file:
$ ansible-vault create secrets.yml
Create the file inside your VM's configuration directory, add any plaintext passwords, and save it. Ansible Vault will encrypt the file, and you can edit the file using `ansible-vault edit`.
When running `vagrant` commands, make sure you tell the Ansible provisioner to use `--ask-vault-pass`, e.g.:
DRUPALVM_ANSIBLE_ARGS='--ask-vault-pass' vagrant [command]
And if you need to override one of the secrets stored in that file, you can do so through an environment-specific config file, for example:
vagrant.config.yml
prod.config.yml
[etc.]
## Example: Drupal VM on DigitalOcean
The [`examples/prod` directory](https://github.com/geerlingguy/drupal-vm/tree/master/examples/prod) contains an example production configuration for Drupal VM which can be used to deploy Drupal VM to a production environment on a cloud provider like DigitalOcean, Linode, or AWS.
This guide contains instructions for how you can build a Drupal environment with Drupal VM on DigitalOcean.
### Create a DigitalOcean Droplet
If you don't already have a DigitalOcean account, create one (you can use geerlingguy's [affiliate link](https://www.digitalocean.com/?refcode=b9c57af84643) to sign up, otherwise, visit the normal [DigitalOcean Sign Up form](https://cloud.digitalocean.com/registrations/new).
Make sure you have an SSH key you can use to connect to your DigitalOcean droplets, and if you don't already have one set up, or if you need to add your existing key to your account, follow the instructions in this guide: [How to use SSH keys with DigitalOcean Droplets](https://www.digitalocean.com/community/tutorials/how-to-use-ssh-keys-with-digitalocean-droplets).
Once you are logged into DigitalOcean and have added your SSH key, click the 'Create Droplet' button on your Droplets page. For the Droplet, choose the following options:
- **Image**: Choose `Ubuntu 16.04.x x64`
- **Size**: 1 GB / 1 CPU (currently $10/month; you can choose a higher plan if needed)
- **Region**: Choose whatever region is geographically nearest to you and your site visitors
- **Settings**: (Nothing here affects how Drupal VM works, choose what you'd like)
- **Add SSH Keys**: Select the SSH key you added to your account earlier.
- **Hostname**: Choose a hostname for your site (e.g. `example.drupalvm.com`)
Click 'Create Droplet', and wait a minute or so while the Droplet is booted. Once it's booted, make sure you can log into it from your local computer:
ssh root@[droplet-hostname-or-ip]
(Make sure you replace `[droplet-hostname-or-ip]`) with the hostname or IP address of your Droplet!)
If you get a warning like "the authenticity of the host can't be established", answer yes to the prompt and hit enter. You should now be logged into the Droplet. Log back out by typing `exit` at the prompt and hitting return.
Your DigitalOcean Droplet is booted and ready to have Drupal VM installed on it.
### Customize `config.yml` for production
Copy [`examples/prod/prod.config.yml`](https://github.com/geerlingguy/drupal-vm/blob/master/examples/prod/prod.config.yml) to `config.yml`, and by looking at `default.config.yml` add any other overrides you'd like. Whatever variables you have set in `config.yml` will override the defaults set by `default.config.yml`.
The changes outlined in the [example `prod.config.yml`](https://github.com/geerlingguy/drupal-vm/blob/master/examples/prod/prod.config.yml) disable development-environment tools (like Pimp My Log and Adminer) and add extra security hardening configuration (via the `extra_security_enabled` variable).
You now have Drupal VM configured for production by default. This is the recommended and safest way, so that you can't accidentally provision a production server with development tools. If desired you can also use the [environment variable `DRUPALVM_ENV`](#production-specific-overrides) to load an additional `<ENV>.config.yml` with production specific overrides. In most cases this is not needed though.
### 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`. Read about how configuration files are read under [Configuring Drupal VM](../getting-started/configure-drupalvm.md)
### Customize `inventory` for production
The only other thing you need to do is copy the inventory file `example.inventory` to `inventory` (so it is located at `prod/inventory`). By default, it reads:
[drupalvm]
1.2.3.4 ansible_ssh_user=my_admin_username
Change the host `1.2.3.4` to either the IP address or the hostname of your DigitalOcean Droplet. Remember that if you would like to use a hostname, you need to make sure the hostname actually resolves to your Droplet's IP address, either in your domain's public DNS configuration, or via your local hosts file.
### Initialize the server with an administrative account
> Note: This guide assumes you have Ansible [installed](http://docs.ansible.com/ansible/intro_installation.html) on your host machine.
The first step in setting up Drupal VM on the cloud server is to initialize the server with an administrative account (which is separate from the `root` user account for better security).
Inside the `examples/prod/bootstrap` folder, copy the `example.vars.yml` file to `vars.yml` and update the variables in that file for your own administrative account (make sure especially to update the `admin_password` value!).
Then, run the following command within Drupal VM's root directory (the folder containing the `Vagrantfile`):
ansible-playbook -i examples/prod/inventory examples/prod/bootstrap/init.yml -e "ansible_ssh_user=root"
Once the initialization is complete, you can test your new admin login with `ssh my_admin_username@droplet-hostname-or-ip`. You should be logged in via your existing SSH key. Log back out with `exit`.
### Provision Drupal VM on the Droplet
Run the following command within Drupal VM's root directory (the folder containing the `Vagrantfile`):
DRUPALVM_ENV=prod ansible-playbook -i examples/prod/inventory provisioning/playbook.yml --become --ask-become-pass
_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._
DRUPALVM_ENV=prod ansible-playbook -i config/prod/inventory vendor/geerlingguy/drupal-vm/provisioning/playbook.yml -e "config_dir=$(pwd)/config" --become --ask-become-pass
Ansible will prompt you for your admin account's `sudo` password (the same as the password you encrypted and saved as `admin_password`). Enter it and press return.
After a few minutes, your Drupal-VM-in-the-cloud Droplet should be fully configured to match your local development environment! You can visit your Droplet and access the fresh Drupal site just like you would locally (e.g. `http://example.drupalvm.com/`).
### Known issues
- You may need to manually create the `drupal_core_path` directory on the server at this time; it's not always created automatically due to permissions errors.
- The `files` folder that is generated during the initial Drupal installation is set to be owned by the admin account; to make it work (and to allow Drupal to generate stylesheets and files correctly), you have to manually log into the server and run the following two commands after provisioning is complete:
```
$ sudo chown -R www-data /var/www/drupalvm/drupal/sites/default/files
$ sudo chmod -R 0700 /var/www/drupalvm/drupal/sites/default/files
```
- You can't synchronize folders between your host machine and DigitalOcean (at least not in any sane way); so you'll need to either have Drupal VM install a site from a given Drush make file or composer.json, or deploy the site via Git, using the `geerlingguy.drupal` role's git deployment options.
- Drupal VM doesn't include any kind of backup system. You should use one if you have any kind of important data on your server!
### Go Further
You can use Ubuntu 14.04, Ubuntu 16.04, Debian 8, CentOS 6 or CentOS 7 when you build the DigitalOcean Droplet. Just like with Drupal VM running locally, you can customize almost every aspect of the server!
You may want to customize your configuration even further, to make sure Drupal VM is tuned for your specific Drupal site's needs, or you may want to change things and make the server configuration more flexible, etc. For all that, the book [Ansible for DevOps](http://ansiblefordevops.com/) will give you a great introduction to using Ansible to make Drupal VM and the included Ansible configuration do exactly what you need!

41
box/docs/other/vagrant-lxc.md Normal file
View file

@ -0,0 +1,41 @@
[`vagrant-lxc` is a Vagrant plugin](https://github.com/fgrehm/vagrant-lxc) that provisions Linux Containers (LXC) rather than VM's such as VirtualBox or VMWare. Although LXC has much better performance, it only works on Linux hosts, and it isn't as well supported or tested by Drupal VM.
### Install dependencies
sudo apt-get install lxc bridge-utils
vagrant plugin install vagrant-lxc
### Load required kernel modules
As containers can't load modules, but inherit them from the host, you need to load these on your host machine.
sudo modprobe iptable_filter
sudo modprobe ip6table_filter
To load these automatically when you boot up your system, you should check the guidelines of your specific distribution. Usually you add them to `/etc/modules` or `/etc/modules-load.d/*`
### Create a [`Vagrantfile.local`](../extending/vagrantfile.md)
config.vm.networks[0][1][:lxc__bridge_name] = 'vlxcbr1'
config.vm.provider :lxc do |lxc|
lxc.customize 'cgroup.memory.limit_in_bytes', "#{vconfig['vagrant_memory']}M"
end
Read more about how to configure the container in [`vagrant-lxc`'s README.md](https://github.com/fgrehm/vagrant-lxc#readme).
### Modify your `config.yml`
The following boxes have been tested only minimally, choose which one you want.
# Centos 7
vagrant_box: frensjan/centos-7-64-lxc
# Ubuntu 16.04
vagrant_box: nhinds/xenial64
# Do not interact with the UFW service on Ubuntu.
drupalvm_disable_ufw_firewall: false
### Provision the Container
vagrant up --provider=lxc

107
box/docs/other/wordpress-other-applications.md Normal file
View file

@ -0,0 +1,107 @@
While Drupal VM caters specifically to Drupal, and support for and compatibility with other PHP applications isn't guaranteed, Drupal VM is flexible enough to work with PHP applications besides Drupal.
## Wordpress
To integrate Drupal VM with an existing Wordpress project such as [bedrock](https://github.com/roots/bedrock), follow the documentation on using [Drupal VM as a Composer dependency](http://docs.drupalvm.com/en/latest/deployment/composer-dependency/).
Begin by forking/cloning `bedrock` as a boilerplate for your application, and require Drupal VM as a development dependency.
```yaml
composer require --dev geerlingguy/drupal-vm
```
Configure the VM by creating a `config/config.yml`:
```yaml
vagrant_hostname: bedrock.dev
vagrant_machine_name: bedrock
vagrant_synced_folders:
- local_path: .
destination: /var/www/wordpress
type: nfs
create: true
# Needs to match with what we have in .env and vagrant_synced_folders.
drupal_core_path: "/var/www/wordpress/web"
drupal_domain: "{{ vagrant_hostname }}"
drupal_db_user: wordpress
drupal_db_password: wordpress
drupal_db_name: wordpress
# Disable Drupal specific features.
drupal_build_composer_project: false
drupal_install_site: false
configure_drush_aliases: false
# Remove some Drupal extras such as `drupalconsole` and `drush`
installed_extras:
- adminer
- mailhog
- pimpmylog
# Add wp-cli
composer_global_packages:
- { name: hirak/prestissimo, release: '^0.3' }
- { name: wp-cli/wp-cli, release: '^1.0.0' }
```
Create the delegating `Vagrantfile` in the root of the project:
```rb
# The absolute path to the root directory of the project. Both Drupal VM and
# the config file need to be contained within this path.
ENV['DRUPALVM_PROJECT_ROOT'] = "#{__dir__}"
# The relative path from the project root to the config directory where you
# placed your config.yml file.
ENV['DRUPALVM_CONFIG_DIR'] = "config"
# The relative path from the project root to the directory where Drupal VM is located.
ENV['DRUPALVM_DIR'] = "vendor/geerlingguy/drupal-vm"
# Load the real Vagrantfile
load "#{__dir__}/#{ENV['DRUPALVM_DIR']}/Vagrantfile"
```
Edit your `.env` file to match the values you set in `config/config.yml`:
```
DB_NAME=wordpress
DB_USER=wordpress
DB_PASSWORD=wordpress
DB_HOST=localhost
WP_ENV=development
WP_HOME=http://bedrock.dev
WP_SITEURL=${WP_HOME}/wp
```
Ignore local Drupal VM configuration files by adding the following to your `.gitignore`:
```
Vagrantfile.local
config/local.config.yml
```
Add a wp-cli `@dev` alias that points to the VM by editing the `wp-cli.yml` file:
```yaml
path: web/wp
@dev:
ssh: vagrant@bedrock.dev/var/www/wordpress/web/wp
url: bedrock.dev
```
For passwordless login with `wp-cli` add the following to your SSH config `~/.ssh/config`:
```
Host bedrock.dev
StrictHostKeyChecking no
IdentityFile ~/.vagrant.d/insecure_private_key
```
Provision the VM and import your database.
```sh
vagrant up
```