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

box/docs/other/acquia.md

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

box/docs/other/bigpipe.md

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

box/docs/other/docker.md

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

box/docs/other/drupal-6.md

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

box/docs/other/management-tools.md

@@ -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
+```

box/docs/other/networking.md

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

box/docs/other/performance.md

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

box/docs/other/production.md

@@ -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!

box/docs/other/vagrant-lxc.md

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

box/docs/other/wordpress-other-applications.md

@@ -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
+```