Create an Environment

Note: To follow this procedure you must have at least one application set up within your Engine Yard account.

Create an environment

An environment is a container for your web application and its instances. Instances are application, database, and utility servers.

To create an environment

  1. Log in to your Engine Yard account.
  2. Click Dashboard.
  3. Navigate to an application by clicking on the application name.
  4. Click Create New Environment.
  5. Enter the information necessary for your environment. (See Environment options below.)
  6. Click CreateEnvironmentButton.png

Environment options


  • Not all options appear, depending on your app development language.
  • For information about AddtoExistingEnvironment.png see Add an Application to an Existing Environment.
  • We recommend testing in a staging environment before applying changes in a production environment.

Environment Name

An environment name should uniquely identify the environment in your dashboard. Use underscores to separate words instead of spaces. Examples: myapp_production, myapp_staging.

Important: The environment name cannot be changed later.

Framework Environment

Select an environment type from the list.

Ruby apps

This populates RAILS_ENV and RACK_ENV. For example, this would be the equivalent to entering the environment variable RAILS_ENV=production in the command line.

Node.js apps

This populates NODE_ENV and FRAMEWORK_ENV.

PHP apps

This populates PHP_ENV.

Application Server Stack

Select an application server from the list.

Ruby apps

The default is Passenger 3; it is used for production and multi-application environments. If you need to run more than one application on an environment, choose Passenger.

Note: If you are currently running another app server (e.g., Unicorn) and want to change to Passenger 4, contact Engine Yard Support. The Engine Yard Support team can help to ensure that old workers are stopped properly. For more information on worker allocation, see Worker Allocation on Engine Yard Cloud.

If you will be running only one application on an environment (this is more common practice), then choose Unicorn. Engine Yard has found Unicorn to be reliable, easier to monitor, and to have less downtime during deployment. You need the Unicorn gem for this selection.

More info: Rails Server Throwdown and Passenger versus Unicorn blog

Node.js apps

The default is Nginx and proxies dynamic HTTP to Node.js. If you need WebSockets, select Node.js.

More info: Deploy Your Node.js App

PHP apps

PHP-FPM is the only server stack available.

More info: Deploy Your PHP App


Select the Engine Yard stack that is appropriate to your app and environment. Options are: Engine Yard Gentoo (legacy stack, stable-v2) or Engine Yard Gentoo 12.11 (stable-v4).

If this is a new environment, and your components and versions meet the Engine Yard Gentoo 12.11 tech stack, we recommend you use Engine Yard Gentoo 12.11 (stable-v4).


Select the interpreter version that your application has been developed with.


Select the appropriate RubyGems version for this environment. For example, an older version of Rails would need a different RubyGems version than the default.

Database Stack

Select the database you need for this environment. The default is PostgreSQL, or you can also use MySQL.

The No Database option is available if you choose to use an alternative data store like Riak or MongoDB. For example, you can use a utility instance and create your own data store. Or you can use this option along with a database offering from the Engine Yard add-on program.

Database Versioning

The default for all new and existing environments is to lock the minor database version (that is, the Prevent minor database version changes option is selected). However, the preferred policy is to allow minor database version changes whenever possible.

  • If the option is selected (checked), then stack upgrades on that environment will not include processing any minor database version upgrades included in the general stack upgrades (that is, your database’s version will be locked at whatever it currently is).
  • If the option is not selected, then minor database version upgrades will be processed whenever they are included in the weekly stack release.

See Database Version Upgrade Policies for more information.

Note: If you need a new environment to run an earlier minor database version (for example, to match another existing environment), contact Engine Yard Support.

Termination Protection

(Optional) The default behavior is to allow any collaborator to terminate an instance in the environment. If you are the account owner, you can require users to re-enter their password before allowing an instance to be terminated.

See Use Termination Protection for more information.

Promotion Protection

(Optional) The default behavior requires users to re-enter their Engine Yard password before proceeding with a database promotion. Un-selecting the associated check-box will remove this re-authentication step.

See Promote a Database Replica for more information on database promotion.

Takeover Preference

Select the appropriate application takeover option for this environment:

  • Boot from snapshot - The default method boots a replacement app slave from a new app master snapshot.

    You might use this if you have data on your volume or if you have a large application.

    Note: Engine Yard does not recommend keeping data on your app master.

  • Boot from new volume - This preferred method creates a new volume and builds a replacement app slave from that new volume.

    This is a faster method than the default. It is preferred because you are starting fresh with a new volume.

    Note: This option assumes you do not need to preserve any data on your app master.

  • Don't boot app slave - Takeovers still happen, but the app slave won't be replaced automatically.

    Note: This is an option if your environment requires manual intervention when creating a new app slave.

  • Disable - No app master takeovers occur. You will need to manually initiate takeovers.

    Note: This is an option for larger environments and environments with instances behind ELB for example. (See Use ELB doc for more information.)

Failed App Master Behavior

Engine Yard automatically triggers an app master takeover when it detects that your application master is unable to reliably respond to requests. During the takeover, the app master is replaced by an app slave. Once the app slave has been promoted to app master, then this setting determines what happens to the old app master.

  • Delete - The default behavior is to delete the old app master; this is best in most situations.
  • Detach - For cases when you want to investigate why an app master takeover is happening, you can select this option, which detaches the old app master and saves it as a utility instance that is not serving traffic, so you can debug the issue.


  • Although the old app master will no longer receive any web traffic, any other programs (for example, cron jobs, workers, or other background jobs) will continue to run until you terminate them.
  • If you click Terminate on the app master yourself, the Detach setting will not apply. The termination request will override the Detach setting.
  • If you need to test the Detach behavior, use the following command on the app master:

    sudo monit stop
    sudo /etc/init.d/haproxy stop

    This will trigger a takeover, and leave the old app master still provisioned, but detached. You will need to connect to the new hostname for the utility instance once the takeover workflow is complete.

See Application Master Takeover for more information.

Domain Name

(Optional) Type your domain name for this application in this environment. If you are only adding one application to this environment, you can leave the Domain Name blank (not set). You can also leave the name blank to make the environment answer requests for any domain.

If this is a multi-application environment, then specify domain name(s). Enter comma-separated values. Wildcards and regular expressions are allowed. This option informs Nginx as to how your URLs are constructed. For more information, see the Nginx wiki.


Select a region for your environment. Usually you want to select the geographical location closest to your app users.

Note: The region for an environment cannot be changed after the environment has been booted.

SSH Keys

Engine Yard provides you with full access to any of your instances; this means you can SSH in, check log files, and run any UNIX command directly on the instance. After you create your new environment, then you can add SSH keys for the environment (select the SSH Public Keys link in the Tools menu).

See Work with SSH (Secure Shells) for more information.

Database Backups

Select the frequency and number of database backups you want to keep for this environment. Database backups are dumps of the application’s database (for example, pg_dump or mysqldump). Database backup files can be used for selective or full data restores and for downloading locally. Data integrity is checked when backup files are written. See Back Up the Database.

  • Frequency of backups includes both backups and snapshots.

  • Number of backups to keep includes both scheduled backups and on-demand backups.

    Tip: You can set the number of snapshots (which includes database snapshots) under the Snapshots heading in the UI.


Select the number of and retention period for snapshots you want to keep for this environment. Snapshots are incremental backups of the /data and /db volumes on single, master, and utility instances, and are stored on S3 volumes in your Engine Yard account. Snapshots are fast and incremental but not a replacement for database backups because snapshots do not check data integrity. See Manage Snapshots.

  • Number of snapshots to keep, per instance.

    Note: This applies to each instance in an environment. For example, if you have 5 instances and set this number of snapshots to 10, then your environment will accumulate 5x10 snapshots.

  • Snapshot retention period in days, for this environment. Engine Yard will delete snapshots after the specified number of days for all snapshots related to any instances associated with this environment.

    Note: This setting takes precedence; once the retention period has passed, the snapshots get deleted, regardless of the number of snapshots.

  • Snapshot frequency is based on the frequency of backups.

    Tip: You can set the frequency of backups under the Backups heading in the UI.

If you have feedback or questions about this page, add a comment below. If you need help, submit a ticket with Engine Yard Support.


Article is closed for comments.