Engine Yard Local (EY Local)

EY Local brings the production virtual environment of Engine Yard Cloud to your local laptop/workstation.

Engine Yard Local is a wrapper around the Vagrant tool which is written in Ruby and utilizes VirtualBox, and a custom prepackaged virtual machine image in order to make the creation and management of your local development environment easy, and customizations to your production environment testable. The project also allows you to test in an almost identical environment to Engine Yard's production cloud environment.

Contact

Team members can be found on irc.oftc.net in #ey-local.

Bugs

If you encounter a bug you can post it here: Engine Yard Local Bugs *

Provide the following information with the bug:

  1. What host platform are you running?
  2. What version of VirtualBox do you have installed? VBoxManage -v
  3. What version of the engineyard-local gem do you have installed? ey-local version
  4. What version of the vagrant gem do you have installed? vagrant -v
  5. Provide gist or other dump of the output that illustrates the problem.

Note: If you do not have an Engine Yard customer login, you cannot log a bug on this forum. Instead, please email us: [email protected] OR ... better ... start a free trial today!

Installation

Install the latest VirtualBox and Ruby for your platform and then perform:

$ gem install engineyard-local

Once the install is complete you're ready to get started.

Common Use

EY Local works from the root directory of your Rack based project. You can fire up a virtual environment from there with one command:

$ cd /path/to/your/application/code/
$ ey-local up
[ey-local] Downloading with Vagrant::Downloaders::HTTP...

If you've never used ey-local before, it will begin the process by downloading the base virtual machine image from which all ey-local virtual environments are built. This will only happen once and ey-local will use the downloaded box for all subsequent virtual environments.

Please note that a known issue is that sometimes it will fail right after download due to not reloading configuration. If this happens to you please try another ey-local up immediately and the issue will likely resolve itself since the configuration will be reloaded properly this second time.

After the download, the virtual machine will be created and you'll be able to visit your app by pointing your browser at the default IP address of 33.33.33.10 which represents the virtual machine's host network location.

From there you can edit your application files and see the application results as you normally would in your browser at the address http://33.33.33.10/

Stop

After working on your application you might want to suspend the virtual machine so it's not eating up cpu cycles while you're doing some thing else. Simply issue:

$ ey-local stop

... from your project directory to suspend the virtual machine.

Start

To restart the project's virtual machine after suspending it to continue working:

$ ey-local start

Other Commands

For details on other possible commands including list, rails, log, and exec please see:

$ ey-local help

Please note that the ey-local command is a wrapper around Vagrant itself and any commands that aren't defined for ey-local will be passed through to Vagrant for execution. For example provisioning an ey-local environment is as simple as:

$ ey-local provision

You can learn more about provision and other Vagrant commands in the Vagrant docs or see vagrant help for more.

Provisioning with Chef

In addition to the facilities for VM provisioning provided through the Vagrantfile, ey-local also includes a sane default for chef recipes when no other provisioning mechanism is defined. To take advantage of the default simply place your recipe at $PROJECT_ROOT/cookbooks/main/recipes/default.rb. From there you can aquire other recipes.

Contributing to the Engine Yard Local Project

Pull requests are the preferred method for contribution to the project with a couple general guidelines:

  1. Keep changesets small. Every changed line has to be reviewed so the smaller each change is the faster the review process will be.
  2. Keep commits small. Keeping each child commit of a pull request small makes managing the git history easier especially for things like bisect. Additionally, if the commits require a rebase by a team member, resolving conflicts will be much less painful.
  3. Discuss large changes. If you are compelled to make some drastic change to the source, please consult the team using the methods detailed earlier.

Engine Yard Local Project Layout

The project layout uses the standard ruby gem folder structure. The best starting point for interested parties new to the source is at lib/engineyard-local/command/group.rb. There you'll find the Thor-based command setup that is the entry point to ey-local's functionality. Thor is a holdover/stopgap before moving to the Vagrant command structure, and is mostly a proxy for the command classes in the same subdirectory.

Upon viewing the individual command classes you'll likely be interested in the middleware used to operate on the Vagrant virtual machines. The middleware is the primary abstraction that is used to keep each unit of work tiny and manageable. All of those and their helpers are to be found int the lib/engineyard-local/middleware/ directory.

Installing the latest development HEAD

You can install the latest from the repository with the following:

$ gem build engineyard-local.gemspec
$ gem install pkg/engineyard-local-<VERSION>.gem

Tests

There are a fairly minimal set of mock/stub based unit tests:

$ bundle install
$ rake test

If you're developing on Ruby 1.8 your bundle install should exclude the :dev group.

$ bundle install --without=dev

If you're feeling brave you are welcome to run the integration tests as well though they will create and destroy virtual machines over a long period of time. After the bundle install:

$ rake integration

You can also prefix that with a DEBUG=true to see the output from the tested commands.

$ DEBUG=true rake integration