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.
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--excludeoption, for more details. Default is empty. See copy_exclude example above for YAML array syntax. -
branch (string)
the branch to deploy by default. Default ismaster. -
migration_command (string)
the command to invoke in order to run migrations. Default israke db:migrate. -
migrate (boolean)
whether or not to run migrations during deploy. -
bundle_without (string)
the argument passed tobundle install --without ''during deploy. Default istest development. -
maintenance_on_restart (boolean)
shows maintenance page during app restart. Default istruefor glassfish and mongrel andfalsefor all other application servers. -
maintenance_on_migrate (boolean)
shows maintenance page during migrations. Default istrue. -
precompile_assets (boolean)
enables rails assets precompilation. Default is inferred using app/assets and config/application.rb.The precompile assets setting in the
ey.ymland 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, theney.ymlprecompiled assets should be set to false. If assets are compiled at deploy time, then theey.ymlprecompiled 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 isfalse.
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
https://developer.github.com/guides/managing-deploy-keys/#machine-users
2.a. Add the machine user as a collaborator to the application repository an the private gem repositories
https://help.github.com/articles/how-do-i-add-a-collaborator
or
2.b. Add the machine user to a team that has access to the application repository and the private gem repositories
https://help.github.com/articles/adding-organization-members-to-a-team
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.ymlconfiguration 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} "{}" +|
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.
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?
Clint,
The answer to this question really depends on the deployment method.
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
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 deployfor instance?robert$ ey deploy
Loading application data from Engine Yard Cloud...
Multiple application environments possible, please be more specific:
Echoing Robert's question. We've had
default: truein the stanza for our staging environment for ages, but it seems that isn't really working anymore and that it's no longer documented.This page needs to be updated, it's missing field asset_roles: which I found here:
https://github.com/engineyard/engineyard
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?
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
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
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]
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.
Hi Noam,
Would the
asset_dependenciesdiscussed at https://github.com/engineyard/engineyard/issues/165 accomplish what you need?Thanks,
Evan
Hm... doesn't seem to be working.
I added.
- .secret
To asset_dependencies.
But it stills logs me out.
cat /data/memorabble/releases/(time)/.secretstill gives me two different strings. I need the file.secretto remain the same between releases.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