DEVCODE
How to Easily Enable Maintenance Mode on Any NGINX Website (With One-Click Toggle Script)
Server

How to Easily Enable Maintenance Mode on Any NGINX Website (With One-Click Toggle Script)

SI

Shamal Iroshan

2025-11-19 | 3 min read

When maintaining or updating a production website, it’s important to temporarily take the site offline and show a clean maintenance page to visitors. Instead of shutting down your server or modifying app code, you can create a simple maintenance mode system directly in NGINX — fast, safe, and easy to toggle.

In this guide, we’ll build,

  • A static maintenance HTML page
  • An NGINX rule to serve it
  • A simple command-line script to turn maintenance mode ON/OFF instantly

You will end up with commands like

maintenance site on
maintenance site off

Let’s get started.

1. Create a Maintenance Page

First, create a static HTML file that visitors will see during downtime,

sudo nano /var/www/maintenance.html

Example content,

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta-name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>We'll Be Back Soon</title>
  <style>
    body {
      margin: 0;
      height: 100vh;
      display: flex;
      justify-content: center;
      align-items: center;
      background: #0d0d0d;
      color: #fff;
      font-family: Arial, sans-serif;
      text-align: center;
      padding: 20px;
    }
    .box {
      max-width: 500px;
      padding: 40px;
      background: rgba(255,255,255,0.05);
      border-radius: 15px;
      backdrop-filter: blur(6px);
      border: 1px solid rgba(255,255,255,0.1);
    }
    h1 { font-size: 36px; margin-bottom: 10px; }
    p { font-size: 18px; opacity: 0.8; }
  </style>
</head>
<body>
  <div class="box">
    <h1>Under Maintenance</h1>
    <p>We're performing updates. Please check back soon.</p>
  </div>
</body>
</html>

Feel free to customize it to match your branding.

2. Add Maintenance Mode Logic to NGINX

Open your site’s NGINX config.
Assuming your site is hosted at,

example.com

sudo nano /etc/nginx/sites-available/example.com

Inside the main server { ... } block, add this near the top,

# Maintenance Mode Toggle
if (-f /var/www/MAINTENANCE_MODE) {
    return 503;
}

error_page 503 @maintenance;

location @maintenance {
    root /var/www;
    rewrite ^(.*)$ /maintenance.html break;
}

Your normal proxy or file-serving rules stay untouched.

Example full config snippet

server {
    server_name example.com;

    # Maintenance Mode
    if (-f /var/www/MAINTENANCE_MODE) {
        return 503;
    }
    error_page 503 @maintenance;
    location @maintenance {
        root /var/www;
        rewrite ^(.*)$ /maintenance.html break;
    }

    # Normal app
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
    }

    listen 443 ssl;
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
}

Apply the changes

sudo systemctl reload nginx

3. Create a One-Command Maintenance Script

Now let’s make a simple command that lets you turn maintenance mode ON and OFF very quickly.

Create a script,

sudo nano /usr/local/bin/maintenance

Add,

#!/bin/bash

# Usage:
#   maintenance site on
#   maintenance site off

ACTION=$2

if [ -z "$ACTION" ]; then
    echo "Usage: maintenance site <on|off>"
    exit 1
fi

FILE="/var/www/MAINTENANCE_MODE"

if [ "$ACTION" == "on" ]; then
    sudo touch $FILE
    echo "Maintenance mode ENABLED"
elif [ "$ACTION" == "off" ]; then
    sudo rm -f $FILE
    echo "Maintenance mode DISABLED"
else
    echo "Unknown action: $ACTION"
    exit 1
fi

sudo systemctl reload nginx

Make it executable,

sudo chmod +x /usr/local/bin/maintenance

4. Use Maintenance Mode

Enable Maintenance Mode

maintenance site on

Visitors will now see your maintenance page.

Disable Maintenance Mode

maintenance site off

Your website comes back online instantly — without restarting your app or NGINX.

Final Thoughts

This approach is,

  • Fast — no app redeploy needed
  • Safe — doesn’t depend on the app itself
  • Zero-downtime — NGINX reload is instant
  • Expandable — you can use it for multiple apps or subdomains
  • Developer-friendly — a simple command manages everything

If you’re hosting multiple sites or micro-services, you can easily extend the script to manage each one separately.

Loading comments...