Troubleshooting the Deployment Process in Engine Yard


As a Ruby on Rails platform, it is necessary for Engine Yard to allow customers to deploy their code. Because of the complexity, frequency, and custom nature of the process, issues may arise during deployment. In this article, we review the main artifacts that will allow you to understand the deployment process and troubleshoot related issues.


The deployment process

The deployment process in Engine Yard is often referred to as server-side, and is executed on the app master, with other instances only showing logs for the deploy hooks.

While the deployment process is detailed in How Your Ruby Code Is Deployed on Engine Yard Cloud, we can generally point to the following stages, excluding the deploy hooks:

  1. The code is fetched from GitHub to the application master.
  2. The code is then pushed to all other instances of the application that require the code.
  3. The release directory is created and permissions are assigned.
  4. Gems (Ruby libraries) to be installed are identified in the Gemfile and "bundled" (installed).
  5. Configuration directories and symlinks are created.
  6. JavaScript dependencies are identified from package.json and installed and compiled by Yarn.
  7. The DB is "migrated", which means that the schema is updated as required by changes to the code.
  8. The new release is symlinked, meaning that the "current" folder now points to the new deployment.
  9. App servers are restarted.
  10. Older deployments are cleaned, as no more than three exist at once.

Working with the deployment logs

Logs in Engine Yard are contained in the following directory:

Location Description

Contains the last deployment log; for older logs, the Engine Yard web UI must be used instead.

The application master contains all deploy-related logs, while other applications only contain the deploy hooks.

Unlike other logs, only the last version of the deploy logs is available in the Engine Yard instances; however, it is possible to see older logs directly from the Engine Yard UI by clicking 'view log' in an environment page.

To navigate the logs, it is generally recommended that you try to identify the stages that have been completed successfully to locate the point of failure. The best way to do this will be to look for the string "~>". If working on the instance, you can use the following command:

grep "~>" /home/deploy/<app_name>-deploy.log

This should show an entry for each stage in the deployment process that has occurred.

The deployment hooks

Deployment hooks are Ruby scripts that can be executed as part of the deployment process at specific stages. For more information on deployment hooks, please refer to The Default Deploy Hooks in Engine Yard.


When deploying code in Engine Yard, you may encounter issues related to the deployment process. Understanding and debugging these issues is crucial for a smooth and successful deployment.


Article is closed for comments.