README

Extend Laravel's maintenance mode with a custom message, countdown timer, whitelist, and multi-server storage (file, redis, s3). Includes a modern admin UI built with TailwindCSS.

Installation

composer require areia-lab/laravel-maintainer

Publish configuration and views:

php artisan vendor:publish --tag=maintainer-config
php artisan vendor:publish --tag=maintainer-views

Configuration

Edit config/maintenance.php to configure:

driver — storage driver (file, redis, s3)
file_path — path for file driver (default: storage/framework/maintenance.json)
redis_key — key for redis driver
s3_disk / s3_key — disk and key for s3 driver
message — default maintenance message
whitelist_ips / whitelist_users — users or IPs allowed to bypass maintenance
admin_path / admin_middleware — admin panel URL and middleware protection
preview_path — optional preview route

Example .env:

MAINTENANCE_DRIVER=file
MAINTENANCE_FILE_PATH=framework/maintenance.json
MAINTENANCE_MESSAGE="We’ll be back soon after scheduled maintenance."

MAINTENANCE_WHITELIST_USERS=1,2
MAINTENANCE_WHITELIST_IPS=127.0.0.1,192.168.1.10

MAINTENANCE_PREVIEW_PATH=maintenance/preview
MAINTENANCE_ADMIN_PATH=maintenance/admin
MAINTENANCE_ADMIN_MIDDLEWARE=web,auth

MAINTENANCE_LOAD_ROUTES_IN_PRODUCTION=true

Supported Drivers

file — stores maintenance state locally (default)
redis — shared across multiple servers
s3 — centralized state in S3

For multi-server deployments, prefer redis or s3.

Commands

Enable custom maintenance:

php artisan maintenance:enable

php artisan maintenance:enable --message="Upgrading" --ends-at="2025-09-12 03:00" --whitelist-ips="127.0.0.1" --whitelist-users="1,admin@example.com"

php artisan maintenance:enable --force

Disable maintenance:

php artisan maintenance:disable

php artisan maintenance:disable --force

Admin UI

Visit the admin panel at:

/maintenance/admin

Protect with auth middleware in production.
Features:
- Enable/disable maintenance mode
- Set custom message
- Set countdown (ends_at)
- Manage whitelisted users/IPs
- Real-time countdown display

Middleware Usage

Route::get('/', function () {
    return view('welcome');
})->middleware(['maintenance.check']);

# Or as a group
Route::middleware(['maintenance.check'])->group(function () {
    Route::get('/', function () {
        return view('welcome');
    });
});

Preview Maintenance Page

Visit /maintenance/preview to preview the maintenance page without enabling it. Shows message, countdown timer, and optional whitelist info.

Notes

Multi-server deployments: use redis or s3.
Security: always protect the admin panel routes with authentication.
Customization: override views in resources/areia/maintenance.
Preview in production: disable preview route if needed using load_routes_in_production in config.

License

MIT

areia-lab / laravel-maintainer

Maintainers

Details