Managing and customizing Nginx

About Nginx

Applications 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.

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 passenger != true
  • if passenger != false
  • if passenger == true
  • if passenger == false

Bad syntax:

  • Bad: if passenger
  • Bad: if !passenger

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.

CategoryAttributeDefault value
worker_processesDynamically set based on instance size
gzip_proxiedexpired no-cache no-store private auth
gzip_typestext/plain application/xml text/css application/x-javascript text/javascript
gzip_disable"MSIE [1-6]."
listen80 default_server
server_name_ or SSL server name
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 NameTypeDescription
user_namestringUser name running the application process
environmentstringApplication environment name (lowercase)
server_addressstringServer address (IP or fqdn)
workersintegerNumber of CPU cores on the server
app_namestringApplication name (lowercase)
envarshashHash of all environment variables on the application
allow_sslbooleanIs an SSL Certificate configured for the application?
perfect_forward_secrecybooleanIs perfect forward secrecy enabled for the application?
cors_enabledbooleanIs CORS enabled for the application?
cors_originstringCORS Origins string
cors_originsarrayList of CORS origins
cors_all_originsbooleanCORS allow all origins
cors_methodsstringCORS Methods
cors_headersstringCORS allowed custom headers
cors_credentialsbooleanCORS allow credentials
has_ha_proxy_load_balancerbooleanAre you using a HAProxy load balancer?
load_balancer_addressstringAddress of your load balancer
red_http_to_httpsbooleanAre you redirecting HTTP to HTTPS?
red_wwwbooleanAre you redirecting traffic to www?
blacklisthashList of IPs you are blacklisting
supports_realip_modulebooleanDoes your Nginx instance use the Real IP module?
stack_supports_nginx_tcp_and_udp_reverse_proxybooleanDoes your application support TCP and UDP reverse proxy?
supports_tcp_proxybooleanDoes your NGINX version support TCP reverse proxy and load balancing?
supports_udp_proxybooleanDoes your NGINX version support UDP reverse proxy and load balancing?
has_load_balancerbooleanAre you using a load balancer?
service_containersarrayContains all services (with service_name and upstreams information)
service_namestringPart of the service_containers hiearchy, containing the name of a specific service
upstreamsarrayPart of the service_containers hiearchy, containing an upstream name, private IPs, traffic matches and port

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.

Customizing Nginx configurations

  1. Open the Application Overview from your Dashboard
  2. Click on ⚙️Application Settings in the right-hand panel
  3. Click on Configuration Files in the sub-nav that opens
  4. Click on the NGINX tab
  5. 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 application, one by one, sequentially:

  • Check your template for Liquid syntax errors
  • Count the number of cores on the server
  • Compile the Nginx configuration based on the information from the server
  • Upload the configuration to the server
  • Reload Nginx

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 application, if the first server fails to be updated, the process will be halted for the other 2 servers to avoid complete service disruption.

Review configs carefully

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

Working examples

Customizing the Nginx error page

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

  1. Using a static page on your own server
    • Make your custom error page (for example 50x/) 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/
    • Customize your Nginx configuration and replace the 50X/ location block with following:
    location = /50x/
        root /var/containers/;
  1. Using external static page
    • Upload your file to a server which is accessible from your server
    • Customize your Nginx configuration and replace the 50X/ location block with the following:
    location = /50x/
        proxy_pass {url-of-your-custom-page};

Enabling HTTP2

Nginx supports HTTP2 and this can be enabled on your application by editing your CustomConfig as follows:

Update the listen directive in the server block from this:

server {
        listen 443;
        ssl on; this:

server {
        listen 443 ssl http2;

Remove 'ssl on' directive

Be sure to remove the separate ssl on directive from the config, or it will not work.

Applying system upgrades