In the FAQ https://matomo.org/faq/new-to-piwik/faq_134/ it is written
"When Matomo is used behind a load balancer, here are the steps to follow:
..... in your config.ini.php, below the section [General], add the following line: multi_server_environment=1. This setting lets Matomo know you’re using multiple servers....."
When publishing a web-service via loadbalancers, you use a health-monitor that checks that the web-application answers as expected. As described in https://matomo.org/faq/how-to/faq_20278/
When activating maintenance_mode, the Reporting API and Core platform changes status-code from 200 to 503.
This will cause the loadbalancers to stop sending traffic to the web-server. And the maintenance page is not reachable for the visitors/clients.
When multi_server_environment = 1 (or new property indicating that there is a loadbalancers in front of matomo) is set.
And maintenance_mode = 1 is set, the status code from Reporting API and Core platform should still be http 200.
So clients are displayed with the maintenance page.
Reporting API and Core platform returns 503 when maintenance_mode is set to 1.
When using multi_server_environment ( or new property), and maintenance_mode is set to 1. Keep the response code 200.
curl -ik 'https://matomo.example.com/index.php?module=API&method=API.getMatomoVersion&token_auth=<token>
Thanks for reporting this @MrIsak makes sense.
Although 503 is the best response code, I wonder if we maybe want to return an HTTP 200 in these cases in general (eg in case someone is using it behind a load balancer but doesn't have this config flag set). Could also only return http 200 when this config is set as suggested.
We should also update the docs in https://matomo.org/faq/how-to/faq_20278/ and mention that if Matomo is put in maintenance mode, then it will return a 503 unless
multi_server_environment is configured.
Sorry, but: If the server is in maintenance (whereas other are not), it is preferable the load-balancer does not sent any request to the server during its maintenance... So it should reply 503
But it's true that if all servers are in maintenance mode, the maintenance page should be available...
@heurteph-ei I assume that servers would be maybe terminated once the 503 comes up and then new ones would be launched which then fail again etc and eg a running Matomo DB upgrade triggered on an instance would be terminated. And generally nobody would see the Matomo Maintenance page. @MrIsak is that maybe the case for you?
@heurteph-ei That would be the "general" recommendation for loadbalanced environments. But due to how motomo works. ALL matomo servers will be in maintenance to prevent clients from using the GUI and have a bad user experience. Which means, no traffic will be forwarded to the enviroment, since the maintenance mode returns 503, not 200, as it says in
@tsteur , not sure I understand you correct. But yes. Since the recommendation in a multi-server-enviroment is to sync config.ini between servers; all servers will be in maintenance-mode at the same time. This will cause the loadbalancers to not forward traffic to matomo since the health-checks response is 503. And as you say, no one will see the maintenance-page.