Nginx options and variables
About Nginx
Applications deployed with Maestro 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.
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.
You can customise this page by following this guide.
Default 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/[app_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]\." | |
| 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 | |
| client_max_body_size | 50m | |
| root | /var/deploy/[application name]/web_head/current/public | |
| ssl_certificate_key | /etc/ssl/localcerts/[ssl cerificate file name].key | |
| ssl_certificate | /etc/ssl/localcerts/[ssl cerificate file name].crt |
Nginx CustomConfig variables
The following variables are available for use in your Nginx CustomConfig.
| Variable Name | Type | Description |
|---|---|---|
| user_name | string | User name running the application process |
| environment | string | Application environment name (lowercase) |
| server_address | string | Server address (IP or fqdn) |
| workers | integer | Number of CPU cores on the server |
| app_name | string | Application name (lowercase) |
| envars | hash | Hash of all environment variables on the application |
| allow_ssl | boolean | Is an SSL Certificate configured for the application? |
| perfect_forward_secrecy | boolean | Is perfect forward secrecy enabled for the application? |
| cors_enabled | boolean | Is CORS enabled for the application? |
| 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 application 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:
- if cors_enabled != true
- if cors_enabled != false
- if cors_enabled == true
- if cors_enabled == false
Bad syntax:
- Bad: if cors_enabled
- Bad: if !cors_enabled
| 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 | Application 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 |
| allow_ssl | boolean | Is an SSL Certificate configured on the application? |
| perfect_forward_secrecy | boolean | Is perfect forward secrecy enabled on the application? |
| cors_enabled | boolean | Is CORS enabled on the application? |
| 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? |
Nginx worker configuration
Nginx now supports autodetection of CPU cores (and other system resources) so there is no need to configure your worker processes differently depending on your cloud.
