diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/advanced/healthchecks.md | 48 | ||||
| -rw-r--r-- | docs/api/swagger.yaml | 38 |
2 files changed, 86 insertions, 0 deletions
diff --git a/docs/advanced/healthchecks.md b/docs/advanced/healthchecks.md new file mode 100644 index 000000000..30f90f7f2 --- /dev/null +++ b/docs/advanced/healthchecks.md @@ -0,0 +1,48 @@ +# Health Checks + +GoToSocial exposes two health check HTTP endpoints: `/readyz` and `/livez`. + +These can be used to check whether GoToSocial is reachable and able to make simple database queries. + +`/livez` will always return a 200 OK response with no body, in response to both GET and HEAD requests. This is useful to check if the GoToSocial service is alive. + +`/readyz` will return a 200 OK response with no body, in response to both GET and HEAD requests, if GoToSocial is able to run a very simple SELECT query against the configured database backend. If an error occurs while running the SELECT, the error will be logged, and 500 Internal Server Error will be returned, with no body. + +You can use the above endpoints to implement health checks in container runtimes / orchestration systems. + +For example, in a Docker setup, you could add the following to your docker-compose.yaml: + +```yaml +healthcheck: + test: wget --no-verbose --tries=1 --spider http://localhost:8080/readyz || exit 1 + interval: 120s + retries: 5 + start_period: 30s + timeout: 10s +``` + +The above health check will start after 30 seconds, and check every two minutes whether the service is available by doing a HEAD request to `/readyz`. If the check fails five times in a row, the service will be reported as unhealthy. You can use this in whatever orchestration system you are using to force the container to restart. + +!!! warning + When doing database migrations on slow hardware, migration might take longer than the 10 minutes afforded by the above health check. + + On such a system, you may want to increase the interval or number of retries of the health check to ensure that you don't stop GoToSocial in the middle of a migration (which is a very bad thing to do!). + +!!! tip + Though the health check endpoints don't reveal any sensitive info, and run only very simple queries, you may want to avoid exposing them to the outside world. You could do this in nginx, for example, by adding the following snippet to your `server` stanza: + + ```nginx + location /livez { + return 404; + } + location /readyz { + return 404; + } + ``` + + This will cause nginx to intercept these requests *before* they are passed to GoToSocial, and just return 404 Not Found. + +References: + +- [Dockerfile reference](https://docs.docker.com/reference/dockerfile/#healthcheck) +- [Compose file reference](https://docs.docker.com/compose/compose-file/compose-file-v3/#healthcheck) diff --git a/docs/api/swagger.yaml b/docs/api/swagger.yaml index 51d8b6e78..e962c6724 100644 --- a/docs/api/swagger.yaml +++ b/docs/api/swagger.yaml @@ -7878,6 +7878,23 @@ paths: summary: View instance information. tags: - instance + /livez: + get: + operationId: liveGet + responses: + "200": + description: OK + summary: Returns code 200 with no body if GoToSocial is "live", ie., able to respond to HTTP requests. + tags: + - health + head: + operationId: liveHead + responses: + "200": + description: OK + summary: Returns code 200 if GoToSocial is "live", ie., able to respond to HTTP requests. + tags: + - health /nodeinfo/2.0: get: description: 'See: https://nodeinfo.diaspora.software/schema.html' @@ -7892,6 +7909,27 @@ paths: summary: Returns a compliant nodeinfo response to node info queries. tags: - nodeinfo + /readyz: + get: + description: If GtS is not ready, 500 Internal Error will be returned, and an error will be logged (but not returned to the caller, to avoid leaking internals). + operationId: readyGet + responses: + "200": + description: OK + "500": + description: Not ready. Check logs for error message. + summary: Returns code 200 with no body if GoToSocial is "ready", ie., able to connect to the database backend and do a simple SELECT. + tags: + - health + head: + description: If GtS is not ready, 500 Internal Error will be returned, and an error will be logged (but not returned to the caller, to avoid leaking internals). + operationId: readyHead + responses: + "200": + description: OK + summary: Returns code 200 with no body if GoToSocial is "ready", ie., able to connect to the database backend and do a simple SELECT. + tags: + - health /users/{username}/collections/featured: get: description: |- |