Document how to "simulate" maintenance mode for clients #15195

Before You Submit

• I have checked for existing issues and pull requests related to my suggestion.
• I have posted on the Nextcloud Community Help Forum if my suggestion is a troubleshooting scenario or I'm unsure about the solution.

Type of Suggestion

Proposing new documentation content

Relevant Documentation Links

https://docs.nextcloud.com/server/stable/admin_manual/maintenance/index.html

Summary

Write that answering with HTTP Status Code of 503 does allow clients to detect the server as being in "maintenance mode".

Details

Example text I propose to add to the maintenance section (feel free to copy & adapt without attribution):

When Nextcloud instances undergo a maintenance with Nextcloud being fully disabled,
Nextcloud can no longer serve its status to clients stating that Nextcloud is in maintenance mode.

Therefore, when such a maintenance is happening, but the HTTP endpoint of your instance is still reachable
(e.g. because you decided to publish a maintenance message to browser users),
that endpoint SHOULD serve [all|important] paths with a HTTP status code of 503.

[optionally serve maintenance JSON on status endpoint]

This aids clients, e.g. the Nextcloud mobile apps or the desktop client, in detecting the maintenance mode properly.
Otherwise they might show confusing errors to their users such as "Some files could not be synchronized".

[optional examples for common webservers]

I have not made a PR because I am unsure where to add this & how detailed this should be. E.g. should it ultimately state under which URLs admins MAY serve a JSON document with {"maintenance":true}, or is 503 good enough because it is messaged the same to its users?

Esp. when including the JSON approach, this new section could include examples of how to configure such static servings directly in the configuration files of some common webservers (Apache, nginx, Caddy, ...)

Additional Notes

I propose this because my university has made a maintenance of their Nextcloud instance. But instead of serving nothing, they decided to serve a custom page stating that "maintenance is ongoing". And of course they decided to send that with a HTTP status code of 200. This of course bricks the clients of some kind because they have no clear idea on how to deal with that:

(The client states: "Some files could not be synchronized!" and "For warnings see below", but they are none.)

Of course the clients could be updated to attempt to identify such cases as well & explain such a situation better to the user. But IMHO I think server operators should just not serve their maintenance hint with a 200. I will write that to my university as well, but I think Nextcloud could aid here by having a small documentation snippet explaining why sending a 503 is useful for automated purposes.