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
This commit is contained in:
Joel Challis 2019-07-16 09:20:34 +01:00 committed by skullydazed
parent a32f7e1a25
commit 29e9caa82b
4 changed files with 107 additions and 15 deletions

31
Vagrantfile vendored
View file

@ -52,26 +52,37 @@ Vagrant.configure(2) do |config|
end end
# Docker provider pulls from hub.docker.com respecting docker.image if # 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 # /vagrant in the guest, so unless your UID is 1000 to match vagrant in the
# image, you'll need to: chmod -R a+rw . # image, you'll need to: chmod -R a+rw .
config.vm.provider "docker" do |docker, override| config.vm.provider "docker" do |docker, override|
override.vm.box = nil override.vm.box = nil
docker.image = "jesselang/debian-vagrant:stretch" docker.build_dir = "util/vagrant"
docker.has_ssh = true docker.has_ssh = true
end end
# This script ensures the required packages for AVR programming are installed # Unless we are running the docker container directly
# It also ensures the system always gets the latest updates when powered on # 1. run container detached on vm
# If this causes issues you can run a 'vagrant destroy' and then # 2. attach on 'vagrant ssh'
# add a # before ,run: (or change "always" to "once") and run 'vagrant up' to get a working ["virtualbox", "vmware_workstation", "vmware_fusion"].each do |type|
# non-updated box and then attempt to troubleshoot or open a Github issue config.vm.provider type do |virt, override|
config.vm.provision "shell", inline: "/vagrant/util/qmk_install.sh", run: "always" 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 config.vm.post_up_message = <<-EOT
Log into the VM using 'vagrant ssh'. QMK directory synchronized with host is Log into the environment using 'vagrant ssh'. QMK directory synchronized with
located at /vagrant host is located at /vagrant
To compile the .hex files use make command inside this directory, e.g. To compile the .hex files use make command inside this directory, e.g.
cd /vagrant cd /vagrant
make <keyboard>:default make <keyboard>:default

View file

@ -1,16 +1,20 @@
# Vagrant Quick Start # 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 ## 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: 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) * [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. 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'
```

33
util/vagrant/Dockerfile Normal file
View file

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

12
util/vagrant/readme.md Normal file
View file

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