Let's first learn about maintenance mode. Let say you have developed a web application and it is now live to millions of users. You are working on weekly or bi-weekly deployment on production environment.
Sometimes you might want to take your server down for sometime during deployment window so that you can avoid write calls to your database.
How can you handle this scenario in laravel application. Sometime you also want to test your changes but you do not want other users to see your new changes until deployment is completly done.
In laravel application there are two artisan commands that helps you with your maintenance window. Let's look at the first command:
# take your laravel site down for maintenance mode php artisan down
When you run this command you will see following screen on your laravel application.
This command will bring your entire website down until you run next command shown below to bring your website up and running again.
# to bring your website up and running again from maintenance mode php artisan up
What can you do during maintenance mode?
When your application under maintenance mode a custom laravel view is displayed to your audience.
You can change the view and design your custom view to show your custom view you can use following command.
# show custom view file located at resources/views/errors/503.blade.php php artisan down --render="errors::503"
Sometime you might want to referesh your page under maintenance mode so that when maintenance is done user do not need to referesh page on their end,
It will automatically bring users site without them clicking their reload button in the browser. To do this you need to run maintenance mode with following option:
# The Refresh header will instruct the browser to automatically refresh the page after the specified number of seconds php artisan down --refresh=15
Above command will send Refresh HTTP header along with page response so that your browser will referesh the page every 15 seconds.
Bypassing Maintenance Mode
In some cases even though your site is under maintenance mode you do want to check the website changes during deployment.
In this case laravel allows you to create a secret route which when you access creates a cookie on your browser as long as you have this cookie on your browser you wont see maintenance mode on your web browser.
Keep in mind that your website is still under maintenance mode and other user will see your custom maintenacne page.
Run following command to create a secret route under maintenance mode:
php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"
After running above command you can go to following matching url:
http://localhost/1630542a-246b-4b66-afa1-dd72a4c43515
When accessing this hidden route, you will then be redirected back to the / route of the application.
Once the cookie has been issued to your browser, you will be able to browse the application normally as if it was not in maintenance mode.
Important notes for maintenance mode in laravel
When application is under maintenance mode you would have to keep following things in mind:
- no queue jobs will be handled
- all your routes will show maintenance page