How to run Laravel in maintenance mode

Introduction

Laravel provides a variety of helpful tools for application development and maintenance, one of which is the maintenance mode feature. When your Laravel application needs updating or maintenance, enabling maintenance mode lets you prevent access to your application while providing a friendly notification to your users. This tutorial will guide you through activating, customizing, and managing Laravel’s maintenance mode.

Enabling Maintenance Mode

To activate the maintenance mode, you use the Artisan command-line tool included with Laravel. The basic command is:

php artisan down

Once this command is executed, all incoming requests to your application will receive a 503 HTTP status code along with a default maintenance mode view.

Service Unavailable

Customizing the Message

You can customize the message your users see when the application is in maintenance mode by using the following command:

php artisan down --message="We're upgrading our system, be right back."

This will change the default maintenance message to inform your users about the reason for downtime.

Allowing Access for Specific IP Addresses

Sometimes you or other stakeholders may need access to the application while it is in maintenance mode. You can whitelist your IP address using the --allow option like this:

php artisan down --allow=123.456.789.000

You can specify multiple IP addresses by repeating the --allow option:

php artisan down --allow=123.456.789.000 --allow=111.222.333.444

Pre-rendering a Maintenance Mode View

Laravel gives you the capability to pre-render a template to use when maintenance mode is enabled. To do this, you can simply create a view and use the --render option:

php artisan down --render="errors::maintenance"

This is useful when you want a custom-designed maintenance page instead of the default message.

Allowing Access to Specific Routes

Laravel allows you to specify the routes that should be accessible even when the app is down. You define this logic inside your application’s middleware.

For example, to grant access to all routes beginning with ‘api/admin’, you would add conditional logic to your middleware:

$request->is('api/admin/*')

At the start of your route group, wrap the desired routes with a request check:

if ($request->is('api/admin/*')) {
   // Execute these routes even in maintenance mode
}

Coming Out of Maintenance Mode

To disable the maintenance mode and bring your application back online, you can use the following Artisan command:

php artisan up

With this, your application will immediately become available to your users as normal.

Advanced Usage: Using Middleware

To allow a finer control over maintenance mode, you can leverage Laravel’s middleware. For instance, you may want to allow only signed-in users with a specific role to access the site. The middleware you write might look like:

public function handle($request, Closure $next)
{
    if ($this->app->isDownForMaintenance() && !auth()->user()?->is_admin) {
        throw new HttpException(503);
    }

    return $next($request);
}

Add this custom middleware to your Kernel.php and ensure it runs for all requests. This will check if the app is in maintenance mode and whether the authenticated user is an admin before proceeding with the request.

Scheduling Maintenance Mode

If you want to schedule maintenance mode you can use the task scheduler to run php artisan down and php artisan up at specific times.

$schedule->command('down')->at('02:00');
$schedule->command('up')->at('03:00');

Add the above cron events to your App\Console\Kernel schedule method.

Using a Custom Template for the Retry After Header

Another advanced feature of Laravel’s maintenance mode is setting a retry-after header by using the --retry option:

php artisan down --retry=60

This tells the client’s browser to retry after 60 seconds. You can also tailor a view that includes a countdown or a periodic refresh to keep the user informed.

Secret Phrase To Bypass Maintenance Mode

Laravel also provides a way to bypass the maintenance mode using a secret phrase. To use this feature, run the following command, which will generate a unique link:

php artisan down --secret="backdoor"

Visiting the URL http://yourapp.com/backdoor will allow you to bypass the maintenance mode screen allowing site review and testing seamlessly.

Conclusion

Maintenance mode is an essential feature for managing your Laravel application during updates and upgrades. Using these simple and advanced features ensures minimal disruption for users and provides the necessary control to developers and administrators during maintenance periods.