aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorGravatar Joel Challis <git@zvecr.com>2019-07-16 09:20:34 +0100
committerGravatar skullydazed <skullydazed@users.noreply.github.com>2019-07-16 01:20:34 -0700
commit29e9caa82bdfe898dd7fca82fcecf0cae2374859 (patch)
treead65f691513580f926465959b5a1169365c77959 /docs
parenta32f7e1a25a8a200d838aa8256ffe39708fbd723 (diff)
downloadqmk_firmware-29e9caa82bdfe898dd7fca82fcecf0cae2374859.tar.gz
Configure Vagrant to use qmk_base_container (#6194)
* Initial conversion of vagrant to use qmkfm/base_container * Fix vagrant when using docker provider * Workaround for VirtualBox VM restarts * Generalise Vagrant docs slightly and add FAQ
Diffstat (limited to 'docs')
-rw-r--r--docs/getting_started_vagrant.md46
1 files changed, 41 insertions, 5 deletions
diff --git a/docs/getting_started_vagrant.md b/docs/getting_started_vagrant.md
index 848a43a1f..b62524271 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