Customizing your Nginx configuration

Overview

Applications deployed with Maestro use Nginx as their web and reverse proxy server. You can customize the default configuration of Nginx to suit your needs.

Customize 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.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 the following:

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

Customize your Nginx configuration

  1. Open the application overview page from your Dashboard
  2. Click on Configuration files in the Application panel on the right of the screen.
  3. Click on the NGINX tab at the top of the main panel
  4. 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:

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.

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 Maestro 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 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?
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:

Bad syntax:

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)
deploy_to string Application path on the server
envars hash Hash of all environment variables on the application
envars hash Hash of all environment variables on the application
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?