Knowledge Base/Engine Yard Local/Engine Yard Local Documentation

Engine Yard Local 1.0.2

Keri Meredith
posted this on November 8, 2012, 3:00 PM

Updated: October 22nd, 2013

What is Engine Yard Local?

Engine Yard Local allows you to develop and test, locally on your own computer, using a virtual machine with an Engine Yard environment. Engine Yard Local allows you to:

  • Simplify your test and development process by running a fast, fully functional Engine Yard VM, wherever you need it.
  • Improve productivity by deploying locally - without committing to remote repositories or launching instances in the cloud.
  • Test Chef recipes before deploying to production or staging environments.
  • Leverage local compute resources for free, during development iterations.

The Engine Yard Local VM includes the same kernel, with the same Gentoo OS, and the same Chef provisioning as one of our cloud instances. Engine Yard Local provides the most recent version of the Engine Yard Gentoo stable-v2 stack (cookbooks) and the CLI warns you when your cookbooks are not up to date. The tool is built using Vagrant and VirtualBox. Engine Yard Local runs from your project root directory.

When you are ready, you can seamlessly deploy your app on the Engine Yard Gentoo stable-v2 stack in the cloud.

Get help or provide feedback

Use the Engine Yard sponsored forums to ask questions, find answerslog bugs, or suggest new features.

Install Engine Yard Local

This section discusses Engine Yard Local installation:


Engine Yard Local supports the same components as Engine Yard Cloud, as specified in the Engine Yard Gentoo stable-v2 stack, per this table:

Ruby  interpreter
  • 1.9.3.p448
Rails  framework
  • 3.2.x
HAProxy  load balancer
  • 1.4.24
Nginx  web server
  • 1.2.9
Passenger  app server
  • 3.0.21
PostgreSQL  database
  • 9.1.9
memcached  memory caching system
  • 1.4.5

Note: This version of Engine Yard Local does not support Ruby 2.0, Node.js, PHP, Java, Unicorn.


We assume you have a working installation of Ruby 1.9.3. How you came to install Ruby is outside the scope of these instructions.

Install manually

Download and install VirtualBox

  1. Navigate to the VirtualBox download site.
  2. Find the VirtualBox for your computer / OS and download it.
  3. Follow the instructions to install VirtualBox.

Note: Engine Yard Local has been tested with VirtualBox 4.1.10; newer versions should also be OK.

Download and install the Engine Yard Local gem

Once VirtualBox is installed, you can install the Engine Yard Local gem, engineyard-local. The gem is available at

  1. Type the following command, which installs the latest Engine Yard Local gem. It also installs an ey-local binary that provides the CLI (command line interface) tool for use with Engine Yard Local.
$ gem install engineyard-local

Get started with Engine Yard Local

This section discusses ways you can start using Engine Yard Local:

Run Engine Yard Local for a new application

The following commands create a new Rails project, myapp, within the existing Sites directory. Because this is the first time, ey-local up boots a VirtualBox, configures it, installs the cookbook recipes onto the VM, creates a DNA file based on the Git project settings for the app, executes the recipes, runs bundler, and invokes the migrations.

$ cd ~/Sites/
$ rails new myapp
$ cd myapp
$ ey-local up

When ey-local up is finished, you can view the default Rails page at

Note: You might want to run one Engine Yard Local application at a time. To switch to another project, power off the VM, change directories, and run ey-local up in the new project directory.

Or, if you don't mind some manual editing, you can edit the Vagrantfile. The boilerplate Vagrantfile puts everything on the same IP. So in order to have more than one VM running at the same time, edit the Vagrantfile and resolve the IP conflicts manually.

Run Engine Yard Local using the todo app

You can use the Engine Yard sample todo app to test your Engine Yard Local installation. For example:

$ cd ~/Sites/
$ git clone git://
$ cd todo

Note: Engine Yard Local defaults to PostgreSQL; If you want to use MySQL, see this known issue for a workaround.

$ ey-local up

When ey-local up is finished you should be able to view the todo app at

Manage the Engine Yard Local virtual machine

These commands will help you navigate your virtual machine.

View VM status

To see the status of your Engine Yard Local virtual machine, use the following command:

$ ey-local status

Log in via ssh

You can customize your development environment by logging in to a running Engine Yard Local virtual machine.

$ ey-local ssh

On an Engine Yard Local server and any Vagrant box, the /vagrant directory is shared with the local file system. Once logged in, change to that folder and you can see that it is the directory in which Engine Yard Local was started.

Note: That same path is also linked to /data/PROJECTNAME/current, so changes on the local file system in the project will be reflected inside the ey-local VM, and vice versa.

vagrant $ cd /vagrant
vagrant $ ls -l

Custom Chef cookbooks on the VM

The /vagrant directory is mounted from the application directory outside of the VM, generally where the ey-local command is invoked. So if you create a sub-directory called cookbooks within your app directory, then the VM will see it as vagrant/cookbooks/ and have access to the contents. If you put custom Chef recipes in that directory, then as part of the ey-local up process, those recipes are run to install and configure software on the VM.

For example:


Would be seen by an Engine Yard Local VM started from myapp/ as:


Tip: See for examples.

Exit the VM

vagrant $ exit

Use Engine Yard Local commands

These basic commands will help you get started with Engine Yard Local.

Create and boot a VM

$ ey-local up

Power off the VM

$ ey-local down

Restart a powered off VM

$ ey-local up

Suspend a VM

$ ey-local stop

Restart a suspended VM

$ ey-local start

Update a VM with the latest cookbooks

$ ey-local update

Note: Engine Yard Local warns you when your cookbooks are out of date.

Destroy a VM

$ ey-local terminate

Note: This command powers off the VM, destroys it, and removes all traces of the VM from the file system.

More help with commands

For the list of ey-local supported arguments, type this command:

$ ey-local help

Note: Any argument not supported by Engine Yard Local is passed to Vagrant.

If you have feedback or questions about this page, add a comment below. If you need help, submit a ticket with Engine Yard Support.



User photo
Alex klein


Just 2 quick questions

1) What is the difference between files in :




2) Do I have to create the database by myself in the box?

December 4, 2012, 6:13 PM
User photo
Keri Meredith
Engine Yard Inc.

Hi Alex, thanks for your questions. I'll answer them here, then move them to the product questions forum. Hope that's OK.

1) What is the difference between files in: /data/MyApp/current  and /vagrant/MyApp

There is no difference between the files. The project directory is mounted in the instance under /vagrant, and we link that to the /data/myapp/current location since that's the Engine Yard standard for where the project is mounted.

2) Do I have to create the database by myself in the box?

No, you are not required to create the database in the box. We use the same cookbooks that are used on Engine Yard Cloud instances, which will set up the database for you. When we deploy your app, we'll take care of the database configurations and even do your Rails database migrations.

If you have more questions, please post them on the Engine Yard Local Product Questions forum.

Thanks for contributing to the Engine Yard Local community by asking your good questions here! kjm

December 5, 2012, 5:38 PM
User photo
Ryan Porter

Has Engine Yard Local been abandoned?  I wish that I could use it, but it's way out of date, and it can't even be used with a Rails 4 project because of gem conflicts.  We're using Vagrant instead.  It would be great if we could at least get a Vagrant base box for Engine Yard Gentoo or something, if Engine Yard Local isn't going to be supported?

May 10, 2014, 3:23 PM
User photo
Liricco Dev

I am also hoping for an update on Engine Yard Local.

May 21, 2014, 1:06 AM
User photo
Tasha Drew
Engine Yard Inc.

Hi all, 

Thanks for the notes, and checking out Engine Yard local.

We are not currently updating EY Local. Due to tooling issues when it was originally released it is very difficult to keep it at the latest Gentoo stack release, so it is identical to what you would receive in a new environment -- or pin it to the exact version of Gentoo a customer is using in production. This limits its usability for the purpose we once envisioned for it. 

Since this project was released, we have added a great deal more tooling internally, with the goal of making releasing stacks simple and streamlined. At some point we may integrate that work with an EY Local project, and turn this into what the original idea was -- a simple and easy way to test your development locally using the Engine Yard stack, and using a stack that exactly mirrors what you are using in production. For now, though, that work is not prioritized. 

Thanks, Tasha 

May 21, 2014, 11:13 AM