Capsules Codes - Make a custom 502 Bad Gateway page

TL;DR: How to display a more appealing 502 page instead of the default NGINX 502 Bad Gateway page.

You will find the source code via this Github Repository. Learn more on Capsules or X.

It can happen that calling a URL returns a 502 page. The 502 Bad Gateway HTTP server error response code indicates that the server, acting as a gateway or proxy, received an invalid response from the upstream server. The server then decides to return a default page:

To enhance the look of this page, we need to instruct NGINX that we want to display a custom page, avoiding the one provided by default. So, a new HTML file needs to be created.

/public/502.html

<!DOCTYPE html>

<html>
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">
        <script src="<https://cdn.tailwindcss.com>"></script>
    </head>

    <body>

        <div class="h-screen w-screen flex flex-col items-center justify-center">

            <div class="flex flex-col sm:flex-row items-center sm:items-start justify-center">

                <div class="w-16 h-16" >

                    <svg viewBox="0 0 322 322">

                        <g>
                            <path style="fill: #E6F1FF" d="M60.8,157.5c0,20.9,16.9,37.8,37.8,37.8s37.8-16.9,37.8-37.8V99.7c0-20.9-16.9-37.8-37.8-37.8 S60.8,78.8,60.8,99.7C60.8,99.7,60.8,157.5,60.8,157.5z"/>
                            <path style="fill: #F3F8FF" d="M98.9,80.7c-11.1,0-20.1,9-20.1,20.1v48c0,11.1,9,20.1,20.1,20.1s20.1-9,20.1-20.1v-48 C119.1,89.7,110,80.7,98.9,80.7z"/>
                            <path style="fill: #DD3773" d="M154.9,164.9c0-6.6-4.4-12.8-11-15.6c-5.3-2.2-11.2-1.7-15.9,1.4c-0.7-0.1-2.1-0.3-4.7-1.3 c-3.6-1.6-6.6-3.3-9.2-5.2c-0.1,0-0.1-0.1-0.2-0.2l-1.7-1.3c-0.8-0.6-1.6-1.2-2.2-1.7c-3.1-2.5-6.4-5-10.5-7.2 c-13.9-7.4-29-7.4-40.5-0.2c-5.4,3.4-9.6,8.1-12.2,13.5c-2.4,5-3.5,10.4-3.5,16.3v45.3c0,11.4,3.2,22,9.5,31.5 C60.3,251.6,72,260,85,263.4c4.5,1.2,9.2,1.8,13.9,1.8c8.8,0,17.7-2.1,25.6-6.2c12.3-6.3,21.7-16.8,26.6-29.6 c3.6-9.5,4-18.6,4-25.6L154.9,164.9z"/>
                            <path style="fill: #2E3A56" d="M98.9,56.7c-23.7,0-43,19.5-43,43.4v55.5c0,24,19.3,43.4,43,43.4s43-19.5,43-43.4v-55.5 C141.9,76.2,122.6,56.7,98.9,56.7z M127.7,155.7c0,16.1-12.9,29.2-28.7,29.2s-28.7-13.1-28.7-29.2v-55.5C70.3,84.1,83.2,71,99,71 s28.7,13.1,28.7,29.2V155.7z"/>
                            <path style="fill: #DD3773" d="M141.1,201.2c0-6.2,0-30.9,0-37.1c0-3.2-4.1-4.9-6.3-2.6c-0.1,0.1-0.1,0.1-0.1,0.1c-0.1,0-0.1,0.1-0.3,0.1 c-1.1,0.6-1.4,0.8-2.9,1.1c-4.5,1-9.2-0.4-13.3-2c-4.3-1.9-22-14.5-25.1-16.1c-8.4-4.5-18.9-6-27.3-0.7c-3.1,2-5.7,4.7-7.3,8 c-1.7,3.6-1.6,7.3-1.6,11.2c0,8.6,0,35.8,0,44.4c0,8.6,1.9,17,6.7,24.3c5.7,8.6,14.5,15.1,24.5,17.7c20.9,5.4,42.9-5.8,50.5-26 C141.4,216.4,141.1,208.8,141.1,201.2z M105.8,153.8c-0.4-0.3-0.1-0.1,0.1,0.1C105.9,153.8,105.9,153.8,105.8,153.8z"/>
                            <path style="fill: #CC296B" d="M134,159.4c-5,0.2-9.3,4.1-9.3,9.3c0,10.6,0,21.3,0,31.9c0,4.1,0.2,8.2-0.1,12.2c0-0.8-0.4,2.1-0.5,2.6 c-0.3,1.1-0.6,2.2-0.9,3.3c-0.1,0.3-0.4,1.1-0.4,1.2c-0.1,0.3-0.3,0.6-0.4,0.8c-0.6,1.1-1.2,2.2-1.8,3.3c-0.4,0.6-0.8,1.2-1.2,1.7 c0.2-0.3,1.1-1.3-0.1,0.1c-0.7,0.8-1.4,1.7-2.2,2.4c-0.8,0.7-1.5,1.5-2.4,2.1c-0.1,0.1-0.1,0.1-0.2,0.1c-0.7,0.5-1.4,0.9-2.1,1.4 c-0.9,0.6-1.9,1.1-2.9,1.6c-0.1,0-0.2,0.1-0.2,0.1c-0.5,0.2-0.9,0.4-1.4,0.5c-1.2,0.4-2.4,0.7-3.7,1c-0.1,0-0.5,0.1-0.8,0.2 c-0.3,0-0.7,0.1-0.9,0.1c-5.2,0.2-7.6,0.1-12.3-1.3c-0.6-0.2-1.2-0.4-1.8-0.6c-0.1,0-0.7-0.3-0.9-0.3c-1-0.5-1.9-1-2.8-1.5 c-0.4-0.2-0.8-0.5-1.2-0.8c-0.2-0.1-0.6-0.5-0.7-0.5c-1.1-1.1-2.3-2.2-3.3-3.3c-3.3-3.4-5.2-6.5-6.4-11.1 c-0.2-0.6-0.3-1.2-0.4-1.8c0-0.2-0.1-0.3-0.1-0.4c-0.1-1-0.2-1.9-0.2-2.9c0-0.7,0-1.4,0-2.1c0-1.2,0-2.3,0-3.5 c0-5.8,0-11.5,0-17.3c0-11.5,0-22.9,0-34.4c0-4.9-4.3-9.5-9.3-9.3s-9.3,4.1-9.3,9.3c0,10.7,0,21.3,0,32c0,6.3,0,12.7,0,19 c0,5.2,0,10.3,1.1,15.5c2.7,12,12.1,23.9,23.2,29.2c10.4,4.9,23.1,6.5,34.2,3c11.2-3.6,21-11.8,26.2-22.4 c3.5-7.3,4.8-14.9,4.8-22.9c0-12.7,0-25.4,0-38.1C143.3,163.8,139,159.2,134,159.4z M109.1,233.7 C108.4,234,108.7,233.8,109.1,233.7L109.1,233.7z M114.7,230.3C115.5,229.6,115.1,230,114.7,230.3L114.7,230.3z"/>
                            <path style="fill: #F3F8FF" d="M129.3,201.7c-0.3-2.5-2.6-4.4-5.2-4.1c-2.5,0.3-4.4,2.6-4.1,5.2c1,8.5-1.2,16.4-6,21.7 c-4.1,4.4-9.6,6.5-16.1,6.2c-2.6-0.1-4.7,1.9-4.9,4.4c-0.1,2.6,1.9,4.7,4.4,4.9c0.5,0,1,0,1.6,0c8.5,0,16.2-3.2,21.8-9.2 C127.6,223.6,130.7,213,129.3,201.7z"/>
                            <path style="fill: #2E3A56" d="M146.6,203.9v-38c0-3.9-2.4-7.5-6-9c-3.4-1.4-7.3-0.9-10.1,1.5c-0.1,0.1-0.3,0.1-0.3,0.2c0,0-0.1,0-0.6,0.1 c-2.8,0.6-6.4-0.5-9.3-1.7c-2.2-1-10-6.3-14.8-9.5c-5-3.4-7.9-5.3-9.4-6.1c-11.5-6.1-23.8-6.3-33.1-0.4c-4.2,2.7-7.5,6.3-9.5,10.5 c-2.2,4.7-2.2,9.2-2.2,13.2v44.2c0,10.5,2.6,19.6,7.6,27.3c6.5,9.8,16.6,17.1,27.7,20c3.9,1,8,1.5,12,1.5c7.6,0,15.2-1.8,22.1-5.4 c10.6-5.4,18.7-14.5,22.9-25.5C146.6,218.9,146.6,211.2,146.6,203.9z M132.1,222.3c-6.3,16.7-24.9,26.2-42.3,21.7 c-8.2-2.1-15.7-7.5-20.5-14.8c-3.7-5.6-5.6-12.5-5.6-20.5v-44.2c0-3.2,0-5.7,1-7.9c1-2,2.7-3.9,4.9-5.3c2.5-1.6,5.5-2.4,8.7-2.4 c3.8,0,7.9,1.1,11.9,3.2c0.9,0.5,5,3.2,8.3,5.4c8.3,5.6,13.9,9.3,16.7,10.6l0.3,0.1c3.6,1.4,8,2.8,12.7,2.8 c2.3,0.3,5.8,1.5,5.9,6.3v24.9v1.5C134.3,210.4,134.3,216.6,132.1,222.3z"/>
                        </g>
                        <g>
                            <path style="fill: #E6F1FF" d="M261,164.5c0-20.9-16.9-37.8-37.8-37.8s-37.8,16.9-37.8,37.8v57.8c0,20.9,16.9,37.8,37.8,37.8 s37.8-16.9,37.8-37.8V164.5z"/>
                            <path style="fill: #F3F8FF" d="M222.9,241.3c11.1,0,20.1-9,20.1-20.1v-48c0-11.1-9-20.1-20.1-20.1s-20.1,9-20.1,20.1v48 C202.8,232.3,211.8,241.3,222.9,241.3z"/>
                            <path style="fill: #33E5E1" d="M167,157.2c0,6.6,4.4,12.8,11,15.6c5.3,2.2,11.2,1.7,15.9-1.4c0.7,0.1,2.1,0.3,4.7,1.3 c3.6,1.6,6.6,3.3,9.2,5.2c0.1,0,0.1,0.1,0.2,0.2l1.7,1.3c0.8,0.6,1.6,1.2,2.2,1.7c3.1,2.5,6.4,5,10.5,7.2 c13.9,7.4,29,7.4,40.5,0.2c5.4-3.4,9.6-8.1,12.2-13.5c2.4-5,3.5-10.4,3.5-16.3v-45.3c0-11.4-3.2-22-9.5-31.5 c-7.5-11.4-19.2-19.8-32.2-23.2c-4.5-1.2-9.2-1.8-13.9-1.8c-8.8,0-17.7,2.1-25.6,6.2c-12.3,6.3-21.7,16.8-26.6,29.6 c-3.6,9.5-4,18.6-4,25.6L167,157.2z"/>
                            <path style="fill: #2E3A56" d="M222.9,265.3c23.7,0,43-19.5,43-43.4v-55.5c0-24-19.3-43.4-43-43.4s-43,19.5-43,43.4v55.5 C179.9,245.8,199.2,265.3,222.9,265.3z M194.2,166.3c0-16.1,12.9-29.2,28.7-29.2c15.8,0,28.7,13.1,28.7,29.2v55.5 c0,16.1-12.9,29.2-28.7,29.2c-15.8,0-28.7-13.1-28.7-29.2L194.2,166.3L194.2,166.3z"/>
                            <path style="fill: #33E5E1" d="M180.7,120.8c0,6.2,0,30.9,0,37.1c0,3.2,4.1,4.9,6.3,2.6c0.1-0.1,0.1-0.1,0.1-0.1c0.1,0,0.1-0.1,0.3-0.1 c1.1-0.6,1.4-0.8,2.9-1.1c4.5-1,9.2,0.4,13.3,2c4.3,1.9,22,14.5,25.1,16.1c8.4,4.5,18.9,6,27.3,0.7c3.1-2,5.7-4.7,7.3-8 c1.7-3.6,1.6-7.3,1.6-11.2c0-8.6,0-35.8,0-44.4c0-8.6-1.9-17-6.7-24.3c-5.7-8.6-14.5-15.1-24.5-17.7c-20.9-5.4-42.9,5.8-50.5,26 C180.5,105.6,180.7,113.2,180.7,120.8z M216,168.3c0.4,0.3,0.1,0.1-0.1-0.1C215.9,168.2,216,168.2,216,168.3z"/>
                            <path style="fill: #32C9CB" d="M187.8,162.6c5-0.2,9.3-4.1,9.3-9.3c0-10.6,0-21.3,0-31.9c0-4.1-0.2-8.2,0.1-12.2c0,0.8,0.4-2.1,0.5-2.6 c0.3-1.1,0.6-2.2,0.9-3.3c0.1-0.3,0.4-1.1,0.4-1.2c0.1-0.3,0.3-0.6,0.4-0.8c0.6-1.1,1.2-2.2,1.8-3.3c0.4-0.6,0.8-1.2,1.2-1.7 c-0.2,0.3-1.1,1.3,0.1-0.1c0.7-0.8,1.4-1.7,2.2-2.4c0.8-0.7,1.5-1.5,2.4-2.1c0.1-0.1,0.1-0.1,0.2-0.1c0.7-0.5,1.4-0.9,2.1-1.4 c0.9-0.6,1.9-1.1,2.9-1.6c0.1,0,0.2-0.1,0.2-0.1c0.5-0.2,0.9-0.4,1.4-0.5c1.2-0.4,2.4-0.7,3.7-1c0.1,0,0.5-0.1,0.8-0.2 c0.3,0,0.7-0.1,0.9-0.1c5.2-0.2,7.6-0.1,12.3,1.3c0.6,0.2,1.2,0.4,1.8,0.6c0.1,0,0.7,0.3,0.9,0.3c1,0.5,1.9,1,2.8,1.5 c0.4,0.2,0.8,0.5,1.2,0.8c0.2,0.1,0.6,0.5,0.7,0.5c1.1,1.1,2.3,2.2,3.3,3.3c3.3,3.4,5.2,6.5,6.4,11.1c0.2,0.6,0.3,1.2,0.4,1.8 c0,0.2,0.1,0.3,0.1,0.4c0.1,1,0.2,1.9,0.2,2.9c0,0.7,0,1.4,0,2.1c0,1.2,0,2.3,0,3.5c0,5.8,0,11.5,0,17.3c0,11.5,0,22.9,0,34.4 c0,4.9,4.3,9.5,9.3,9.3c5-0.2,9.3-4.1,9.3-9.3c0-10.7,0-21.3,0-32c0-6.3,0-12.7,0-19c0-5.2,0-10.3-1.1-15.5 c-2.7-12-12.1-23.9-23.2-29.2c-10.4-4.9-23.1-6.5-34.2-3c-11.2,3.6-21,11.8-26.2,22.4c-3.5,7.3-4.8,14.9-4.8,22.9 c0,12.7,0,25.4,0,38.1C178.5,158.2,182.8,162.9,187.8,162.6z M212.8,88.4C213.4,88,213.1,88.2,212.8,88.4L212.8,88.4z M207.1,91.7 C206.3,92.4,206.8,92,207.1,91.7L207.1,91.7z"/>
                            <path style="fill: #F3F8FF" d="M192.5,120.3c0.3,2.5,2.6,4.4,5.2,4.1c2.5-0.3,4.4-2.6,4.1-5.2c-1-8.5,1.2-16.4,6-21.7 c4.1-4.4,9.6-6.5,16.1-6.2c2.6,0.1,4.7-1.9,4.9-4.4c0.1-2.6-1.9-4.7-4.4-4.9c-0.5,0-1,0-1.6,0c-8.5,0-16.2,3.2-21.8,9.2 C194.2,98.4,191.2,109,192.5,120.3z"/>
                            <path style="fill: #2E3A56" d="M175.2,118.2v38c0,3.9,2.4,7.5,6,9c3.4,1.4,7.3,0.9,10.1-1.5c0.1-0.1,0.3-0.1,0.3-0.2c0,0,0.1,0,0.6-0.1 c2.8-0.6,6.4,0.5,9.3,1.7c2.2,1,10,6.3,14.8,9.5c5,3.4,7.9,5.3,9.4,6.1c11.5,6.1,23.8,6.3,33.1,0.4c4.2-2.7,7.5-6.3,9.5-10.5 c2.2-4.7,2.2-9.2,2.2-13.2v-44.2c0-10.5-2.6-19.6-7.6-27.3c-6.5-9.8-16.6-17.1-27.7-20c-3.9-1-8-1.5-12-1.5 c-7.6,0-15.2,1.8-22.1,5.4c-10.6,5.4-18.7,14.5-22.9,25.5C175.2,103.1,175.2,110.8,175.2,118.2z M189.7,99.8 c6.3-16.7,24.9-26.2,42.3-21.7c8.2,2.1,15.7,7.5,20.5,14.8c3.7,5.6,5.6,12.5,5.6,20.5v44.2c0,3.2,0,5.7-1,7.9 c-1,2-2.7,3.9-4.9,5.3c-2.5,1.6-5.5,2.4-8.7,2.4c-3.8,0-7.9-1.1-11.9-3.2c-0.9-0.5-5-3.2-8.3-5.4c-8.3-5.6-13.9-9.3-16.7-10.6 l-0.3-0.1c-3.6-1.4-8-2.8-12.7-2.8c-2.3-0.3-5.8-1.5-5.9-6.3v-24.9v-1.5C187.6,111.6,187.6,105.4,189.7,99.8z"/>
                        </g>

                    </svg>

                </div>

                <div class="px-10 sm:px-4 h-full flex flex-col items-center sm:items-start text-center sm:text-left justify-center">

                    <h1 class="m-0 font-mono text-lg font-normal text-[#32e5e1]">502 - Internet Broken</h1>

                    <p class="m-0 font-mono text-xs text-sky-900">Whoops, it seems the interwebs are in a bad mood. Please check back soon.</p>

                </div>

            </div>

        </div>

    </body>
  
</html>

This HTML page reproduces the redesigned article image. It is static, and it is recommended to be light. The images are in SVG format, and there is no localization management. The set language is English. Some usage of the TailwindCSS CDN is included to enhance code understanding.

To reproduce the NGINX error and display the custom page, a few lines need to be added to the NGINX configuration.

Using Laravel Valet :

/opt/homebrew/etc/nginx/valet/valet.conf

error_page 502 /502.html;

    location = /502.html {
        root /path/to/your/project/public/folder/where/the/file/is;
        internal;
    }

It's crucial to note that these lines should be added at the bottom of the server section.

Stop the php service to access the new 502 page.

valet restart

brew services stop php@8.2

This is solely for the purpose of a local testing phase. The lines added to the NGINX Valet configuration file will then need to be removed. However, these lines can be permanently added to the NGINX configuration file associated with the project, if one exists.

Using Forge :

Add these lines to the NGINX configuration file of the site in the server 443 section :

error_page 502 /502.html;

    location = /502.html {
        root /home/forge/path/to/your/project/public/folder/where/the/file/is;
        internal;
    }

Stop the php service on the dedicated server and access the new 502 page :

sudo systemctl stop php8.2-fpm.service

The command systemctl status allows you to check the status of the service. The command systemctl start allows you to restart the service.

Glad this helped.