dotcom-arcade/docs/10-features/11-maintenance-mode.md

Maintenance Mode

Temporarily restrict access to the application while performing system updates.

Overview

Maintenance mode allows administrators to temporarily block access to the application while performing critical operations like database migrations, updates, or emergency repairs. When enabled, only administrators can access the system while regular users and guests receive a maintenance message.

How It Works

When maintenance mode is enabled:

1. Administrators (users with settings.update permission) can access everything
2. Regular users are blocked from all API endpoints
3. Guest users are blocked from all API endpoints
4. Public paths remain accessible for login (so admins can authenticate)

Enabling Maintenance Mode

Via Settings UI

1. Navigate to Settings → App Settings (requires admin access)
2. Toggle Maintenance Mode on
3. Confirm the change

Via API

curl -X PATCH http://localhost:3100/api/settings/app \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"maintenanceMode": true}'

Via Database (Emergency)

If locked out, update the database directly:

UPDATE system_settings
SET value = '0'
WHERE key = 'app.maintenance_mode';

User Experience

Admin Users

Admins experience no change during maintenance:

• Full access to all features
• Can browse games, manage users, update settings
• Log entries show admin activity during maintenance

Non-Admin Users

When a non-admin user tries to access the site:

API Response:

{
  "error": "Service Unavailable",
  "message": "The application is currently undergoing maintenance. Please try again later.",
  "maintenanceMode": true,
  "retryAfter": 3600
}

HTTP Status: 503 Service Unavailable

Headers:

• Retry-After: 3600 (suggests retry after 1 hour)

Frontend Handling

The frontend should:

1. Detect 503 responses with maintenanceMode: true
2. Display a maintenance message to users
3. Provide a way to check if maintenance has ended

Public Paths

These endpoints remain accessible during maintenance (for admin login):

Path	Purpose
/health	Health check endpoint
/api/auth/login	Admin authentication
/api/auth/register	User registration
/api/auth/setup-status	Initial setup check
/api/auth/refresh	Token refresh
/api/settings/public	Public settings (UI needs)
/api/playlists/shared/*	Shared playlist access

Security

Fail-Closed Strategy

If the maintenance middleware encounters an error (e.g., database failure), it blocks requests rather than allowing them through. This ensures the system remains protected even during failures.

Admin Detection

Admin status is determined by checking if the user has the settings.update permission. This permission is typically assigned only to the "admin" role.

Token Validation

The middleware relies on softAuth middleware to validate JWT tokens. No duplicate validation is performed, ensuring good performance.

Testing Maintenance Mode

As Admin

1. Enable maintenance mode via Settings
2. Verify you can still access all features
3. Check activity logs for maintenance access entries
4. Disable maintenance mode

As Regular User

1. Have an admin enable maintenance mode
2. Open the site in a different browser/incognito
3. Verify you see the maintenance message
4. Verify login page is accessible (for error display)
5. Have admin disable maintenance mode

As Guest

1. Enable maintenance mode (as admin)
2. Open site in incognito (not logged in)
3. Verify API requests return 503
4. Verify static assets still load

Troubleshooting

Can't Disable Maintenance Mode

Cause: Admin token may have expired.

Solution:

1. Log out and log back in for a fresh token
2. Or update database directly (see above)

UI Broken During Maintenance

Cause: Public settings endpoint may be failing.

Solution: Verify /api/settings/public is accessible and returning valid data.

Admin Getting Blocked

Cause: User may not have settings.update permission.

Solution:

1. Check user's role permissions in the database
2. Ensure user is assigned the admin role

Logging

The middleware logs all maintenance-related activity:

Log Level	Message	Description
INFO	[Maintenance] Admin <username> accessing...	Admin request during maintenance
WARN	[Maintenance] Blocked...	Non-admin request blocked
ERROR	[Maintenance] Critical error...	Middleware failure

Best Practices

1. Notify users beforehand when possible (email, announcement)
2. Keep maintenance windows short to minimize disruption
3. Test critical operations before enabling maintenance
4. Monitor logs during maintenance for issues
5. Have database access ready in case of admin lockout
6. Verify admin login works before enabling maintenance

Related Documentation

• System Settings - Where maintenance mode is configured
• Authentication - How admin access works
• Settings API - API for toggling maintenance
• Internal Maintenance Docs - Technical implementation details