Maintenance Mode and Whitelists in Laravel 4

When developing web applications on your local web server you are pretty safe, nobody except you will notice your bugs. But from time to time you need to push the changes to the production server. This is the most stressful part of web developer's job and it's the biggest single point of frustration. You are all familiar with the famous: "but it works on my machine" excuse...

I hope you are all using some sort of code testing and/or staging servers before you actually push changes to the production but even then you might encounter some migrations or major changes which might produce issues and it would be better done unnoticed. A lot of major web sites/applications like oDesk have maintenance time here and there and that's a perfectly good way to disable the site for a while you are making your changes.

Luckily Laravel 4 provides a simple way to put your application into maintenance mode.

In order to put the site into maintenance mode simply run this command from the command line:

php artisan down

Now when the site is accessed you will get a short message that says:

"Be right back!"

This message is returned by App::down function which is already in your:


If it's not you should really update your Laravel files.

The default App::down() function looks like this:

    return Response::make("Be right back!", 503);

If you want to render a view instead of the plain old message, you would pass in the view name instead of the message like this:

    return Response::view('maintenance', array(), 503);

This will render a view called 'maintenance' from your views directory. You also pass in an empty array as the second argument because we don't have any data to pass. The third argument 503 is a number that represents a HTTP status code, in our case 'Service Unavailable'.

RFC explains status code 503:

10.5.4 503 Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay MAY be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 response. Note: The existence of the 503 status code does not imply that a server must use it when becoming overloaded. Some servers may wish to simply refuse the connection.

To disable the maintenance mode, we use the up command:

php artisan up

This approach is great but disables the site for all visitors including admins!

If we want to make it more sophisticated we would create a white list of IPs that have access to the site.

We could lookup the clients ip address and look it up in the white listed array of ip addresses, something like this:

    $ip = Request::getClientIp();
    $allowed = array('', '', '');

    if(!in_array($ip, $allowed))
        return Response::view('maintenance', array(), 503);

Now only visitors whose IPs are white listed have access to the site.

Share your thoughts and comments below.

comments powered by Disqus