Knowledge Base > Joget Maintenance Mode

Introduction

Platform-level toggle to restrict userview/API access during maintenance windows.

Overview

The Maintenance Mode plugin allows Joget platform administrators to temporarily restrict access to userviews and APIs during planned maintenance windows. When enabled, all non-admin traffic is blocked and returns an HTTP 503 (Service Unavailable) response, while the admin console and configured safe paths remain fully accessible.

This is useful for scenarios such as:

Performing database migrations or upgrades
Deploying new application versions
Running system-level maintenance tasks that require no active user sessions

Plugin information

Plugins Available in the Bundle:

Joget Maintenance Mode Plugin.

This plugin bundle is compatible with Joget DX 9 and onwards.

Where to get the plugin

You can download this plugin from Latest target Releases.

Maintenance Mode Settings

Maintenance Mode settings are found in the Joget admin console under:

Settings > System Settings > Maintenance Mode

Note
Only users with the ROLE_ADMIN role can access and modify these settings.

Status

The Status section controls whether maintenance mode is currently active.

Field	Description
Status Indicator	Shows the current state of maintenance mode: ENABLED or DISABLED.
Enable Button	Activates maintenance mode immediately. All non-admin userview and API traffic will begin returning HTTP 503.
Disable Button	Deactivates maintenance mode immediately. Normal traffic resumes for all users.
Admin Banner	When maintenance mode is enabled, an orange "⚠ Maintenance Mode is ENABLED" banner appears persistently at the top of every page for admin users only. Non-admins see the 503 page instead.

Note
When enabled, userview/API traffic returns HTTP 503. Admin console and configured safe paths continue to work.

What non-admin users see when maintenance mode is enabled:

What admin users see — the orange banner appears across all pages as a persistent reminder:

Field	Description
Maintenance Title	The heading displayed on the maintenance page shown to blocked users. Default: "Maintenance In Progress".
Maintenance Message	The message body displayed below the title. Default: "System is under maintenance. Please try again later.".

These values are also returned in the JSON error body for blocked API requests:

{ "success": false, "message": "<Maintenance Message>" }

Access Rules

The Access Rules section defines which roles and URL paths are permitted to bypass maintenance mode.

Field	Description
Allowed Roles	Fixed to ROLE_ADMIN for platform safety. Users with the admin role will always be able to access the platform regardless of maintenance mode status.
Additional Allowed URL Prefixes	A comma- or newline-separated list of additional URL path prefixes that should remain accessible during maintenance mode. These paths are added to the platform's built-in recovery URL list. The paths include: /web/console, /web/json/console, /web/j_spring_security_check, /web/images, /web/css, /web/js, /web/plugin, /web/fonts, /web/health, /web/console/setting/plugin, /web/console/setting/plugin/upload. Note: The platform includes a built-in set of recovery URLs that are always accessible and cannot be modified. These ensure administrators can continue accessing essential platform functions, such as the Admin Console, Plugin Manager, login, console APIs, static resources, and the health endpoint, even when maintenance mode is enabled. Any URL prefixes configured here are appended to this built-in list.
Reset To Recommended Defaults	Resets the Allowed URL Prefixes back to the system-recommended default paths.

Note: The Allowed Roles field is fixed to ROLE_ADMIN and cannot be changed. This ensures administrators always retain access to the console during maintenance.

Emergency Bypass

The Emergency Bypass section allows a specific HTTP header to be configured as a secret bypass token. Any request carrying the matching header name and value will pass through maintenance mode without restriction, regardless of the user's role.

This is useful for:

Allowing automated systems or monitoring tools to continue calling APIs during maintenance
Permitting specific trusted integrations to remain active while blocking general user access
Enabling QA or testing teams to verify the system without disabling maintenance mode

Field	Description
Header Name	The name of the HTTP request header to check for the bypass token. Leave empty to disable the bypass feature.
Header Value	The expected value of the bypass header. Requests that present this exact header name and value will be allowed through.

Note: Keep the bypass header name and value confidential. Anyone who knows these values can bypass maintenance mode entirely.

Custom Maintenance Page

By default, maintenance mode displays a built-in maintenance page. You can override this with a fully custom HTML template.

Field	Description
Use Own Template	When checked, the system will use the HTML provided in the Custom Template field instead of the default maintenance page.
Custom Maintenance HTML	A full HTML document to display to blocked users. Supports two token placeholders that are substituted at runtime: {{title}} – replaced with the Maintenance Title value. {{message}} – replaced with the Maintenance Message value.

Example: Custom Maintenance Page

Below is a working example of a custom HTML maintenance page.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
  <title>{{title}}</title>
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }

 

    body {
      font-family: 'Segoe UI', Arial, sans-serif;
      background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
      min-height: 100vh;
      display: flex;
      align-items: center;
      justify-content: center;
      color: #fff;
    }

 

    .container {
      text-align: center;
      padding: 60px 40px;
      background: rgba(255,255,255,0.05);
      border: 1px solid rgba(255,255,255,0.1);
      border-radius: 20px;
      backdrop-filter: blur(10px);
      max-width: 560px;
      width: 90%;
    }

 

    .icon {
      font-size: 64px;
      margin-bottom: 24px;
    }

 

    h1 {
      font-size: 2rem;
      font-weight: 700;
      margin-bottom: 16px;
      color: #f0c040;
    }

 

    p {
      font-size: 1.05rem;
      color: #ccc;
      line-height: 1.7;
      margin-bottom: 32px;
    }

 

    .progress-bar {
      width: 100%;
      height: 6px;
      background: rgba(255,255,255,0.1);
      border-radius: 999px;
      overflow: hidden;
    }

 

    .progress-fill {
      height: 100%;
      width: 40%;
      background: linear-gradient(90deg, #f0c040, #e67e22);
      border-radius: 999px;
      animation: pulse 2s ease-in-out infinite;
    }

 

    @keyframes pulse {
      0%, 100% { opacity: 1; width: 40%; }
      50% { opacity: 0.6; width: 60%; }
    }

 

    .footer {
      margin-top: 32px;
      font-size: 0.8rem;
      color: rgba(255,255,255,0.3);
    }
  </style>
</head>
<body>
  <div class="container">
    <div class="icon">🔧</div>
    <h1>{{title}}</h1>
    <p>{{message}}</p>
    <div class="progress-bar">
      <div class="progress-fill"></div>
    </div>
    <div class="footer">Please check back shortly. We appreciate your patience.</div>
  </div>
</body>
</html>

Affected Traffic

Maintenance mode blocks traffic on the following URL patterns:

/web/** — Standard Joget web paths including userviews and JSON APIs
/api/** — API Builder endpoints published via the Joget API Builder

The following paths are always accessible during maintenance mode by default:

Path	Purpose
/web/console	Admin console
/web/json/console	Admin console JSON APIs
/web/j_spring_security_check	Login authentication endpoint
/web/images	Platform images
/web/css	Platform stylesheets
/web/js	Platform JavaScript
/web/plugin	Plugin resources
/web/fonts	Platform fonts
/web/health	Health check endpoint
/web/console/setting/plugin	Plugin Manager
/web/console/setting/plugin/upload	Plugin upload page

Saving Settings

After making changes to the Response, Access Rules, Emergency Bypass, or Custom Template sections, click the Save Settings button at the bottom of the page to persist your changes.

Note
Toggling maintenance mode on or off (via the Enable/Disable buttons) saves immediately without requiring the Save Settings button.

Joget Maintenance Mode

Summary

Prerequisites & Step-by-Step