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
  • Bundle install private repository gems
  • Advanced customization with override files
  • Deploy Hooks

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 => ''

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 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 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
#{} \\) -exec chown #{config.user}:#{} "{}" +|

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.