Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Configure Vagrant to use qmk_base_container #6194

Merged
merged 4 commits into from
Jul 16, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 21 additions & 10 deletions Vagrantfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
46 changes: 41 additions & 5 deletions docs/getting_started_vagrant.md
Original file line number Diff line number Diff line change
@@ -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:

Expand All @@ -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 changes: 33 additions & 0 deletions util/vagrant/Dockerfile
Original file line number Diff line number Diff line change
@@ -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 changes: 12 additions & 0 deletions util/vagrant/readme.md
Original file line number Diff line number Diff line change
@@ -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