Engine Yard Developer Center

Customize Your Deployment

If your application has special deployment requirements, read this page about methods to customize the deployment process.

The following methods can help you customize your deployment:

Using ey.yml to customize your deployment

ey.yml is a YAML file that lives in your application’s config/ directory. It allows you to customize the deploy process to a limited, but still useful, extent.

ey.yml contains a single top-level hash named environments. Its keys are environment names, and its values are themselves hashes of settings for that particular environment.


All these examples assume your environment is myapp_staging. Replace that with your environment’s actual name.

  • Don’t copy .git directory to each release

    - .git
  • Set a default branch

    branch: master
  • Use thor to run migrations, but only run them when –migrate is specified

    migrate: false
    migration_command: thor db:migrate

Fields to note

The engineyard gem pays attention to many keys in the per-environment hash. They are:

  • copy_exclude (array)
    items that are excluded when copying from your repository to each release. See rsync(1), in particular the --exclude option, for more details. Default is empty. See copy_exclude example above for YAML array syntax.

  • branch (string)
    the branch to deploy by default. Default is master.

  • migration_command (string)
    the command to invoke in order to run migrations. Default is rake db:migrate.

  • migrate (boolean)
    whether or not to run migrations during deploy.

  • bundle_without (string)
    the argument passed to bundle install --without '' during deploy. Default is test development.

  • maintenance_on_restart (boolean)
    shows maintenance page during app restart. Default is true for glassfish and mongrel and false for all other application servers.

  • maintenance_on_migrate (boolean)
    shows maintenance page during migrations. Default is true.

  • precompile_assets (boolean)
    enables rails assets precompilation. Default is inferred using app/assets and config/application.rb.

    The precompile assets setting in the ey.yml and the contents of the repository need to be in agreement on the expected asset compile method. If assets are compiled locally and committed to the repository, then ey.yml precompiled assets should be set to false. If assets are compiled at deploy time, then the ey.yml precompiled assets should be true and the repository should not contain a public/assets folder.

  • ignore_database_adapter_warning (boolean)
    hides database adapter warning if you don't use MySQL or PostgreSQL. Default is false.

Bundle install private gem repositories

To install gems in your Gemfile that are referenced by private git repository URI, like the following:

gem 'privategem', :git => 'git@github.com:yourname/privategem.git'

Now you can follow these steps:

1. Create a machine user account in Github

2.a. Add the machine user as a collaborator to the application repository an the private gem repositories


2.b. Add the machine user to a team that has access to the application repository and the private gem repositories

3. Finally, Copy the deployment key and add it as an SSH key of the machine user. As the machine user, go to https://github.com/settings/ssh then press the New SSH key button and add the deployment key.

When you've finished these steps, your private repository will be accessible to bundler when you deploy.

Advanced customization with override files

Deploy overrides offer an advanced level of customization via overrides file. This file is instance_eval’d into the main deploy class so that you can over ride core functionality of the deploy. You should not use this for simple modifications around a deploy (deploy hooks are a better choice for those tasks).

Using deploy overrides

To use deploy overrides, create a file in your code repository at either config/eydeploy.rb or eydeploy.rb. This file should contain a list of methods, and is instance_eval’d into the main EY::Deploy class. You can super into any of the methods that you override. You can see the source of the class that your customization will be instance_eval’d into on GitHub at https://github.com/engineyard/engineyard-serverside/blob/master/lib/engineyard-serverside/deploy.rb. We guarantee the top level tasks (bundle, symlink_configs, enable_maintenance_page, migrate, symlink, restart, disable_maintenance_page, and cleanup_old_releases) will remain consistent and in a consistent order. All other methods in the class are subject (but unlikely) to change.

Using the eydeploy.rb Files

Engine Yard does not typically recommend using the eydeploy.rb files to make changes to your application because maintaining version compatibility can be cumbersome. However, some situations warrant their usage. Use the eydeploy.rb files under the following conditions only:

  • If you have application changes that are too specific to add to an ey.yml configuration option.
  • The application changes are only temporarily needed. For example, you need a temporary fix while you are migrating your application.
  • You want to maintain the deploy consistency yourself.

eydeploy.rb Example

Below is an example of how you might use the eydeploy.rb files.

requirement = Gem::Requirement.create("~>2.3.0")
unless requirement.satisfied_by?(About.version)
  raise "engineyard-serverside version change detected. Make sure this patch works before deploying to production"end 
# In this example, the command below is not altered.
# Here is where you would make your modification to the chown command.
# Methods in the kernel scope here are eval'd into the Deploy object.
# This will then override all calls to ensure_ownership.
def ensure_ownership(*targets)
   sudo %|find #{targets.join(' ')} \\( -not -user #{config.user} -or -not -group
#{config.group} \\) -exec chown #{config.user}:#{config.group} "{}" +|

Deploy Hooks

Deploy hooks are Ruby scripts that you write which are executed at designated points in the deployment process. This allows you to customize the deployment of your application to meet its particular needs. We discuss deploy hooks in Use deploy hooks.

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

Was this article helpful?
6 out of 6 found this helpful
Have more questions? Submit a request


  • Avatar
    Clint Bounds

    Is config/eydeploy.rb still the preferred way to change the deploy methods in deploy.rb? For example, how do we set config.copy_exclude in the new copy_repository_cache method?

  • Avatar
    Evan Machnic


    The answer to this question really depends on the deployment method.

    • If using the web deploy, you'd need to configure the settings in the eydeploy.rb file.
    • If deploying from the CLI, you can use the ey.yml file mentioned in the documentation.

    I'd like to note that the ey.yml is going to be the preferred method in the future. Currently version 2.0 of the engineyard gem is in a public beta and greatly improves support for ey.yml. The web is currently requires eybackup.rb but will likely be updated to work with ey.yml as well.

    Feel free to install engineyard 2.0.0 --pre to test out the new version.



  • Avatar
    Robert Cigan

    Hi, is there a way to specify an account/app/environment in the ey.yml so when I deploy from the CLI, I don't need to enter this all the time manually instead just type ey deploy for instance? 


    robert$ ey deploy

    Loading application data from Engine Yard Cloud...

    Multiple application environments possible, please be more specific:


  • Avatar
    Ches Martin

    Echoing Robert's question. We've had default: true in the stanza for our staging environment for ages, but it seems that isn't really working anymore and that it's no longer documented.

  • Avatar
    Jason Gerry

    This page needs to be updated, it's missing field asset_roles: which I found here:



  • Avatar
    Michael O'Boyle

    If both the app and a gem used by the app are in private github repositories, the technique described above for setting the deploy key on the gem repo does not work. Github will reject setting the gem repo deploy key with a "Key is already in use" error. As a result, I'm not able to deploy my customer's application. Can something be done to support this need?

  • Avatar
    Intl Gum

    I just wanted to share my ey.yml real quick, because the steps on this page were confusing to me for some reason (no relavent example).  Oh, and I just use EY UI web to deploy everything, rather than CLI.



      maintenance_on_migrate: true

      maintenance_on_restart: true

      precompile_assets: true

  • Avatar
    James Paterni

    Hi Michael,

    When the key needs to be associated to multiple repositories you will need to use what github refers to as a "machine user", which is to create a new github account and give the key to that user, then allow that user access to both repositories.

    Github has more information about the machine user accounts here: https://help.github.com/articles/managing-deploy-keys#machine-users

    Hope this fully answers your questions.  Please let us know if there is anything else we can do to assist you.


    James Paterni

  • Avatar
    Keri Meredith

    Hi Kevin @Intl Gum, sorry this doc was confusing to you. Thanks for the feedback; we'll see if we can improve it! kjm


  • Avatar
    Noam Gagliardi

    Is there a way to specify a file that I want copied with every deploy? I have a .secret file for setting secret_key_base. It's generated (unless it already exists) on every deploy causing users to get logged out every time I deploy.

  • Avatar
    Evan Machnic

    Hi Noam,

    Would the asset_dependencies discussed at https://github.com/engineyard/engineyard/issues/165 accomplish what you need?



  • Avatar
    Noam Gagliardi

    Hm... doesn't seem to be working.

    I added. 

        - .secret 

    To asset_dependencies. 

    But it stills logs me out. cat /data/memorabble/releases/(time)/.secret still gives me two different strings. I need the file .secret to remain the same between releases.

  • Avatar
    Evan Machnic


    If that doesn't work, the best bet would probably be to drop the file to a location that isn't being symlinked during deployments using a custom Chef recipe. For reference, our documentation is at http://ey.io/custom-chef.



Please sign in to leave a comment.

Powered by Zendesk