varl/qmk_firmware
1
0
Fork 0
forked from forks/qmk_firmware
Code Pull requests Activity

Configure Vagrant to use qmk_base_container (#6194)

Browse source 
* 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
Show stats Download patch file Download diff file Expand all files Collapse all files

31
Vagrantfile vendored
View file

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

46
docs/getting_started_vagrant.md
View file

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

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