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.


  • Avatar
    Permanently deleted user

    What are the log levels available?  I cannot find anything on the internet.

    Comment actions Permalink
  • Avatar
    Permanently deleted user

    It is just standard nginx configuration. You can find more details of their configuration on the wiki:


    Comment actions Permalink
  • Avatar
    Joshua Pinter

    Is there a way to install Nginx modules, such as the chunkin module (, as well?

    Comment actions Permalink
  • Avatar
    Permanently deleted user

    Hi Joshua,

    Good question - Nginx modules are compiled in at compile time, so it's a little tougher than on something like Apache.  However, you can always check what modules we compile in with nginx -V

    ~ # nginx -V

    nginx version: nginx/1.2.3

    TLS SNI support enabled

    configure arguments: --prefix=/usr --conf-path=/etc/nginx/nginx.conf --http-log-path=/var/log/nginx/access_log --error-log-path=/var/log/nginx/error_log --pid-path=/var/run/ --http-client-body-temp-path=/var/tmp/nginx/client --http-proxy-temp-path=/var/tmp/nginx/proxy --http-fastcgi-temp-path=/var/tmp/nginx/fastcgi --with-md5-asm --with-md5=/usr/include --with-sha1-asm --with-sha1=/usr/include --with-http_realip_module --with-http_flv_module --with-http_ssl_module --with-imap --with-http_perl_module --with-http_stub_status_module --with-http_dav_module --with-http_geoip_module --add-module=/var/tmp/portage/www-servers/nginx-1.2.3-r1/work/nginx_http_push_module-0.692 --add-module=/var/tmp/portage/www-servers/nginx-1.2.3-r1/work/redis2_nginx_module-v0.06 --add-module=/var/tmp/portage/www-servers/nginx-1.2.3-r1/work/nginx_upload_module-2.2.0 --add-module=/engineyard/portage/engineyard/www-servers/nginx/files/nginx-accesskey-2.0.3 --with-http_gzip_static_module --add-module=/var/tmp/portage/www-servers/nginx-1.2.3-r1/work/nginx_headers_more_module-v0.14rc1 --add-module=/engineyard/portage/engineyard/www-servers/nginx/files/mod-read-cookies-0.1 --add-module=/var/tmp/portage/www-servers/nginx-1.2.3-r1/work/nginx_uploadprogress_module-0.8.4 --add-module=/var/tmp/portage/www-servers/nginx-1.2.3-r1/work/nginx_tcp_proxy_module_20120827ey --add-module=/var/tmp/portage/www-servers/nginx-1.2.3-r1/work/passenger-3.0.11/ext/nginx

    If you do want to have a special module included, drop us a feature request and we'll consider including it or may be able to provide you with a special ebuild that will include it.


    Comment actions Permalink
  • Avatar
    Joshua Pinter

    Thanks John. I've created a ticket to add the chunkin module that we need for large POST requests to the server.

    Comment actions Permalink

Please sign in to leave a comment.

Powered by Zendesk