Customize Nginx

You might need to customize the default Nginx configuration. This page describes the layout of our Nginx configuration files and lists the files that are not altered by Chef on subsequent runs. These non-altered (customizable) files are straightforward to customize.

You can also customize Nginx with custom Chef recipes and with keep files; however, this is more difficult.

Note: If you need to create new customized instances that cannot be based on data volume snapshots of existing customized instances, then you must use custom Chef recipes for your Nginx configuration; cf. Apply Nginx customizations to new or rebuilt instances.

Customizable files

These are the files that you can edit without writing a custom Chef recipe or using keep-files:

Note: /etc/nginx is a symbolic link to /data/nginx on each instance.

  • /etc/nginx/http-custom.conf - Use this file to add configurations that need to go inside the http context, for example, configuring the Nginx proxy_cache_path directive.

  • /etc/nginx/servers/app_name/custom.conf - Use this file to add configurations inside the server context of app_name. This file is commonly used for rewrites.

  • /etc/nginx/servers/app_name/custom.ssl.conf - Use this file to add configurations inside the server context of app_name that only apply when the request comes in over HTTPS. This file does not exist if SSL is not enabled for your application.

  • /etc/nginx/servers/app_name.rewrites - This file is only used by (deprecated) Mongrel. Both HTTP and HTTPS requests can be affected by the rewrites in this file.

  • /etc/nginx/servers/default.conf - This file ensures that Nginx starts. We recommend that you leave it empty.

Apply Nginx customizations to your environment

After you edit customizable files, make sure to reload Ngnix in your environment so that your customizations take effect.

To apply your Nginx customizations to your environment

  1. Via SSH, connect to the application master instance and edit one or more of the files listed above.

  2. If you have a clustered environment with one or more application-slave instances, make the same edits on the slave instances (or copy the edited files from the application master instance).

  3. Load new the Ngnix configuration files by doing one of the following:
    • In the UI, click Apply.

    • Use the CLI interface (on your local machine), type this engineyard gem command:

      ey ssh "sudo /etc/init.d/nginx reload" -e environment_name --app-servers 

Apply Nginx customizations to other environments or instances

Use a recent snapshot to copy your Nginx customizations from one environment or application instance to another.

Important! Because these customizable files are not managed by Chef, if you rebuild your environment or add an application instance from a fresh data volume (instead of a snapshot), your Nginx customizations are lost.

To apply your Nginx customizations to another environment or instance

  1. If you don’t take a recent snapshot available, take a snapshot of the environment.

  2. If you are creating an environment, clone the environment from the already customized environment.


    If you are rebuilding the environment or adding an application slave to the existing environment, use the recent snapshot when rebuilding.

More information

For more information about... See...
SSHing into an instance                                                               Connect to your instance via SSH.                                                           
the engineyard gem Engine Yard CLI User Guide.
about environments About environments.
cloning an environment Clone an environment.
adding MIME types Add MIME Types to Nginx.

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.