Knowledge Base/Engine Yard Cloud Documentation/Deploy your Application

Customize Your Deployment

Engine Yard
posted this on February 16, 2012 10:02 AM

Updated: March 6th, 2013

 

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.

Examples

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

    environments: 
    myapp_staging:
    copy_exclude:
    - .git
  • Set a default branch

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

    environments:
    myapp_staging:
    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 false.

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

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

You need to install the Deploy Key for your application in the Github deploy keys.

  1. Go to the Engine Yard Cloud Dashboard and click on your application's name.
  2. Find a link near the top named "Deploy Key". It will show a box with an SSH public key and copy the entire key.
  3. Go to the private gem's github.com page, click on Admin, and then Deploy Keys.
  4. Paste the key, and label it something like "[app name] deploy key".
  5. Save the key, entering your github password if prompted.

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.

Example: GitHub style deploy

# This is an overrides file for ey deploy that uses git to do all 
# moving around, rather than using multiple directories and symlinks

class ::EY::Serverside::Deploy::Configuration
# no separate releases directories
def release_path(*args)
current_path
end

def all_releases(*args)
[current_path]
end
end

def copy_repository_cache
# Don't need to do this, just make sure current is linked to
# cached-copy
run "ln -nfs #{c.repository_cache} #{c.current_path}"
end

def symlink(*args)
# do nothing
end

def cleanup_old_releases(*args)
# do nothing
end

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.

 

Comments

User photo
Clint Bounds
Plan to Eat

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?

June 25, 2012 11:32 AM
User photo
Evan Machnic
Engine Yard Inc.

Clint,

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.

Thanks,
Evan
June 26, 2012 12:34 PM
User photo
Robert Cigan
BC21 Inc.

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:

 

December 12, 2012 02:06 AM
User photo
Ches Martin
Admin500

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.

February 08, 2013 07:53 AM
User photo
Jason Gerry
Cox-Digital-Exchange

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

https://github.com/engineyard/engineyard

 

April 01, 2013 11:58 AM
User photo
Michael O'Boyle
ProvaSystems

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?

June 11, 2013 10:49 AM
User photo
Intl Gum
intlgum

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.

 

defaults:
  maintenance_on_migrate: true
  maintenance_on_restart: true
  precompile_assets: true

June 11, 2013 07:42 PM
User photo
James Paterni
Engine Yard Inc.

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.

Regards,

James Paterni

June 12, 2013 08:34 AM
User photo
Keri Meredith
Engine Yard Inc.

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

[DOC-947]

June 12, 2013 09:05 AM
User photo
Noam Gagliardi
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.

August 21, 2013 10:06 AM
User photo
Evan Machnic
Engine Yard Inc.

Hi Noam,

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

Thanks,
Evan

August 21, 2013 10:21 AM
User photo
Noam Gagliardi
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.

August 21, 2013 10:49 AM
User photo
Evan Machnic
Engine Yard Inc.

Noam,

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.

Thanks,
Evan

August 21, 2013 11:08 AM