Home / server / Questions / 310819
Accepted
NeDark
Asked: 2011-09-14 02:49:26 +0800 CST

Maintenance page on nginx, best practices

  • 772

I want to configure the server to show a maintenance page when it exist. I tried this code and works:

location / {
    try_files /maintenance.html $uri $uri/ @codeigniter;
}

But I noticed it would be served with a 200 status code, and it can cause confusion to search engines. I think the best practice would be returning a 503 status code. On google I find several relevant pages about it, like this. However, they use if to make the redirect and according to nginx documentation it isn't safe to use ifs.

Is there a way of doing it without using if? Is safe to use if in this case?

Thanks.

nginx maintenance best-practices

4 Answers

  1. Here is what I do.

                if (-f $document_root/maintenance.html) {
                    return 503;
            }
            error_page 503 @maintenance;
            location @maintenance {
                    rewrite ^(.*)$ /maintenance.html break;
            }

    If the file is there it will show the maintenance page. Once you remove the file you will go back to normal.

    • 31
  2. Best Answer

    I think the best practice would be returning a 500 status code.

    I think you mean 503 instead of 500.

    they use if to make the redirect and according to nginx documentation it isn't safe to use ifs.

    No. Only return is 100% safe inside if in location context.

    According to nginx documentation, you can specify an HTTP status code as the last argument to try_files. I've tried this but it didn't work.

    • 10

  3. Yes, it's important to use HTTP 503 for temp. redirects. That's the way I've solved it:

    server {
        listen      80;
        server_name joergfelser.at;
        root    /var/www/joergfelser.at/;

        location / {
            if (-f $document_root/maintenance.html) {
                return 503;
           }
            ... # rest of your config, it's important to have 
            ... # the maintenance case at the very top
         }

        error_page 503 @maintenance;
        location @maintenance {
                rewrite ^(.*)$ /maintenance.html break;
        }
}

    I've also written a blog post on that topic:
    https://www.joergfelser.at/redirecting-to-a-custom-nginx-maintenance-page/

    Happy maintenancing ;)

    • 7

  4. If the maintenance page only has HTML

    No CSS, JS, ...

        # use RegExp because it has higher priority
    # if you don't have other `location`, you can use `location /`
    location ~ ^ {
        root /usr/share/nginx/html/maintenance/;
        error_page 503 /503.html;

        # return all request with status 503
        # use the `if ($status != 503)` to check if it is internal redirect
        if ($status != 503) {
            return 503;
        }
    }

    Without using if

        location @503 {
        root /usr/share/nginx/html/maintenance/;

        # `break` will stop internal redirect, just return the "/503.html"
        rewrite ^ "/503.html" break;
    }

    # use RegExp because it has higher priority
    location ~ ^ {
        error_page 503 @503;

        # return all request with status 503
        return 503;
    }

    For maintenance page that has CSS / JS / ...

    The flow of this is:

    • If URI is /, return status 503
    • If URI is a file (HTML, CSS, JS, ...) under root, return content with status 200
    • If not found, redirect to /
        location @index {
        # use redirect because if URI has sub-folder ($uri == /path/path/),
        # the relative path for static contents (CSS, JS, ...) will be incorrect
        rewrite ^ "/" redirect;
    }

    # use RegExp because it has higher priority
    location ~ / {
        root /usr/share/nginx/html/maintenance/;

        # 503 page URI
        error_page 503 /503.html;

        # if URI is index page, return 503
        if ($uri = "/") {
            return 503;
        }

        # redirect all URI to index (503) page (except static contents)
        try_files $uri @index;
    }

    You can put the config in a maintenance.conf, include maintenance.conf when in maintenance.

    • I will not use if (-f <file>) because it will try to check if the file exist on every request

    Ref: Nginx Maintenance

    • 1