1. Setting Up

You need to prepare your laptop to use the numerous tools in our planned meet-ups. To do so, read this page and follow its instructions, step-by-step. You will find a a verification procedure at the end of the document that will ensure that you have a working development environment.

At a glance, you will configure all of the following. Don’t download these now, just glance at the list to get a sense of what you’re setting up.

  1. tottbox (v2013-12-31), an Ubuntu virtual machine (VM) prepared to run all of our tools
  2. VirtualBox (v4.3.6) to run tottbox
  3. Vagrant (v1.4.1) to control tottbox
  4. Git for version control
  5. A GitHub account for code backup, collaboration, and submission
  6. SublimeText for code editing (optional)
  7. Package Control for SublimeText and some useful extensions (optional)
  8. Google Chrome for web development (optional)

Some of the steps will vary depending on your operating system (e.g., Windows, Mac, Linux). Make sure you follow the appropriate instructions.

Note

If you are following these steps during one of our meet-ups, you can save time by borrowing a thumbdrive with all of the required installers (Windows and OS X, sorry Linux users) and VM images on it. If you do, copy all of the files from the thumbdrive to a temporary folder somewhere on your laptop. Then use them in place of fresh downloads throughout this document.

1.1. VirtualBox

VirtualBox is an open source virtualizer, an application that can run an entire operating system within its own virtual machine. For instance, you can create a virtual machine running Ubuntu Linux and bring up that machine right on your Windows 7 desktop. There are many interesting uses and advantages of virtual machines, two of which will benefit us greatly:

  1. A common, consistent environment for running code and tools
  2. The ability to “reset-to-zero” at any time

Do the following to install VirtualBox 4.3.6, the latest stable version tested for this meetup.

  1. Download the installer for your laptop operating system using the links below.
  2. Run the installer, choosing all of the default options.
    • Windows: Grant the installer access every time you receive a security prompt.
    • Mac: Enter your admin password.
    • Linux: Enter your root password if prompted.
  3. Reboot your laptop if prompted to do so when installation completes.
  4. Close the VirtualBox window if it pops up at the end of the install.

1.2. Vagrant

Vagrant is an open source command line utility for managing reproducible developer environments. While we could use the VirtualBox GUI to juggle virtual machines, their settings, and their distribution, Vagrant hides the complexity as you’ll see in the next section.

First, however, you need to install Vagrant 1.4.1, the latest stable version tested for this meetup.

  1. Download the installer for your laptop operating system using the links below.
  2. Run the installer, choosing all defaults.
  3. Reboot your laptop if prompted to do so when installation completes.

1.2.1. SSH for Windows Users

If you are running Windows on your laptop and have not installed Cygwin or the like, you’ll need to perform a few additional steps before Vagrant will be useful to you. Namely, you need to get a command line SSH (Secure SHell) client in order to connect to the virtual machine running on your laptop.

Installing Cygwin just to get SSH is overkill for our needs. A lower-overhead solution is to install git for Windows. This Windows installer includes a few common Unix command line utilities including the necessary ssh. (We’re not actually going to use git on Windows: we just want this package for its bundled copy of ssh.)

  1. Visit http://git-scm.com/download/win.
  2. If the installer does not download automatically, click to download it.
  3. Run the installer.
    • Choose the defaults until prompted about adjusting your PATH..
    • Pick Run Git and included Unix tools from the Windows Command Prompt.
    • Continue choosing defaults until the installer completes.

1.3. tottbox

With VirtualBox and Vagrant installed, you’re now ready to bring up the virtual machine (VM) running we’ll be using in our meet-ups, affectionately named tottbox. The VM has Ubuntu Linux Server 12.04 installed along with many of the tools we need to boostrap our explorations. It will be our common developer environment.

Note

To make it clear where we are running commands, from now on this doc will call the operating system running on your laptop the host box and the virtual machine, tottbox.

  1. Open a terminal window.
    • Windows: In the Start Menu, search for and run the Command Prompt application (cmd.exe). If you have Cygwin installed, you can run the Cygwin Bash Shell instead.
    • Mac: Run Terminal in the Applications folder.
    • Linux: You know what to do.
  2. Create a folder that will serve as the container for all of your practice work on your host box. In these instructions, we’ll call this the tott_dir from now on. Enter the following to create the folder.
    • Windows: mkdir \Users\your_username\projects\tott
    • Mac/Linux: mkdir -p ~/projects/tott
  3. Switch to the folder you just created in the terminal.
    • Windows: cd \Users\your_username\projects\tott
    • Mac/Linux: cd ~/projects/tott
  4. Download the TotT Vagrantfile, a config that tells Vagrant how to run tottbox. Do not give the file any extension if your browser prompts you for a download file name.
  5. Double-check the file name after downloading. Strip any .txt or other extension your browser gives to the Vagrantfile. You can do this using the Windows/OSX/Linux desktop environment or when you move the file via the terminal in the next step.
  6. Place the Vagrantfile in the tott_dir you created. You can do this by downloading it directly to tott_dir, using the Windows/OSX/Linux desktop environment to drag/drop it in, or using the move command in your terminal. For example:
    • Windows: move \Users\your_username\Downloads\Vagrantfile \Users\your_username\projects\tott
    • Mac/Linux: ~/Downloads/Vagrantfile ~/projects/tott/
  7. If you copied files off the borrowed thumbdrive, copy the file ending in .box to the tott_dir as well.
  8. If have not borrowed the thumbdrive, pause here until you have a stable Internet connection and time to leave your laptop downloading the tottbox virtual machine image (~700 MB) in the next command.
  9. Enter the following command: vagrant up. You must be connected to the Internet whenever you issue this command.
    • Vagrant will download the tottbox virtual machine image or copy it off from tott_dir for safe keeping.
    • It will make a hidden copy of the image in the folder you created.
    • It will launch and configure an instance of the virtual machine.
    • After some log messages and scary looking (but OK!) text, Vagrant returns you to the command prompt.
  10. Type vagrant ssh in the terminal.
  11. After a moment, you should land at a prompt like vagrant@tottbox:~$.

Important

On Windows, if you get an error about the VM being halted right after bringing it up, you likely need to enable support for virtualization on your laptop. This involves rebooting it, going into the BIOS setup, and finding the setting that says something like “Enable Virtualization Support”. Unfortunately, the steps for doing this vary widely across machines. Try to look for it, but ask for help if you can’t find it.

1.3.1. The tottbox shell

You are now in a shell running on your copy of tottbox. When you vagrant ssh, you are in the home directory of the vagrant user on the virtual machine. You can change to other directories using the shell command cd and list the contents of directories using the command ls. (We’ll cover these command and others in the sesson on Bash, Screen, Vi, and SSH).

Leave this shell open for the remainder of the steps in this tutorial. If you close your laptop or reboot it, you can reconnect to tottbox by opening a new terminal, returning to tott_dir using the cd command, typing vagrant up, and then running vagrant ssh.

If you want to explore, feel free. Anything you do on the VM file system is temporary. You can reset your tottbox at any time by running vagrant destroy followed by vagrant up on your host box.

There is one exception to the reset rule: the /vagrant directory on tottbox is a synchronized mirror of the tott_dir in which you ran vagrant up on your host box. Anything you do in /vagrant on the VM will also happen in the corresponding folder on your host box. Likewise, anything you do in the tott_dir on your host box will appear in the /vagrant folder on tottbox. This feature is critical: it will allow us to edit code and view web apps in our desktop environment, but run them in the stable tottbox environment. You’ll get to see this in action in a few minutes down below.

1.4. git

Git is an open source, fast, modern distributed version control system. Many high-profile projects have adopted Git for version control, and, according to the GitHub stats quoted on the front page of this site, many more are starting life in Git. We will practice using Git in almost everything we do.

Right now, you just need to tell Git who you are before we proceed. In the tottbox terminal, enter the following commands, replacing my name and email address with your own.

git config -f /vagrant/.gitconfig user.name "Peter Parente"
git config -f /vagrant/.gitconfig user.email "parente@cs.unc.edu"

This information will appear on all code changes you make. Make sure it is accurate.

1.5. GitHub

GitHub and BitBucket are two sites offering version control as a service. GitHub is by far and away the most popular site for social coding, but BitBucket offers unlimited private repositories to users with academic email addresses (i.e., you). Since we’re not concerned about keeping our practice code private, we will focus on GitHub. But keep in mind you can get free, private hosting on BitBucket if you need it for other course work.

  1. Visit the GitHub home page.
  2. Click Sign up for GitHub.
  3. Enter the required information.

At this point you’ve got a GitHub account, but no way to push code to it for version control. To finish the setup, you need to create a public-key pair. You will store the public half of the key on GitHub and keep the private half local for use in your tottbox.

  1. Click the Account settings (tools icon) in the top right.

  2. Enter your first and last name at least.

  3. Click SSH keys on the left.

  4. Click Add SSH key.

  5. Enter tottbox public key in the Label field.

  6. Switch to your tottbox terminal and enter the following commands in the tottbox shell.

    mkdir -p /vagrant/.keys
cd /vagrant/.keys
ssh-keygen -f /vagrant/.keys/github
  1. When prompted, enter a password of your choosing to protect the key pair. You’ll only need to enter it once each time you bring up a new tottbox instance, so giving it a password is not painful and it’s The-Right-Thing-To-Do (TM).
  2. Run less github.pub in the tottbox terminal.
  3. Copy the entire output, the public key, to the clipboard.
  4. Back on the GitHub site, paste the entire output into the Key field.
  5. Click Add key.

Your GitHub account is now ready for use. We’ll test it in a few minutes to confirm your environment is configured properl. For the moment, check that the /vagrant directory on your tottbox has the proper files.

  1. Run the command find /vagrant in the tottbox terminal.

  2. Verify the output looks something like the following. (It’s OK if there are other files too.)

    vagrant
vagrant
vagrant/Vagrantfile
vagrant/.keys
vagrant/.keys/github.pub
vagrant/.keys/github
vagrant/.gitconfig

Note

Typically, keypairs live in a .ssh directory in your home folder. We deviate from the norm here because we want our keys to continue to exist even if we destroy and recreate tottbox. So, instead, we store the keys in the /vagrant folder which keeps them synced with our host box. When the you run vagrant up a little script copies the keys from the /vagrant/.keys folder into the right location in your tottbox instance.

Vagrant does support agent forwarding which would allow us to store the keys more securely on our host box. Setting up forwarding is a bit of a pain on some OSes, however, so we’ll stick with the sync’ed folder approach.

1.6. SublimeText (Optional)

SublimeText is a cross-platform programmer’s text editor with a powerful extension system. To get a sense of what it can do, visit http://www.sublimetext.com/, watch the animation on the front page, and read some of the features further down the page. While I will not go so far as to require that you use a particular editor, I highly recommend it. I’ve been through Emacs, Vim, Eclipse, TextMate, and others: I’ve been the most productive with Sublime.

  1. Visit the SublimeText home page.
  2. Click the download link for your operating system below the animation or visit the Download tab.
  3. Install SublimeText.
    • Windows: Double-click the downloaded installer and follow its instructions.
    • Mac: Double-click the downloaded disk image and drag SublimeText to your Applications folder.
    • Linux: tar xjf Sublime*.bz2 and make sure the sublime_text executable is in your $PATH.
  4. Run SublimeText.
    • Windows: Click the SublimeText icon in the Start menu.
    • Mac: Double click the SublimeText icon in your Applications folder.
    • Linux: Run sublime_text in a terminal in your desktop environment.

Take a few minutes to try some of the features noted on the SublimeText home page before continuing. Pay extra attention to the Goto Anything and Command Palette features.

1.6.1. SublimeText Package Control

Package Control is an extension for SublimeText that lets you easily install a host of additional extensions from within Sublime.

  1. Visit the Package Control home page.
  2. Click the Installation tab.
  3. Follow the instructions to install Package Control for the version of SublimeText you installed.

Once you have Package Control installed, do the following to install some extensions that will benefit you.

  1. Press Ctrl-Shift-P (Windows/Linux) or Cmd-Shift-P (Mac) to open the SublimeText Command Palette.
  2. Start typing install until Package Control: Install Package is the selected item.
  3. Press Enter.
  4. Start typing GitGutter until that package is selected.
  5. Press Enter to install it.

Voila. You’ve installed a package that can show you which lines in your code you’ve changed since you last committed your code to version control. (If the last sentence was gibberish, don’t fret. We’re going to cover version control with git and these extensions will make a lot more sense in context.)

Repeat the procedure you just followed to install GitGutter for the following additional packages:

  • SublimeLinter
  • SidebarEnhancements
  • HTML5

After installing these, take a few minutes to browse the Package Control community repository to get a sense of the tools available.

1.7. Google Chrome (Optional)

The desktop browser scene is not as messy as it was some years back. The big browser vendors are largely converging on a common feature set defined by HTML5, CSS3, and so on. Firefox, Safari, Google Chrome, Opera, and even recent versions of Internet Explorer are all fine for browsing the web. Most are pretty good for web development too. I recommend using Google Chrome for its excellent developer tools, but any modern browser should suffice.

  1. Download the Chrome installer.
  2. Follow the instructions that appear one you accept the license agreement to get it installed.
  3. Run Chrome.
    • Windows: Click the Chrome icon in the Start menu.
    • Mac: Double click the Chrome icon in your Applications folder.
    • Linux: Run chrome in a terminal in your desktop environment.

Chrome will prompt you to create or login to a Google Account. You do not need to do so for the purposes of our meetings, but you can if you wish.

1.8. Verification

We’ll now run a quick test of your environment. We won’t test everything, but we will at least kick the tires.

By following these steps, you’ll start with a fresh tottbox instance, fork the repository I created on GitHub for this test, clone the repository locally, fill in a little README text file template with some basic information, run a test suite I wrote to check your work, commit your changes to the repository, and push the changes back up to GitHub.

Again, don’t let the jargon scare you: we’re going to get lots of practice using git for version control and cover all of these terms. If you want to jumpstart your understanding, start reading the first two chapters of the Pro Git book and playing with git on tottbox.

1.8.1. Destroy

  1. In the tottbox terminal, type exit to terminate the SSH connection to the tottbox.

  2. Destroy, rebuild, and then connect to a fresh tottbox instance by running the following commands in the tott_dir on your host box.

    vagrant destroy
vagrant up
vagrant ssh

  3. Enter the passphrases you assigned to the GitHub key you created when prompted on login.

1.8.2. Create and Clone

  1. Visit GitHub and login.

  2. Visit https://github.com/parente/tott-verify.

  3. Click the Fork button.

  4. Clone your tott-verify fork for local editing with the following commands on tottbox, replacing your_username with your GitHub username.

    cd /vagrant
git clone git@github.com:your_username/tott-verify.git

1.8.3. Edit and Test

  1. Open SublimeText on your host box.

  2. Use it to open the README.md file in the tott-verify directory git created in the tott_dir.

    • On Windows, if you followed my tott_dir suggestion, it’s in \Users\your_username\projects\tott\tott-verify\README.md
    • On Mac/Linux, if you followed my tott_dir suggestion, it’s in ~/projects/tott/tott-verify/README.md.

  3. Review the contents of the README.md file.

  4. Replace the information about me with the equivalent information about you.

    • If you’re using SublimeText and have installed GitGutter, you should see little markers in the left gutter of the editor when you save. These are the lines you’ve modified in comparison with the latest copy of the README in version control.
    • You don’t have to put your real name and email. It’s just a test case for pushing code to GitHub.

  5. Back at the tottbox prompt, do the following to execute a test suite checking the README.md file and tottbox environment against the specs.

    cd /vagrant/tott-verify
behave

  6. Address any README.md failures reported by fixing your the file until the tests pass.

  7. Address any tottbox failures by asking for help. (They’re probably my bugs, not yours.)

Note

For this exercise, specifications and tests are overkill. However, I want you to get a glimpse of behavior-driven development (BDD), a topic we will cover later. If you’re curious about what’s going on, open features/*.features files in your editor and review their contents. They open the associated features/steps/*.py files and match up code with specification.

1.8.4. Commit and Push

  1. In the tottbox terminal, run the following commands to commit your changes to your local git repository and then push them to the copy of your repository on GitHub.

    cd /vagrant/tott-verify
git commit -a -m "Replaced user info in README"
git push origin master

  2. Visit your GitHub dashboard again.

  3. Confirm that the front page of your dashboard shows the README with the changes you just made.

1.8.5. What Happened?

You might wonder what just happened behind the scenes. Here’s the gist.

  • You destroyed your tottbox VM instance and brought up a new one.
  • You created a read-write copy, a fork, of the read-only parente/tott-verify git repository on GitHub.
  • You made a read-write clone of your fork in your tott_dir on your laptop for local editing.
  • You edited the README.md to note your personal information.
  • You ran the test suit I provided to check that your README.md and environment conforms to a simple spec.
  • You committed your edits to the README.md in your local clone of the repository.
  • You pushed the commit from your local clone up to your fork on GitHub.

Don’t worry if the above description leaves you with even more questions. We have an upcoming session on Git and GitHub.

1.9. Cleanup

If you borrowed a thumbdrive, you can delete everything you copied to your hardrive, except the Vagrantfile. You can delete the .box file you copied into tott_dir. Vagrant has safely stashed it away in its own directory.

1.10. Success

You just setup a virtually indestructible development environment on your laptop with numerous interesting, useful tools pre-installed. Play with it. Break it. Put it back together. Read more about the pieces. Have fun.

We’ll exercise all of the pieces during our coming sessions.