Bookware: VM instructions


Options for getting and using the bookware

You have a number of different options for setting up the software for use with the textbook or in a SaaS course:
  1. Run the VM image within VirtualBox on your own computer:
    • This is the recommended approach and the most straightforward. It involves installing the free VirtualBox software (for Intel-based Macs, Windows PCs, or Linux computers) and downloading the SaaS course Virtual Machine image to use within it.
    • This option is completely free, thanks to support from edX for hosting the image file.  (Google and Microsoft supported this previously…thank you for helping us launch!)
    • The instructions on the rest of this page will walk you through this option.
  2. Use Amazon Elastic Compute Cloud to deploy the VM image in the cloud:
    • Use this option if, for example, you don’t have a computer with enough spare capacity to run the VirtualBox option.
    • The Amazon Web Services Free Tier gives you 1 year of access to a Micro instance, which is sufficient to do the coursework, but may be sluggish. 
    • You can pay per hour (from $0.03 and up) to get a dedicated Small instance, which would be faster. To use this option you must have your own Amazon Web Services account.
    • If you are using this book in a course, your instructor may be able to get a donation of AWS educational credits from Amazon and allocate some of those to you.  (We have no connection to Amazon and cannot secure donations for you.)  Note that the Kindle edition of the textbook now comes with a free $10 of AWS credit.
      Follow these instructions to deploy the VM image on Amazon EC2.  (Thanks to MOOC student Jeremy Banks for providing the detailed procedure and screenshots.)
  3. Install the SaaS course software on an existing Ubuntu system:
    • Start from a free "bare bones" Ubuntu image and run our setup script to install all the courseware. There's no point-and-click here—you must be comfortable using Unix command-line utilities and troubleshooting the error messages that might appear. The setup script is in the GitHub saasbook/courseware repo and is tagged with the version number of the earliest book version with which it's been tested.
    • One interesting possibility is to use vagrant to create a blank ubuntu instance on which to install the courseware.
  4. Use a cloud hosted editor system such as Cloud9 or Nitrous (not 100% tested)
    • In the past some students have managed to complete the homeworks using cloud hosted editors such as Cloud9 or Nitrous.  We have yet to thoroughly test these alternatives.

Which version of the VM should I use?

Book version VM image to download and deploy on VirtualBox hypervisor) Amazon AMI ID (see instructions below)  Notes/Errata
1.1.1 - 0.10.3  saasbook-0.10.3.1.zip ami-db655cb2 (Region: us-east-1, N. Virginia)
ami-803c5fb0 (Region: us-west-2, Oregon)
Coming Soon: 1-click Amazon CloudFormation setup
New gem themoviedb replaces ruby-tmdb;  rspec-rails gem added to install; cucumber-rails-training-wheels gem reinstated
 0.10.0 - 0.10.2 (Second Beta Edition)

 saasbook-0.10.3.1.zip

ami-b97b2cd0 (Region: us-east-1, N.Virginia)

Update to Ruby 1.9.3, Rails 3.2.16, many new gems, libraries and tools that are introduced in book version 0.10.0 and later


Option 1: Run the VM image within VirtualBox on your own computer

  1. Download and install the free VirtualBox on your host computer, which can be any Intel-based Mac, Windows PC, or Linux box
  2. Download and unzip the VM image (~2GB zipped) from the links in the table at the top of this page. If you encounter problems unzipping the VM (default unzip software may not be sufficient on older operating systems), 7zip is a free unzip program.
  3. Run VirtualBox and click the New button to create a new VM.
  4. When the VM Wizard appears, select the following options:
    • operating system: Linux
    • version: Ubuntu
    • RAM base memory: at least 1024 MB
    • Select "Use existing hard disk" and choose the .vdi file you downloaded in step 2
  5. This screencast explains how to set up, boot and log in to the VM. Note: Please ensure to run 'bundle install' before running 'rails server'
  6. Make sure you have network access by opening the Firefox browser (icon located along left screen edge when VM is running) and visiting a popular site such as Google.com. Here is troubleshooting information if you have networking issues.
  7. Highly recommended: enable Shared Folders and Copy/Paste, which allows you to view and edit files residing in the VM image using an editor on your host computer and to copy and paste text between the VM and your host computer (That this will work, you need to install VM Guest Additions):
    • In VirtualBox, choose Devices > Insert Guest Additions CD image…
On the popup window click Run button, after that give the password (saasbook) and click on the Authenticate button.
    • In VirtualBox, choose Devices > Shared Clipboard > Bidirectional
      This will allow you to do copy and paste between your host computer and the virtual machine. However, if you’re copying from or pasting to a terminal window within the VM then you should use Ctrl+Shift-C, Ctrl+Shift-V instead of the more usual Ctrl-C and Ctrl-V
A typical work session using the VirtualBox VM proceeds as follows:
  1. Start VirtualBox, select the saasbook VM, and click the Start button.
  2. Do your work.
  3. When you're ready to quit, select Close from the VirtualBox Machine menu. You have three choices of what to do with your VM state.
    1. Save virtual machine state means the next time you resume, the VM will be exactly as you left it, like standby/resume on your host computer
    2. Send shutdown signal will shut down the VM's (guest) OS in an orderly way; your changes will be saved, but the next time you restart the VM, any programs that were running in the VM will have been shut down.  This is like using the shutdown command in the table of "useful VM commands" above.
    3. Power off  is like pulling the plug on the VM, and there is a risk that some data may be lost.  This option is not recommended except as a last resort if the other options don't work. This is like using the reboot -q command in the table below.

A note on VirtualBox VM networking

VirtualBox uses network address translation (NAT) by default, giving your VM a 10.0.0.* address that is routable from your host computer but not from the outside world. VirtualBox offers other networking options if this doesn't work in your setup. 

If your host computer is connected to the Internet, your VM will be too.  However, if you suspend (sleep) your host computer and then wake it up on a different physical network (for example, sleep your computer at work, then travel home and wake it up there), you will need to restart the VM's networking subsystem or networking will appear to be broken.  The table of useful VM commands below shows how to do this.  If the network restart doesn't work, reboot your VM.

Useful commands while working with the VM

The VM's root (administrator) password is saasbook - you will need to supply it when doing certain administration tasks, such as any command line that begins with sudo.

 sudo /etc/init.d       networking restart  Restart VM networking when host computer is suspended and then resumed on a different network.  (Not applicable if using EC2)
 sudo /sbin/reboot  Reboot VM gracefully
 sudo /sbin/reboot -q  Reboot VM forcibly (if gracefully doesn't work)
 sudo /sbin/shutdown    Shut down VM gracefully (add -q for forcefully, if gracefully doesn't work)


Option 2: Use Amazon Elastic Compute Cloud (EC2) to deploy the VM image in the cloud

This is recommended if running a virtual machine on your computer is too slow. Here are the instructions, thanks to MOOC student Jeremy Banks.

Option 3: Installing the software yourself on an existing system (experienced users only)

Use git to clone the repo github.com:saasbook/courseware.  In the vm-setup directory you'll find shell scripts for configuring various versions of the VM.  These scripts assume starting from a clean Ubuntu image, so they may not work out-of-the-box on your equipment, but you should be able to figure out what is being installed.  One way to get a clean Ubuntu image is to use vagrant to create a blank ubuntu instance on which to install the courseware.

Option 4: Using a Cloud hosted editor (not 100% tested)

In the past some students have managed to complete the homeworks using cloud hosted editors such as Cloud9 or Nitrous.  We have yet to thoroughly test these alternatives.  There are some notes on getting set up with c9:

http://www.agileventures.org/remote-pair-programming/c9-howto


Check that the installation is correct

After cloning the repo using the console you should do:

  1. Enter the directory of rotten potatoes directory with the command

    cd REPODIRECTORY/vm-setup/rottenpotatoes

  2. Install possible missing gems

    bundle install

  3. Install the database migration of rotten potatoes

    bundle exec rake db:migrate

  4. Start the http server (this will hold the console and you cannot use it anymore, if you want to stop you can do CTRL+C)

    rails server

  5. Using one browser check if the application can be accessed using the URL http://localhost:3000/ and you should be able to see the rotten potatoes application running