Custom Error Page Settings via NGINX Balancer

When an error occurs within a particular environment (e.g. when trying to access non-existing page), a default error page for the server is opened. For example:

Tomcat default error page

You can substitute this error page with a custom one to provide end-users with more specific instructions and leave email to contact you. Below, we’ll show how to configure a custom error page using the NGINX load balancer added to your environment:

1. Go to your platform dashboard, find the NGINX load balancer in your environment and click the Config button next to it.

2. In the opened configuration manager tab navigate to the /etc/nginx/conf.d folder and create or upload your custom error page.

create custom error page

3. For this tutorial we’ll use the following error.html file:

example custom page

4. Then navigate to the /etc/nginx directory and copy content of the nginx-iNET.elastic.conf file and paste it into the nginx.conf, replacing the include /etc/nginx/nginx-iNET.elastic.conf; line (circled in the image below).

edit nginx.conf file

Now, you are able to specify all the required configurations.

5. Find the server section of the pasted configs and substitute the default error_page settings with the following strings:

1
2
error_page 403 404 500 502 503 504 /error.html;
proxy_intercept_errors on;

error page configurations

6. Next, scroll a little bit lower and adjust the error page parameters within location subsections:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
location /error.html {
    root   /etc/nginx/conf.d;
    internal;
}

location / {
    if ($cookie_SRVGROUP ~ group|common) {
        proxy_pass http://$cookie_SRVGROUP;
        error_page 403 404 500 502 503 504 = /error.html;
    }
    if ($cookie_SRVGROUP !~ group|common) {
        add_header Set-Cookie "SRVGROUP=$group; path=/";
    }
    proxy_pass http://default_upstream;
    add_header Set-Cookie "SRVGROUP=$group; path=/";
}

location @rescue {
    proxy_pass http://$cookie_SRVGROUP;
    error_page   500 502 503 504 = error.html;
}

location @recycle {
    proxy_pass http://default_upstream;
    add_header Set-Cookie "SRVGROUP=$group; path=/";
}

error page location settings

7. In case of using SSL for your website (i.e. for connections over HTTPS), some additional configurations are required (otherwise go to the 9th step of this guide). Add the following lines to the servers section of the /etc/nginx/conf.d/ssl.conf file:

1
2
3
4
proxy_intercept_errors on;
location /error.html {
                    root   /etc/nginx/conf.d;
 }

configure ssl.conf file

8. Also, you need to adjust the /etc/nginx/conf.d/ssl.upstreams.inc file. Find the next condition and change it as follows:

1
2
3
4
5
if ($cookie_SRVGROUP ~ group|common) {
                   proxy_pass http://$cookie_SRVGROUP;
                   error_page 403 404 /error.html;
                   error_page   500 502 503 504 = @resque;
}

adjust SSL upstreams file

9. Don’t forget to Restart NGINX server to apply all changes.

restart NGINX balancer nodes

10. That’s it! Try to access any non-existing page within your domain.

custom error page

Note: If the server with pre-configured custom error pages or the whole environment is not reachable, a platform-wide default error page will be displayed, e.g.:

PaaS default error page

You cannot modify such notifications for your environments.

Custom Error Page Settings via NGINX Balancer

What’s next?