qmk

Unnamed repository; edit this file 'description' to name the repository.
git clone git://git.z3bra.org/qmk.git
Log | Files | Refs | Submodules | LICENSE

commit 29e9caa82bdfe898dd7fca82fcecf0cae2374859
parent a32f7e1a25a8a200d838aa8256ffe39708fbd723
Author: Joel Challis <git@zvecr.com>
Date:   Tue, 16 Jul 2019 09:20:34 +0100

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:
Vagrantfile | 31+++++++++++++++++++++----------
docs/getting_started_vagrant.md | 47++++++++++++++++++++++++++++++++++++++++++-----
util/vagrant/Dockerfile | 33+++++++++++++++++++++++++++++++++
util/vagrant/readme.md | 12++++++++++++
4 files changed, 108 insertions(+), 15 deletions(-)

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