How to configure Nginx

About Nginx

Stacks deployed with Cloud 66 use Nginx as their web server, and its configuration is dependant on the resources of your server(s). Nginx is a high performance, open source web server used by some of the biggest web services in the world.

Nginx configuration

The following table outlines the default configuration of Nginx.

Category
 Attribute Default value
General -
user nginx
worker_processes Dynamically set based on instance size
error_log /var/deploy/[stack_name]/web_head/shared/log/nginx_error.log
Events -
worker_connections 1024
HTTP -
gzip on
gzip_min_length 100
gzip_proxied expired no-cache no-store private auth
gzip_types text/plain application/xml text/css application/x-javascript text/javascript
gzip_disable "MSIE [1-6]\."
passenger_root [passenger location]
passenger_ruby [stack ruby shell]
passenger_ruby nginx
passenger_pool_idle_time 0
passenger_max_pool_size 15
ssl_session_cache shared:SSL:10m
ssl_session_timeout 10m
underscores_in_headers on
default_type application/octet-stream
client_max_body_size 50m
sendfile on
server_tokens off
keepalive_timeout 65
Server -
listen 80 default_server
server_name _ or SSL server name
rails_env [stack environment]
client_max_body_size 50m
root /var/deploy/[stack name]/web_head/current/public
passenger_enabled on
ssl_certificate_key /etc/ssl/localcerts/[ssl cerificate file name].key
ssl_certificate /etc/ssl/localcerts/[ssl cerificate file name].crt

Nginx worker configuration

The following table specifies the number of workers configured for your Nginx based on the server resources (CPU cores) on each cloud.

Cloud provider
 Instance type Number of Workers
AWS -
t1.micro 1
m1.small 1
m1.medium 2
m1.large 2
m1.xlarge 4
m3.medium 1
m3.large 2
m3.xlarge 4
m3.2xlarge 8
m2.xlarge 2
m2.2xlarge 4
m2.4xlarge 8
c1.medium 2
c1.xlarge 8
c3.large 2
c3.xlarge 4
c3.2xlarge 8
c3.4xlarge 16
c3.8xlarge 32
cc2.8xlarge 88
i2.xlarge 4
i2.2xlarge 8
i2.4xlarge 16
i2.8xlarge 32
cr1.8xlarge 88
hi1.4xlarge 35
hs1.8xlarge 35
cg1.4xlarge 33
g2.2xlarge 8
DigitalOcean -
512MB - 1 CPU 1
1GB - 1 CPU 1
2GB - 2 CPU 2
4GB - 2 CPU 2
8GB - 4 CPU 4
16GB - 8 CPU 8
32GB - 12 CPU 12
48GB - 16 CPU 16
64GB - 20 CPU 20
96GB - 24 CPU 24
GCE -
n1-standard-1 1
n1-standard-2 2
n1-standard-4 4
n1-standard-8 8
n1-standard-16 16
n1-highmem-2 2
n1-highmem-4 4
n1-highmem-8 8
n1-highmem-16 16
n1-highcpu-2 2
n1-highcpu-4 4
n1-highcpu-8 8
n1-highcpu-16 16
f1-micro 1
g1-small 1
Linode -
Linode 1GB 1
Linode 2GB 2
Linode 4GB 4
Linode 8GB 6
Linode 16GB 8
Linode 32GB 12
Linode 48GB 16
Linode 64GB 20
Linode 96GB 20
Microsoft Azure -
ExtraSmall 1
Small 1
Medium 2
Large 4
ExtraLarge 8
A5 2
A6 4
A7 8
A8 8
A9 16
STANDARD_D1 1
STANDARD_D2 2
STANDARD_D3 4
STANDARD_D4 8
STANDARD_D11 2
STANDARD_D12 4
STANDARD_D13 8
STANDARD_D14 16
Rackspace -
512MB Standard Instance 1
1GB Standard Instance 1
2GB Standard Instance 2
4GB Standard Instance 2
8GB Standard Instance 4
15GB Standard Instance 6
30GB Standard Instance 8
3.75 GB Compute v1 2
7.5 GB Compute v1 4
15 GB Compute v1 8
30 GB Compute v1 16
60 GB Compute v1 32
1 GB General Purpose v1 1
2 GB General Purpose v1 2
4 GB General Purpose v1 4
8 GB General Purpose v1 8
15 GB I/O v1 4
30 GB I/O v1 8
60 GB I/O v1 16
90 GB I/O v1 24
120 GB I/O v1 32
15 GB Memory v1 2
30 GB Memory v1 4
60 GB Memory v1 8
120 GB Memory v1 16
240 GB Memory v1 32
1 GB Performance 2
2 GB Performance 2
4 GB Performance 4
8 GB Performance 8
15 GB Performance 4
30 GB Performance 8
60 GB Performance 16
90 GB Performance 24
120 GB Performance 32
CloudA -
512 MB 1
1 GB 1
2 GB 1
4 GB 2
8 GB 4
16 GB 6
32 GB 8
8 GB - HM 2
16 GB - HM 4
32 GB - HM 6
4 GB - HC 4
8 GB - HC 8
16 GB - HC 12

Default Cloud 66 Nginx error page

When there is a problem with your upstream server (ie. a container), requests will be passed to the default Cloud 66 error page. From there, you can visit the problematic server page in Cloud 66 dashboard to troubleshoot.

Custom Nginx error page

There are two ways for you to create a custom Nginx 50X error page:

  1. Using a static page on you own server
    • For Docker stacks, make your custom error page (for example 50x.html) available in your container (for example in /usr/app), and simply mount this folder to the host (for example with /var/containers:/usr/app). The path used in the next step would then be /var/containers/50x.html

    • Customize your Nginx configuration and replace the 50X.html location block with following:

      location = /50x.html { root /var/containers/; }

  2. Using external static page
    • Upload your file to a server which is accessible from your server

    • Customize your Nginx configuration and replace the 50X.html location block with following:

      location = /50x.html { proxy_pass {url-of-your-custom-page}; }

Customize your Nginx configuration

Cloud 66 makes it easy for you to customize your Nginx configuration. From your stack detail page, access your web server group page (eg. Rails server) and click Customize Nginx in the right sidebar. Follow the CustomConfig instructions to customize the configuration.

Editing and committing your Nginx CustomConfig will perform the following steps on every web server in your stack, one by one, sequentially:

Reloading Nginx does not interrupt the serving of traffic. This process will be stopped if an error is encountered. For example, if you have 3 web servers in your stack, if the first server fails to be updated, the process will be halted for the other 2 servers to avoid complete service diruption.

Warning

A bad configuration may stop your Nginx from functioning, so take extra care when making changes.

Nginx CustomConfig variables

The following variables are available for use in your Docker stack Nginx CustomConfig.

Variable Name Type Description
user_name string User name running the application process
environment string Stack environment name (lowercase)
server_address string Server address (IP or fqdn)
workers integer Number of CPU cores on the server
app_name string Stack name (lowercase)
envars hash Hash of all environment variables on the stack
allow_ssl boolean Is an SSL Certificate configured on the stack?
perfect_forward_secrecy boolean Is perfect forward secrecy enabled on the stack?
cors_enabled boolean Is CORS enabled on the stack?
cors_origin string CORS Origins string
cors_origins array List of CORS origins
cors_all_origins boolean CORS allow all origins
cors_methods string CORS Methods
cors_headers string CORS allowed custom headers
cors_credentials boolean CORS allow credentials
has_ha_proxy_load_balancer boolean Are you using a HAProxy load balancer?
load_balancer_address string Address of your load balancer
red_http_to_https boolean Are you redirecting HTTP to HTTPS?
red_www boolean Are you redirecting traffic to www?
blacklist hash List of IPs you are blacklisting
supports_realip_module boolean Does your Nginx instance use the Real IP module?
stack_supports_nginx_tcp_and_udp_reverse_proxy boolean Does your stack support TCP and UDP reverse proxy?
supports_tcp_proxy boolean Does your NGINX version support TCP reverse proxy and load balancing?
supports_udp_proxy boolean Does your NGINX version support UDP reverse proxy and load balancing?
has_load_balancer boolean Are you using a load balancer?
service_containers array Contains all services (with service_name and upstreams information)
service_name string Part of the service_containers hiearchy, containing the name of a specific service
upstreams array Part of the service_containers hiearchy, containing an upstream name, private IPs, traffic matches and port

Boolean variables

To ensure correct boolean condition checks within your template, always explicitly compare the variable with true or false (even if you are checking for true).

Good syntax:

Bad syntax:

Variable Name Type Description
passenger boolean Is nginx running Passenger or a custom web server?
passenger_supports_cgi_param boolean Does the current Passenger version support CGI param?
passenger_enterprise boolean Are you using Passenger enterprise?
user_name string User name running the application process
environment string Stack environment name (lowercase)
server_address string Server address (IP or fqdn)
workers integer Number of CPU cores on the server
passenger_pool_max integer Size of the passenger pool (Passenger Only)
use_ruby_shell boolean Used internally
ruby_shell string /var/deploy/ruby_shell
app_name string Stack name (lowercase)
deploy_to string Stack path on the server
envars hash Hash of all environment variables on the stack
envars hash Hash of all environment variables on the stack
passenger_location string Passenger location (Passenger only)
allow_ssl boolean Is an SSL Certificate configured on the stack?
perfect_forward_secrecy boolean Is perfect forward secrecy enabled on the stack?
cors_enabled boolean Is CORS enabled on the stack?
cors_origin string CORS Origins string
cors_origins array List of CORS origins
cors_all_origins boolean CORS allow all origins
cors_methods string CORS Methods
cors_headers string CORS allowed custom headers
cors_credentials boolean CORS allow credentials
has_ha_proxy_load_balancer boolean Are you using a HAProxy load balancer?
load_balancer_address string Address of your load balancer
red_http_to_https boolean Are you redirecting HTTP to HTTPS?
red_www boolean Are you redirecting traffic to www?
blacklist hash List of IPs you are blacklisting
supports_realip_module boolean Does your Nginx instance use the Real IP module?
has_load_balancer boolean Are you using a load balancer?
Need help with deployments?
Contact Support
More Questions?
Join the Slack Channel