Laravel Maintenance Mode During Deployment: Controlled 503 Instead of Random 500 Errors

During a production deployment in ICanUp, there is a short period where code, Composer dependencies, migrations, caches, and long-running processes may not change at exactly the same moment.

If normal traffic remains open during that transition, a user can reach the application between two valid states.

At best, they refresh the page. At worst, they receive a random 500 Internal Server Error.

During the critical deployment phase, I therefore deliberately put the site into maintenance mode and return a controlled HTTP 503 Service Unavailable.

Every individual deployment command may be correct, but the full sequence is not atomic.

Git may already contain new code while vendor is still old. A migration may already have changed the schema while Laravel caches still describe the previous version. A new frontend build may not yet be active.

To the user, that does not look like "deployment in progress". It simply looks like a broken page.

500 Internal Server Error means the server attempted to process a normal request and failed.

503 Service Unavailable communicates something different: the service is temporarily unavailable and the server is saying so intentionally.

During a controlled deployment, the second response describes the actual system state more accurately.

Maintenance mode needs to be active before application code, dependencies, and other critical components begin changing.

Enabling it only after composer install or migrations would still leave part of the unsafe window exposed.

Three options matter to me here:

• --render=maintenance uses a pre-rendered maintenance view.
• --retry=60 communicates when a client may retry the request.
• --refresh=15 allows the maintenance page to refresh periodically during a short maintenance window.

The worst maintenance page is one that depends on the same Laravel components currently being replaced.

If the response needs the full application to boot while composer install or cache rebuilding is in progress, the maintenance page can fail together with the application.

I therefore use a pre-rendered view through --render.

I do not expose stack traces, failed commands, or other internal deployment details.

The user only needs to know that the site is being updated and that trying again shortly is appropriate.

To return a controlled HTTP 503, the web stack still needs to accept requests.

I therefore do not stop Nginx or PHP-FPM merely to close the site during deployment.

Doing so would produce timeouts, connection errors, or proxy failures instead of an intentional maintenance response.

Until those steps complete, I do not want normal public traffic reaching the application.

The deployment script ending does not automatically mean the site should return to users.

If a critical command fails, the current application state may be incomplete.

In that situation I keep maintenance mode active until the problem is fixed or the deployment is rolled back.

It is easy to write a shell cleanup handler that always runs php artisan up when a script exits.

That pattern is useful for temporary files. It is not always correct for production traffic.

If deployment fails after changing the database schema or dependencies, automatically reopening the site can expose exactly the broken state maintenance mode was intended to hide.

I do not run php artisan up immediately after the last deployment command.

First I verify that the application is ready for normal traffic.

• Laravel boots successfully.
• Migrations completed successfully.
• Laravel caches were rebuilt.
• Frontend assets are present.
• The queue worker is running.
• Reverb is running.
• The SSR process is running.
• Supervisor reports no critical process failures.

Even after artisan up, the deployment is not finished for me.

After normal traffic returns, I run an external HTTP check.

At this point it verifies the real public application rather than the maintenance page.

The --fail option ensures that an HTTP 500 response does not look like a successful shell command.

There is another important edge case: all deployment commands succeed, artisan up runs, but the external verification still finds a problem.

I do not leave the site open simply because the pipeline is almost complete.

An HTTP 503 response can include Retry-After so clients and crawlers understand that the outage is temporary.

For a short controlled deployment, that is more accurate than behaving as if the page were permanently broken.

Laravel exposes that value through --retry.

Maintenance mode is not an excuse for long downtime.

Its job is to make a short dangerous transition predictable.

If maintenance mode remains active for a long time, that becomes a separate operational incident that needs investigation.

In a modern Laravel application, one HTTP 200 response does not describe the health of the whole system.

In ICanUp, deployment also needs to restore the queue worker, Reverb, and Inertia SSR to a known healthy state.

That is why Supervisor restarts and process verification happen before the maintenance window is considered complete.

Maintenance mode is useful to me only when it is part of a predictable deployment flow.

I do not want to manually remember when to run artisan down, when to run artisan up, and what to verify in between.

I described the broader process in my article about a real Laravel CI/CD pipeline.

• Do not keep normal public traffic open while critical application state is changing.
• Do not show random 500 responses when the outage is actually planned.
• Do not stop Nginx or PHP-FPM merely to create a maintenance window.
• Do not build the maintenance page on complex application logic that may fail during deployment.
• Do not run artisan up automatically after every failure.
• Do not treat the final deployment command as proof of application health.
• Do not reopen the site before checking Supervisor processes.
• Do not complete deployment without an external HTTP check.
• Do not leave public traffic open after a failed final check.

• Prepare a simple maintenance page.
• Enable maintenance mode before critical changes.
• Return HTTP 503 instead of 200.
• Provide Retry-After through --retry.
• Update code, dependencies, migrations, and caches.
• Restart long-running processes.
• Verify Supervisor status.
• Keep maintenance mode active on failure.
• Run artisan up only after internal verification.
• Run an external HTTP health check after reopening.
• Restore maintenance mode if the final check fails.

• Treat maintenance mode as the boundary between the stable old version and the stable new version.
• Enable 503 before critical application changes begin.
• Use a pre-rendered maintenance page.
• Do not depend on the full Laravel boot process for the maintenance response.
• Do not reopen the application automatically after a failed deployment.
• Verify long-running processes before restoring public traffic.
• Run a separate external check after artisan up.
• Restore maintenance mode after a failed final check.
• Keep recovery and rollback procedures separate from the successful deployment path.

In ICanUp, maintenance mode became more than a decorative page. It is part of production safety.

Its job is simple: prevent users from reaching the intermediate state between the old valid version and the new one.

During the critical phase, the site intentionally returns 503 Service Unavailable. Code, dependencies, migrations, caches, queue workers, Reverb, and SSR are updated behind that boundary.

If something fails, maintenance mode remains active. If internal checks pass, the site reopens and one more external HTTP check verifies the public application.

For me, a good deployment is not one with zero seconds of 503. It is one where users never see a broken intermediate application state.