Skip to main content

How to display maintenance page except for specific IP addresses?

You can configure KurocoFront to display a maintenance page to all visitors except those accessing from specific IP addresses using the ip_restricted_maintenance feature in kuroco_front.json.

Configuration Overview​

The ip_restricted_maintenance setting allows you to:

  • Display maintenance pages to all visitors except specified IP addresses
  • Use custom HTML maintenance pages
  • Support subnet mask notation for flexible IP range configuration
  • Configure multiple IP addresses or ranges

Basic Configuration​

kuroco_front.json Configuration File​

Create or update your kuroco_front.json configuration file with the following content:

{
    "ip_restricted_maintenance": [
        "111.111.111.111/32",
        "222.222.222.222/32",
        "192.168.1.0/24"
    ],
    "error_page": {
        "status_ip_503": "/maintenance.html"
    }
}

File placement by framework:

  • Nuxt 3: /public/kuroco_front.json
  • Next.js: /public/kuroco_front.json
  • Other frameworks: Build output root directory
tip

If you don't specify a custom maintenance page, visitors from non-allowed IP addresses will see a standard "503 Service Unavailable" error.

Custom Maintenance Page (HTML)​

Create a custom maintenance page HTML file with the following content:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Site Under Maintenance</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            text-align: center;
            padding: 50px;
            background-color: #f5f5f5;
            margin: 0;
        }
        .maintenance-container {
            max-width: 600px;
            margin: 0 auto;
            background: white;
            padding: 40px;
            border-radius: 10px;
            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
        }
        h1 {
            color: #e74c3c;
            margin-bottom: 20px;
        }
        p {
            color: #666;
            line-height: 1.6;
            margin-bottom: 15px;
        }
        .contact {
            margin-top: 30px;
            padding-top: 20px;
            border-top: 1px solid #eee;
            font-size: 14px;
            color: #999;
        }
    </style>
</head>
<body>
    <div class="maintenance-container">
        <h1>🔧 Site Under Maintenance</h1>
        <p>We are currently performing scheduled maintenance to improve our services.</p>
        <p>We apologize for any inconvenience this may cause.</p>
        <p>Please check back shortly as we work to restore normal operations.</p>
        <div class="contact">
            <p>For urgent inquiries, please contact: support@example.com</p>
        </div>
    </div>
</body>
</html>

File placement by framework:

  • Nuxt 3: /public/maintenance.html
  • Next.js: /public/maintenance.html

IP Address Formats​

FormatDescriptionExample
Single IPSpecific IP address"192.168.1.100/32"
SubnetIP range using CIDR notation"192.168.1.0/24"
Multiple IPsArray of IP addresses/ranges["10.0.0.1/32", "192.168.0.0/16"]

Reference: Comparison with KurocoEdge​

KurocoFront can handle basic maintenance scenarios, but by using KurocoEdge, you can achieve more advanced configurations such as specifying scheduled maintenance times and setting access restrictions on a per-path basis.

For more details, please refer to the KurocoEdge documentation.

FeatureKurocoFrontKurocoEdge
Setup complexitySimpleAdvanced
IP-based restrictions✅✅
Custom maintenance pages✅✅
Scheduled activation❌✅
Path-specific restrictions❌✅

Support

If you have any other questions, please contact us or check out Our Slack Community.

Contact form
Join Kuroco Slack community