From b4a3126134dae8181779e5c87c0e295badc9a6c8 Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Fri, 28 Jan 2022 23:26:40 +0000 Subject: [PATCH] :memo: Updates docs with status check custom response code (#456) --- docs/status-indicators.md | 19 +++++++++++++++---- docs/troubleshooting.md | 2 ++ 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/docs/status-indicators.md b/docs/status-indicators.md index 0c473e8e..b602f571 100644 --- a/docs/status-indicators.md +++ b/docs/status-indicators.md @@ -60,18 +60,29 @@ For example, `statusCheckHeaders: { 'X-Custom-Header': 'foobar' }` ## Disabling Security By default, (if you're using HTTPS) any requests to insecure or non-HTTPS content will be blocked. This will cause the status check to fail. If you trust the endpoint (e.g. you're self-hosting it), then you can disable this security measure for an individual item. This is done by setting `statusCheckAllowInsecure: true` +## Allowing Alternative Status Codes +If you expect your service to return a status code that is not in the 2XX range, and still want the indicator to be green, then you can specify an expected status code under `statusCheckAcceptCodes` for a given item. For example, `statusCheckAcceptCodes: '403,418'` + ## Troubleshooting Failing Status Checks -If the status is always returning an error, despite the service being online, then it is most likely an issue with access control, and should be fixed with the correct headers. Hover over the failing status to see the error code and response, in order to know where to start with addressing it. -If your service requires requests to include any authorization in the headers, then use the `statusCheckHeaders` property, as described above. +If you're using status checks, and despite a given service being online, the check is displaying an error, there are a couple of things you can look at: + +If your service requires requests to include any authorization in the headers, then use the `statusCheckHeaders` property, as described [above](#setting-custom-headers). + If you are still having issues, it may be because your target application is blocking requests from Dashy's IP. This is a [CORS error](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), and can be fixed by setting the headers on your target app, to include: ``` -Access-Control-Allow-Origin: https://[dashy-location]/ +Access-Control-Allow-Origin: https://location-of-dashy/ Vary: Origin ``` -If the URL you are checking is not using HTTPS, then you may need to disable the rejection of insecure requests. This can be done by setting `statusCheckAllowInsecure` to true for a given item. +If the URL you are checking has an unsigned certificate, or is not using HTTPS, then you may need to disable the rejection of insecure requests. This can be done by setting `statusCheckAllowInsecure` to true for a given item. + +If your service is online, but responds with a status code that is not in the 2xx range, then you can use `statusCheckAcceptCodes` to set an accepted status code. If you get an error, like `Service Unavailable: Server resulted in a fatal error`, even when it's definitely online, this is most likely caused by missing the protocol. Don't forget to include `https://` (or whatever protocol) before the URL, and ensure that if needed, you've specified the port. +Running Dashy in HOST network mode, instead of BRIDGE will allow status check access to other services in HOST mode. For more info, see [#445](https://github.com/Lissy93/dashy/discussions/445). + +If you have firewall rules configured, then ensure that they don't prevent Dashy from making requests to the other services you are trying to access. + Currently, the status check needs a page to be rendered, so if this URL in your browser does not return anything, then status checks will not work. This may be modified in the future, but in the meantime, a fix would be to make your own status service, which just checks if your app responds with whatever code you'd like, and then return a 200 plus renders an arbitrary message. Then just point `statusCheckUrl` to your custom page. For further troubleshooting, use an application like [Postman](https://postman.com) to diagnose the issue. Set the parameter to `GET`, and then make a call to: `https://[url-of-dashy]/status-check/?&url=[service-url]`. Where the service URL must have first been encoded (e.g. with `encodeURIComponent()` or [urlencoder.io](https://www.urlencoder.io/)) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index ff35e29c..6b07cb62 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -209,6 +209,8 @@ Vary: Origin ``` If the URL you are checking has an unsigned certificate, or is not using HTTPS, then you may need to disable the rejection of insecure requests. This can be done by setting `statusCheckAllowInsecure` to true for a given item. +If your service is online, but responds with a status code that is not in the 2xx range, then you can use `statusCheckAcceptCodes` to set an accepted status code. + If you get an error, like `Service Unavailable: Server resulted in a fatal error`, even when it's definitely online, this is most likely caused by missing the protocol. Don't forget to include `https://` (or whatever protocol) before the URL, and ensure that if needed, you've specified the port. Running Dashy in HOST network mode, instead of BRIDGE will allow status check access to other services in HOST mode. For more info, see [#445](https://github.com/Lissy93/dashy/discussions/445).