Separate maintenance mode (503) from infrastructure/application errors

[Copilot]

HTTP 503 was overloaded - used for both scheduled maintenance and backend failures/timeouts, causing users to see the maintenance page inappropriately.

Changes

NGINX configuration examples (examples/nginx/)

• Reserve 503 exclusively for scheduled maintenance via flag file check (/var/www/maintenance.flag)
• Route distinct error conditions to appropriate status codes:
  • 502: Backend unreachable
  • 504: Backend timeout (via explicit proxy_*_timeout settings)
  • 500: Application errors
  • 429: Rate limiting
• Named location @maintenance for 503 handling
• Internal location blocks for error page serving

Error pages (examples/nginx/error-pages/)

• Distinct HTML pages for each error type with contextual messaging
• maintenance.html only shown during actual maintenance

Configuration variants

• nginx.conf: Server block snippet for inclusion
• nginx-standalone.conf: Complete config for testing/validation
• test-config.sh: Automated syntax and structure validation

Example

location / {
    # Only return 503 when maintenance flag exists
    if (-f /var/www/maintenance.flag) {
        return 503;
    }
    
    proxy_pass http://backend;
    # Explicit timeouts → 504 instead of 503
    proxy_connect_timeout 60s;
    proxy_read_timeout 60s;
}

error_page 503 @maintenance;  # Scheduled maintenance only
error_page 502 /502.html;     # Backend down
error_page 504 /504.html;     # Backend timeout

Maintenance control:

touch /var/www/maintenance.flag   # Enable
rm /var/www/maintenance.flag      # Disable

Original prompt

freestyle-nginx-web seems to be serving a maintinence page for many different errors. it's because it's using 503 to mean maintinence, but 503 is being used for other reason. can you make sure that the maintinence page is only served when there's actually maintinence and have different error pages for those other things

Created from VS Code.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.