Make a custom 502 Bad Gateway page
Tags: laravel, nginx, html, tutorial
Published: 2023-08-15 15:36:36

How to display a more appealing `502` page instead of the default NGINX `502 Bad Gateway` page.

&nbsp; 
&nbsp; 

You can find a Laravel Project example on our [Github Repository](https://github.com/capsulescodes/articles).

&nbsp;
&nbsp;

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:

&nbsp; 

![Default 502 page screenshot](https://capsules.codes/storage/canvas/images/9erMI4iKy6AlGCjJoh04YcLme93roIiAelWndVZz.jpg)

&nbsp; 
&nbsp; 

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.

&nbsp; 
&nbsp; 

`/public/502.html`

```php
<!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">...</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>
```

&nbsp; 
&nbsp; 

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.

&nbsp;
&nbsp;

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

&nbsp;
&nbsp;

Using Laravel Valet :

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

```bash
error_page 502 /502.html;

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

&nbsp;
&nbsp;

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

&nbsp;
&nbsp;

Stop the php service to access the new `502` page.

```bash
valet restart

brew services stop php@8.1
```

&nbsp;
&nbsp;

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.

&nbsp;
&nbsp;

Using Forge :

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

```bash
error_page 502 /502.html;

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

![Laravel Forge Nginx Configuration screenshot](https://capsules.codes/storage/canvas/images/kOJubWMi7qvdCNsBH4W4LGKskgFlge9dX6p0kSnb.jpg)

&nbsp;
&nbsp;

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

```bash
sudo systemctl stop php8.1-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.

&nbsp;
&nbsp;

You can find a Laravel Project example on our [Github Repository](https://github.com/capsulescodes/articles)

&nbsp;
&nbsp;

Glad this helped.

&nbsp;
&nbsp;

Find out more on [Capsules](https://capsules.codes) or [X](https://x.com/capsulescodes)