Knowledge Base/Engine Yard Cloud Documentation/Deploy your Application

Deploy from the CLI (Engine Yard CLI User Guide)

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

Updated: March 7th, 2013

Welcome to the user guide for deploying to Engine Yard Cloud with the engineyard gem. The engineyard gem provides a command line interface (CLI) to perform tasks such as deploying your application, rebuilding your applications environment, opening an ssh session to any of your instances, uploading and applying custom chef recipes, and more.

Getting started

You need to install and run the engineyard gem in your local environment on your development machine.

Even if you already have the engineyard gem installed, it is good practice to run "install engineyard" to make sure that you have the latest version of the gem.

To deploy an application from the CLI

  1. Install the engineyard gem:

    gem install engineyard
  2. Switch to your local application directory that contains your git repository:

    cd ~/my_application
  3. Deploy your application:

    ey deploy

    If your application is running in multiple environments, append -e environment_name to disambiguate, for example, ey deploy -e production.

  4. The first time you run the engineyard gem, enter your Engine Yard account credentials (email address and password) at the prompts. You only have to enter these once.

    Your application is now deployed.

Switching Engine Yard accounts

If you want to log out of one Engine Yard account and log in to another, use the logout command to delete the API token from ~/.eyrc or env $EYRC. This token is created at Step 4 above.

To switch accounts within the CLI

  1. Type:

    ey logout
  2. Run any engineyard gem command, for example, ey login

  3. At the prompt, enter the credentials for the account you want to use.

Shortened name matching

A shortened substring name may be used to save typing with any command that accepts --environment/-e, --account/-c, or --app/-a as options.

For example, if the app has 2 environments, myapp_staging and myapp_production, then any one of the following will correctly select myapp_production:

  • --environment myapp_production
  • --environment production
  • -e prod

The interface will do its best to find the indicated application, environment, and account and exit without doing anything if it cannot find a definitive match.

Command reference

ey help

  • Print a short help message.

  • ey help COMMAND prints out the help for that command. For example, ey help deploy prints out the help for the ey deploy command, while ey help recipes apply shows the help for ey recipes apply.

ey version

  • Print the version of the engineyard gem.

  • Arguments: none

ey deploy

  • Deploy your application.

  • This command must be run from a checked-out copy of your application.

  • Arguments:
    • -e --environment NAME (optional): the environment to which you want this application to deploy. If this application is only deployed in one environment, this argument may be omitted.
    • -r --ref GIT-REF(optional): the git ref to deploy
      • You can specify a branch, a tag, or a SHA.
      • This argument defaults to the current branch.
      • Note: the deployment process pulls the code from the git remote that was previously entered into the Engine Yard Cloud web application. Thus, the named branch must exist in that git remote for your deployment to succeed.
    • -a --app NAME (optional): the application to deploy. If the current working directory is inside the application’s git repository and --app is omitted, ey infers the application from the configured git remotes.
    • -c --account ACCOUNT (optional): name of the account in which the application and environment can be found
    • -m --migrate COMMAND: the command to use for database migrations. Default is rake db:migrate.
    • --no-migrate: Skip migrations.
    • --ignore-default-branch (optional): Override the default branch specified in ey.yml.
    • --extra-deploy-hook-options (optional): Additional options to be made available in deploy hooks (in the 'config' hash). Add key value pairs as follows: --extra-deploy-hook-options key1:val1 key2:val2
  • Deployment takes place in several stages. For more information, see our documentation on Steps of Deployment.

ey status

  • Shows deployment status of an app and environment.

  • Arguments:

    • -c --account ACCOUNT (optional): name of the account in which the environment can be found
    • -a --app APP (optional): name of the deployed application.
    • -e --environment ENV (optional): the environment to show the deploy status

ey environments

  • List your applications and environments. By default, lists only the environments for the current application.

  • Arguments:
    • -A --all (optional): list all applications and environments
    • -s --simple (optional): prints each environment name on its own on a new line
    • -c --account ACCOUNT (optional): name of the account in which the environment can be found
    • -a --app APP (optional): name of the application containing the environments
    • -e --environment ENV (optional): shows only environments matching named environment

ey rebuild

  • Ensure the configuration of your environment is up-to-date.

  • Arguments:
    • -c --account ACCOUNT (optional): name of the account in which the environment can be found
    • -e --environment NAME (optional): the environment to rebuild.

ey ssh

  • SSH into a session or run a command on the application master. A command can also be run on --all servers.

  • Arguments:
    • -c --account ACCOUNT (optional): name of the account in which the environment can be found
    • -e --environment/-e NAME (optional): the environment to SSH into.
    • -A --all (optional): run command on all servers.
    • --utilities UTILITY NAMES HERE (optional): Run command on the utility servers with the given names. If no names are given, run on all utility servers.
    • --app-servers (optional): Run command on all application servers
    • --db-servers (optional): Run command on the database servers
    • --db-master (optional): Run command on the master database server
    • --db-slaves (optional): Run command on the slave database servers

ey logs

  • Show the most recent configuration logs.

  • Arguments:
    • -c --account ACCOUNT (optional): name of the account in which the environment can be found
    • -e --environment NAME (optional): the environment in whose logs you are interested.

ey recipes apply

  • Run already uploaded custom chef recipes.

  • Arguments:
    • -c --account ACCOUNT (optional): name of the account in which the environment can be found
    • -e --environment NAME (optional): the environment in which to run the recipes.
      • This argument may be specified by unambiguous substring.

ey recipes upload

  • Upload custom chef recipes.

  • Arguments:
    • -c --account ACCOUNT (optional): name of the account in which the environment can be found
    • -e --environment/-e NAME (optional): the environment in which to place the recipes.
    • --apply (optional): immediately run the uploaded recipes. This is the same as running ey recipes upload && ey recipes apply.

ey recipes download

  • Download custom chef recipes from an instance.

  • Arguments:
    • -c --account ACCOUNT (optional): the account that the environment belongs to.
    • -e --environment NAME (optional): the environment to download the recipes from.
  • Use download on instances where you have previously uploaded recipes. For example, you might want to download custom chef recipes when troubleshooting–to review the recipes that you are running on your instance.

  • The recipes are unpacked into a directory called “cookbooks” in the current directory. If the cookbooks directory already exists, you get an error.

ey web disable

  • Display a maintenance page. (Disables the web app and then displays the maintenance page.)

  • Arguments:
    • -c --account ACCOUNT (optional): name of the account in which the environment can be found
    • -a --app APP (optional): name of the application whose maintenance page will be displayed.
    • -e --environment NAME (optional): the environment in which to display the maintenance page.
  • This command has to be invoked from the application’s git repository so it can figure out which application gets the maintenance page.

ey web enable

  • Remove the maintenance page. (Removes the maintenance page and enables the web app.)

  • Arguments:
    • -c --account ACCOUNT (optional): name of the account in which the environment can be found
    • -a --app APP (optional): name of the application whose maintenance page will be removed.
    • -e --environment NAME (optional): the environment in which to remove the maintenance page.
  • This command has to be invoked from the application’s git repository so it can figure out which application gets its maintenance page removed.

  • For more information, see Using Application Maintenance Pages. 

ey web restart

  • Restarts the application servers for the given application. 
  • Enables maintenance pages if they would be enabled during a normal deploy. Respects the maintenance_on_restart option in ey.yml.
  • Arguments:
    • -c --account ACCOUNT (optional): name of the account in which the environment can be found
    • -a --app APP (optional): name of the application whose maintenance page will be removed.
    • -e --environment NAME (optional): the environment in which to remove the maintenance page.

ey logout

  • Logs out the currently signed in user by removing the api_token from ~/.eyrc.

Environment variables

  • ENGINEYARD_API_TOKEN

    Specify an API token to use instead of the token found in ~/.eyrc. Useful for automation scripts. The API token may also be specified on any command with --api-token.

  • CLOUD_URL

    Location of Engine Yard Cloud. Mainly used in development. Default is https://cloud.engineyard.com/

  • DEBUG

    Debug the engineyard gem (print a lot of stuff). Default is off.

  • EYRC

    Specifies the location of the .eyrc file to use. The .eyrc file is where the API token is stored. Default is ~/.eyrc.

  • NO_SSH

    If set, all commands (e.g. ey deploy, ey rollback) that require an SSH connection will short-circuit. Mainly used in the engineyard gem’s integration tests.

  • GIT_DIR or GIT_WORK_TREE

    The engineyard gem will respect the standard git environment variables to indicate the application working directory.

ey.yml Customizations

Extra customization can be accomplished with an ey.yml file. More about the ey.yml file.

Disable migrations

To prevent the rake db:migrate for certain environments, add migrate: false to the environment section ey.yml:

environments:
YOUR-ENVIRONMENT-NAME-GOES-HERE:
migrate: false

Exclude the .git directory

If you have a large .git directory and you do not want it copied over on every deploy, add a config/ey.yml to your application’s repository with the following contents:

environments:
YOUR-ENVIRONMENT-NAME-GOES-HERE:
copy_exclude:
- .git

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
kranthi reddy
highonrails

Hi, i'm getting the following error when installing the engineyard gem. Could you please look into this

$ gem install engineyard

ERROR: While executing gem ... (NoMethodError)
undefined method `call' for nil:NilClass

March 15, 2012 09:54 PM
User photo
J. Austin Hughey
Engine Yard Inc.

Hi Kranthi,

We've responded to the ticket you already had open with us in support. Please direct all further questions regarding your issue installing the engineyard gem to that ticket. Thanks!

March 15, 2012 11:49 PM
User photo
Norman Bean
TheGoldRefinery

Hi there,

I had to deploy some fixes to my server. Since the dashboard is not yet working,  I had to try CLI.  

First problem is that I don't have "~/my_application" directory.  My application is at /data/my_application.  In that directly, I tried running ey deploy.  It doesn't really use the working directory as input, it listed the environments that I can deploy instead.  It was helpful.  But then when I run it, I got this problem that it doesn't have ssh-key:

 

ip-10-212-70-9 .ssh # ey deploy --environment='staging' --app='my_app' --account='my_account' --branch 'refs/heads/production'
Loading application data from EY Cloud...
Beginning deploy of ref 'refs/heads/production2' for 'my_app' in 'Staging' on server...
Running command on deploy@ec2-xxx-xx-xxx-xxx.compute-1.amazonaws.com.
Error encountered during deploy.
Failed deployment recorded in EY Cloud
Authentication Failed: Please add your environment's ssh key with: ssh-add path/to/key

I tried doing ssh-add to the app's ssh key to access github, but it doesn't work.  I thought my environment is the most typical engineyard environment.  But this instruction seems to not support that.   Would you please give some pointers?

 

Thanks in advance.

March 18, 2012 10:04 PM
User photo
Norman Bean
TheGoldRefinery

Thanks for the great support.  They pointed out that I am actualy to install and use the EngineYard gem CLI on my local machine.  Once I know that,  it went very smoothly and my app is deployed. 

March 18, 2012 10:54 PM
User photo
Jane Day
Engine Yard Inc.

Thank you very much for your feedback. We have updated this page to clarify that the engineyard gem runs on your local machine.

March 19, 2012 02:49 PM
User photo
Tom Hoen
GiveCorps

Small comment. The doc above says that ey logout will take down the maintenance page. I believe it will log you out instead.

June 05, 2012 06:52 AM
User photo
Keri Meredith
Engine Yard Inc.

Hi Tom, thanks for the catch! We appreciate the feedback. kjm

June 05, 2012 07:35 AM
User photo
Agustin Cavilliotti
account-6569

Hi there! is there any way through the CLI tool or maybe another way, to display the Maintenance Page to all the visitor, except to the ones accessing from an specific IP? Thanks in advance for your time!

December 10, 2012 05:09 AM
User photo
Tom Hoen
GiveCorps

+1 for Agustin suggestion

December 10, 2012 05:23 AM
User photo
J. Austin Hughey
Engine Yard Inc.

Hi Agustin, Tom,

Our CLI does not have this capability at present (nor does the dashboard). Generally speaking, you should be able to push new code changes to a staging environment and preview them there before deploying live (so you can see the changes without affecting users). However, if that isn't sufficient for your needs, I recommend opening a feature request at our feature request forums.

https://support.cloud.engineyard.com/forums/30086-feature-requests

December 10, 2012 11:24 AM
User photo
Fritz Madden
Orchestra-fmadden-irise-com

Do you have a client tool for PHP deployments for is the this a Ruby only solution?

March 04, 2013 03:44 PM
User photo
Evan Machnic
Engine Yard Inc.

Hi Fritz,

While the engineyard gem is really focused on deploying Ruby applications, it should still be possible to use it to deploy a PHP app. Features related to migrations and database operations will likely not work but most of the other features should still be very useful for a PHP developer.

Note that to use the CLI, you will need to have Ruby installed and then you should be able to install it with $ (sudo) gem install engineyard. After that, just run ey help to see what commands are available to you.

Thanks,
Evan Machnic

March 04, 2013 06:52 PM
User photo
Sundeep Chugani
WeLiike

Hi all, 

Please give me sample code for mongoid.yml and ey.yml for engine yard.

 

Thanks & Regards

 

Sundeep

March 19, 2013 03:11 AM
User photo
Matt Scilipoti
LearnZillion

FYI: there is no mention of `ey rollback`

March 28, 2013 11:11 AM
User photo
Keri Meredith
Engine Yard Inc.

Thanks, Matt. What we really need is automated push of the https://github.com/engineyard/engineyard/blob/master/README.rdoc to this doc! :) 

thanks again, kjm

March 28, 2013 02:47 PM
User photo
Adam Raouki
KODEFUGE

After installing the 'engineyard gem' and issued the 'ey deploy' command, I got the following

   

Loading application data from Engine Yard Cloud...
Using current HEAD branch "master".
The environment 'kodefugeEnv' does not have a master instance.

 

Any clue?

   

September 17, 2013 04:20 PM