{"id":20126095,"url":"https://github.com/asicsdigital/healthcheck","last_synced_at":"2026-05-08T12:47:30.659Z","repository":{"id":64303582,"uuid":"137533412","full_name":"asicsdigital/healthcheck","owner":"asicsdigital","description":"Reference implementation of service healthcheck endpoint","archived":false,"fork":false,"pushed_at":"2019-03-06T19:40:03.000Z","size":13,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-01-13T08:12:28.270Z","etag":null,"topics":["docker-compose","golang","healthcheck"],"latest_commit_sha":null,"homepage":"https://healthcheck.staging.asics.digital","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asicsdigital.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-15T21:28:35.000Z","updated_at":"2023-04-06T23:27:02.000Z","dependencies_parsed_at":"2023-01-15T10:01:06.241Z","dependency_job_id":null,"html_url":"https://github.com/asicsdigital/healthcheck","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asicsdigital%2Fhealthcheck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asicsdigital%2Fhealthcheck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asicsdigital%2Fhealthcheck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asicsdigital%2Fhealthcheck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asicsdigital","download_url":"https://codeload.github.com/asicsdigital/healthcheck/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241570921,"owners_count":19984002,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker-compose","golang","healthcheck"],"created_at":"2024-11-13T20:13:48.678Z","updated_at":"2026-05-08T12:47:25.638Z","avatar_url":"https://github.com/asicsdigital.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Healthcheck Reference Implementation\n\nA dedicated healthcheck endpoint is a crucial component of making any web service operable.  This repo contains a reference implementation of ASICS Digital's standard healthcheck endpoint; the intended audience consists of application developers (who can refer to this implementation when building their own healthchecks) and infrastructure engineers (who can refer to this implementation when building tools that consume healthcheck results).\n\nA healthcheck endpoint has the following qualities:\n\n* It is accessed via a static URI path which is not used for any other application functionality.  \n  **Good**: `https://app.example.com/health-check`  \n  **Bad**: `https://app.example.com/login`  \n* It responds to a HTTP GET request.  \n  **Good**: `GET https://app.example.com/health-check`  \n  **Bad**: `POST https://app.example.com/status?action=healthcheck`  \n* It does not require any authentication information.  \n  **Good**: `curl https://app.example.com/health-check`  \n  **Bad**: `curl -H 'Authorization: ablablablabla' https://app.example.com/health-check`  \n  **Worse**: `curl -u 'sooper:seekrit' https://app.example.com/health-check`  \n  **OMG STOPPP**: `curl -H 'X-MyFancyPantsToken: ablablablabla' https://app.example.com/health-check`\n* It returns HTTP response code 200 to indicate a healthy service; any other response code indicates an unhealthy service.  \n  **Good**: `GET https://app.example.com/health-check` -\u003e `HTTP/1.1 200 OK`  \n  **Sideeye**: `GET https://app.example.com/health-check` -\u003e `HTTP/1.1 401 Not Authorized`  \n  **NOOOOOOOO**: `GET https://app.example.com/health-check` -\u003e `HTTP/1.1 200 OK` (in the body: `Status: Unhealthy`)\n* It returns a body consisting solely of JSON-encoded text (with Content-Type `application/json`) that validates against the JSONschema included in this repository.  \n  **Good**: `GET https://app.example.com/health-check` -\u003e `{\"application\":\"my_app\",\"status\":200,\"metrics\":\"{}\"}`  \n  **Unacceptable**: `GET https://app.example.com/health-check` -\u003e `\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\u003chealthcheck\u003e\u003coh\u003enoes\u003c/oh\u003e\u003c/healthcheck\u003e`  \n  **SRSLY WTF**: `GET https://app.example.com/health-check` -\u003e `\u003c!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 Transitional//EN\" \"http://www.w3.org/TR/html4/loose.dtd\"\u003e\u003chtml\u003e\u003chead\u003e\u003ctitle\u003eoh noes\u003c/title\u003e\u003c/head\u003e\u003cbody\u003e\u003cp\u003eOOPSY WOOPSY\u003c/p\u003e\u003c/body\u003e\u003c/html\u003e`\n\n## The purpose of a healthcheck\n\nFIXME\n\n## Using this reference implementation\n\nThere are several ways to start up this reference implementation for testing or experimentation.  The application reads some runtime configuration values from its environment; these values control the information returned by the healthcheck endpoint.\n\n### Our publically-hosted endpoint\n\n```sh\n$ curl https://healthcheck.staging.asics.digital/healthcheck | jq .\n```\n\nTo change the values, access the us-east-1 staging Consul cluster at https://asics-services.us-east-1.staging.asics.digital and modify the entries under `healthcheck/` in the key/value store.  Changes will be reflected in the endpoint immediately.\n\n### Local Docker\n\nIn one shell:\n\n```sh\n$ docker pull asicsdigital/healthcheck:latest\n$ docker run --rm -it \\\n  -p 8080:8080 \\\n  -e CONSUL_HTTP_ADDR=\"https://asics-services.us-east-1.staging.asics.digital\" \\\n  -e CONSUL_HTTP_AUTH=\"consul:GET_THIS_FROM_1PASSWORD\" \\\n  asicsdigital/healthcheck:latest\n```\n\nIn another shell:\n\n```sh\ncurl http://localhost:8080/healthcheck | jq .\n```\n\nYou can also pass in a VAULT_TOKEN and a VAULT_ADDR to this example to read secrets from Vault.\n\n( Someone will have had to have run `vault write secret/healthcheck HONEYCOMB_API_KEY=\u003cKEY` at some point, check your vault )\n\n```sh\ndocker run --rm -it \\\n  -p 8080:8080 \\\n  -e CONSUL_HTTP_ADDR=\"https://asics-services.us-east-1.staging.asics.digital\" \\\n  -e CONSUL_HTTP_AUTH=\"consul:GET_THIS_FROM_1PASSWORD\" \\\n  -e VAULT_ADDR=\"https://vault.us-east-1.staging.asics.digital\" \\\n  -e VAULT_TOKEN='\u003cA VAULT TOKEN\u003e' \\\n  asicsdigital/healthcheck:latest\n```\n\n### Build from source\n\nIf you want to entirely avoid the dependency on Consul, build the application from source.  You'll need a Golang development environment installed locally.\n\nIn one shell:\n\n```sh\n$ go get github.com/asicsdigital/healthcheck\n$ cd ~/go/src/github.com/asicsdigital/healthcheck\n$ go build\n$ HEALTHCHECK_APP=my_app HEALTHCHECK_STATUS=500 HEALTHCHECK_METRICS='{\"everything\":\"terrible\"}' ./healthcheck\n```\n\nIn another shell:\n\n```sh\ncurl http://localhost:8080/healthcheck | jq .\n```\n\n## The promised JSONschema\n\nAfter following the above instructions:\n\n```sh\ncurl http://localhost:8080/schema.json\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasicsdigital%2Fhealthcheck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasicsdigital%2Fhealthcheck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasicsdigital%2Fhealthcheck/lists"}