4 files changed, 107 insertions, 15 deletions
diff --git a/Vagrantfile b/Vagrantfile
index 552711d632..dae4e0d53d 100644
--- a/Vagrantfile
+++ b/Vagrantfile
@@ -52,26 +52,37 @@ Vagrant.configure(2) do |config|
   end
 
   # Docker provider pulls from hub.docker.com respecting docker.image if
-  # config.vm.box is nil. Note that this bind-mounts from the current dir to
+  # config.vm.box is nil. In this case, we adhoc build util/vagrant/Dockerfile.
+  # Note that this bind-mounts from the current dir to
   # /vagrant in the guest, so unless your UID is 1000 to match vagrant in the
   # image, you'll need to: chmod -R a+rw .
   config.vm.provider "docker" do |docker, override|
     override.vm.box = nil
-    docker.image = "jesselang/debian-vagrant:stretch"
+    docker.build_dir = "util/vagrant"
     docker.has_ssh = true
   end
 
-  # This script ensures the required packages for AVR programming are installed
-  # It also ensures the system always gets the latest updates when powered on
-  # If this causes issues you can run a 'vagrant destroy' and then
-  # add a # before ,run: (or change "always" to "once") and run 'vagrant up' to get a working
-  # non-updated box and then attempt to troubleshoot or open a Github issue
-  config.vm.provision "shell", inline: "/vagrant/util/qmk_install.sh", run: "always"
+  # Unless we are running the docker container directly
+  #   1. run container detached on vm
+  #   2. attach on 'vagrant ssh'
+  ["virtualbox", "vmware_workstation", "vmware_fusion"].each do |type|
+    config.vm.provider type do |virt, override|
+      override.vm.provision "docker" do |d|
+        d.run "qmkfm/base_container",
+          cmd: "tail -f /dev/null",
+          args: "--privileged -v /dev:/dev -v '/vagrant:/vagrant'"
+      end
+
+      override.vm.provision "shell", inline: <<-SHELL
+        echo 'docker restart qmkfm-base_container && exec docker exec -it qmkfm-base_container /bin/bash -l' >> ~vagrant/.bashrc
+      SHELL
+    end
+  end
 
   config.vm.post_up_message = <<-EOT
 
-  Log into the VM using 'vagrant ssh'. QMK directory synchronized with host is
-  located at /vagrant
+  Log into the environment using 'vagrant ssh'. QMK directory synchronized with
+  host is located at /vagrant
   To compile the .hex files use make command inside this directory, e.g.
      cd /vagrant
      make <keyboard>:default
diff --git a/docs/getting_started_vagrant.md b/docs/getting_started_vagrant.md
index 848a43a1f9..b62524271c 100644
--- a/docs/getting_started_vagrant.md
+++ b/docs/getting_started_vagrant.md
@@ -1,16 +1,20 @@
 # Vagrant Quick Start
 
-This project includes a Vagrantfile that will allow you to build a new firmware for your keyboard very easily without major changes to your primary operating system. This also ensures that when you clone the project and perform a build, you have the exact same environment as anyone else using the Vagrantfile to build. This makes it much easier for people to help you troubleshoot any issues you encounter.
+This project includes a `Vagrantfile` that will allow you to build a new firmware for your keyboard very easily without major changes to your primary operating system. This also ensures that when you clone the project and perform a build, you have the exact same environment as anyone else using the Vagrantfile to build. This makes it much easier for people to help you troubleshoot any issues you encounter.
 
 ## Requirements
 
-Using the `/Vagrantfile` in this repository requires you have [Vagrant](http://www.vagrantup.com/) as well as [VirtualBox](https://www.virtualbox.org/) (or [VMware Workstation](https://www.vmware.com/products/workstation) and [Vagrant VMware plugin](http://www.vagrantup.com/vmware) but the (paid) VMware plugin requires a licensed copy of VMware Workstation/Fusion).
+Using the `Vagrantfile` in this repository requires you have [Vagrant](http://www.vagrantup.com/) as well as a supported provider installed:
 
-*COMPATIBILITY NOTICE* Certain versions of Virtualbox 5 appear to have an incompatibility with the Virtualbox extensions installed in the boxes in this Vagrantfile. If you encounter any issues with the /vagrant mount not succeeding, please upgrade your version of Virtualbox to at least 5.0.12. **Alternately, you can try running the following command:** `vagrant plugin install vagrant-vbguest`
+* [VirtualBox](https://www.virtualbox.org/) (Version at least 5.0.12)
+  * Sold as 'the most accessible platform to use Vagrant'
+* [VMware Workstation](https://www.vmware.com/products/workstation) and [Vagrant VMware plugin](http://www.vagrantup.com/vmware)
+  * The (paid) VMware plugin requires a licensed copy of VMware Workstation/Fusion
+* [Docker](https://www.docker.com/)
 
-Other than having Vagrant and Virtualbox installed and possibly a restart of your computer afterwards, you can simple run a 'vagrant up' anywhere inside the folder where you checked out this project and it will start a Linux virtual machine that contains all the tools required to build this project. There is a post Vagrant startup hint that will get you off on the right foot, otherwise you can also reference the build documentation below.
+Other than having Vagrant, a suitable provider installed and possibly a restart of your computer afterwards, you can simple run a 'vagrant up' anywhere inside the folder where you checked out this project and it will start an environment (either a virtual machine or container) that contains all the tools required to build this project. There is a post Vagrant startup hint that will get you off on the right foot, otherwise you can also reference the build documentation below.
 
-# Flashing the Firmware
+## Flashing the Firmware
 
 The "easy" way to flash the firmware is using a tool from your host OS:
 
@@ -19,3 +23,35 @@ The "easy" way to flash the firmware is using a tool from your host OS:
 * [Atmel FLIP](http://www.atmel.com/tools/flip.aspx)
 
 If you want to program via the command line you can uncomment the ['modifyvm'] lines in the Vagrantfile to enable the USB passthrough into Linux and then program using the command line tools like dfu-util/dfu-programmer or you can install the Teensy CLI version.
+
+## Vagrantfile Overview
+The development environment is configured to run the QMK Docker image, `qmkfm/base_container`. This not only ensures predictability between systems, it also mirrors the CI environment.
+
+## FAQ
+
+### Why am I seeing issues under Virtualbox?
+Certain versions of Virtualbox 5 appear to have an incompatibility with the Virtualbox extensions installed in the boxes in this Vagrantfile. If you encounter any issues with the /vagrant mount not succeeding, please upgrade your version of Virtualbox to at least 5.0.12. **Alternately, you can try running the following command:**
+
+```console
+vagrant plugin install vagrant-vbguest
+```
+
+### How do I remove an existing environment?
+Finished with your environment? From anywhere inside the folder where you checked out this project, Execute:
+
+```console
+vagrant destory
+```
+
+### What if I want to use Docker directly?
+Want to benefit from the Vagrant workflow without a virtual machine? The Vagrantfile is configured to bypass running a virtual machine, and run the container directly. Execute the following when bringing up the environment to force the use of Docker:
+```console
+vagrant up --provider=docker
+```
+
+### How do I access the virtual machine instead of the Docker container?
+Execute the following to bypass the `vagrant` user booting directly to the official qmk builder image:
+
+```console
+vagrant ssh -c 'sudo -i'
+```
+\ No newline at end of file
diff --git a/util/vagrant/Dockerfile b/util/vagrant/Dockerfile
new file mode 100644
index 0000000000..1936ee023a
--- /dev/null
+++ b/util/vagrant/Dockerfile
@@ -0,0 +1,33 @@
+FROM qmkfm/base_container
+
+# Basic upgrades; install sudo and SSH.
+RUN apt-get update && apt-get install --no-install-recommends -y \
+        sudo \
+        openssh-server \
+    && rm -rf /var/lib/apt/lists/*
+RUN mkdir /var/run/sshd
+RUN sed -i 's/PermitRootLogin yes/PermitRootLogin no/' /etc/ssh/sshd_config
+RUN echo 'UseDNS no' >> /etc/ssh/sshd_config
+
+# Remove the policy file once we're finished installing software.
+# This allows invoke-rc.d and friends to work as expected.
+RUN rm /usr/sbin/policy-rc.d
+
+# Add the Vagrant user and necessary passwords.
+RUN groupadd vagrant
+RUN useradd -c "Vagrant" -g vagrant -d /home/vagrant -m -s /bin/bash vagrant
+RUN echo 'root:vagrant' | chpasswd
+RUN echo 'vagrant:vagrant' | chpasswd
+
+# Allow the vagrant user to use sudo without a password.
+RUN echo 'vagrant ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/vagrant
+
+# Install Vagrant's insecure public key so provisioning and 'vagrant ssh' work.
+RUN mkdir /home/vagrant/.ssh
+ADD https://raw.githubusercontent.com/mitchellh/vagrant/master/keys/vagrant.pub /home/vagrant/.ssh/authorized_keys
+RUN chmod 0600 /home/vagrant/.ssh/authorized_keys
+RUN chown -R vagrant:vagrant /home/vagrant/.ssh
+RUN chmod 0700 /home/vagrant/.ssh
+
+EXPOSE 22
+CMD ["/usr/sbin/sshd", "-D"]
diff --git a/util/vagrant/readme.md b/util/vagrant/readme.md
new file mode 100644
index 0000000000..e4b870a642
--- /dev/null
+++ b/util/vagrant/readme.md
@@ -0,0 +1,12 @@
+# QMK Vagrant Utilities
+
+## Dockerfile
+Vagrant-friendly `qmkfm/base_container`.
+
+In order for the Docker provider and `vagrant ssh` to function the container has a few extra requirements.
+
+* vagrant user
+* ssh server
+  * configured with expected public key
+* sudo
+  * passwordless for vagrant user