RailsBridge Virtual Machine
If you just want the VM image, downloads are here: http://downloads.railsbridge.org/
To workshop participants: this is the "behind the scenes" stuff that instructors use to create the virtual machine that you will use. You should install the virtual machine image file, not this code. Please follow the instructions on the RailsBridge Boston site to set up your virtual machine.
To instructors and TAs: if you're interested in helping to maintain the VM, keep reading.
Setup of the generated VM
The base box is Ubuntu 16.04 LTS 32-bit; Ubuntu distributes version 5.0 of the VirtualBox guest additions (which work with VirtualBox 5.2). We should have students install the latest compatible version of the VirtualBox host.
The target versions are Ruby 2.5 and Rails 5.1 (the latest patchlevels available at build time). These are set in
provision-files/versions.sh, which is used by the provisioning scripts.
chruby to build/install Ruby, and invoke it in the user's
.bash_profile to set their
PATH. It provides a version of
gem that defaults to user installs.
Building a fresh image
If this is not your first time building a VM, make sure you have cleaned up any old versions of the Ubuntu base image with
vagrant box prune before continuing.
- Oracle VirtualBox - https://www.virtualbox.org - Last tested on v5.2.8
- HashiCorp Vagrant - https://www.vagrantup.com - Last tested on v2.0.3
- Ruby - https://www.ruby-lang.org/en/ - Last tested on v2.5.0
Download and install VirtualBox and Vagrant to your local machine. Installers for all platforms are available at the sites above, however these steps were only validated using macOS High Sierra.
There are a few simple Rake tasks to help you rebuild the image from scratch. Run:
This will update the base box if you've downloaded it previously, then run
vagrant up to provision the VM. (If you haven't downloaded the base box, Vagrant will fetch it automatically.)
Don't worry about the red text (Vagrant automatically colors all text printed to standard error). Building Ruby takes a while, so get some coffee.
When the provision finishes, run this to create an image file to distribute:
This will output an image file name
railsbridgevm-version.box, where the
version is based on the tag you have checked out.
Finally, when you're ready to make a change and build again, run:
To halt and destroy the VM, so that the next
vagrant up run has to re-provision it.
When you are ready to make the "gold master" version that we will ask students to download, create (and push to GitHub) a tag with the year and month of the workshop (e.g.
2014-01) before running
rake package. During the process of testing an image, you can run
rake package with an untagged commit; the version will then include its SHA and how many commits it is ahead of the last tag.
What to edit in this repo
To keep things simple and easy for everyone to modify, we use a shell script provisioner. There are three scripts:
provision-root-install.shruns as root (installs packages/Ruby system-wide)
provision-user-install.shruns as the
vagrantuser (installs gems to home directory)
provision-root-cleanup.shruns as root (removes files and zeroes out disk)
We also run the Heroku Toolbelt install script directly as root.
Files are copied into the VM from the
provision-files directory (
/etc as root,
/home/vagrant as the user account).
If you make changes to the provisioning scripts, you should rebuild the VM from a clean image to ensure that everything is reproducible and that no manual changes have snuck in. To do this, run
vagrant destroy and then
vagrant up again.
It will re-run everything again, so grab some more coffee.
Using the VM
There are a few extra scripts in the VM that you can use during the workshop:
railsbridge-update-dotfileswill download and re-install all dotfiles from this repo (useful if they are mistakenly edited or deleted).
railsbridge-color offwill disable coloring of shell and IRB prompts (log out and back in to see the change). To re-enable color, run
showargscan be used to explain how command-line arguments work.
vagrantprints a message explaining that you're in the VM and should exit if you want to run a Vagrant command.
Some files are not installed in the VM:
vm.rb: this is a Rails application template that students can apply to their app so that they don't have to pass
rails server. Copy it to the downloads site alongside the VM images, and have students apply it with
rake rails:template LOCATION=http://downloads.railsbridge.org/vm.rb.
TODO: There should be some kind of automated test for the output (i.e. can you start the VM, log in, clone a test Rails app, and run it).