Service health checks

Health checks show whether Gramax Enterprise Server can accept requests and which functions have errors. Use the health endpoints in Kubernetes, a load balancer, or a monitoring system to distinguish a complete service outage from a failure of an individual module.

Configure health checks

1. Create a shared secret and pass the same value to the Enterprise and documentation portal containers:

   HEALTHCHECK_TOKEN={SECRET_KEY}

2. To let Enterprise collect the documentation portal status, pass its internal address to the Enterprise container:

   DOCPORTAL_SERVICE_URL=http://docportal:3000

   If the variable is not set, Enterprise reports only its own status.

3. Restrict access to the health endpoints at the internal network level. Detailed responses require a token, but probes are available without authorization for Kubernetes and load balancers.

Health endpoints

/health/services is available on Enterprise. The other endpoints are available on Enterprise and the documentation portal.

Check the status

Check liveness without a token:

curl https://{ges_url}/health/liveness

Successful response:

{
  "status": "healthy"
}

Check readiness:

curl https://{ges_url}/health/readiness

Get the detailed Enterprise status:

curl \
  -H "Authorization: Bearer {SECRET_KEY}" \
  https://{ges_url}/health

Get the overall GES snapshot:

curl \
  -H "Authorization: Bearer {SECRET_KEY}" \
  https://{ges_url}/health/services

Enterprise refreshes the documentation portal status in the background. The check runs every 5 minutes with a 10-second timeout. A snapshot older than 15 minutes is considered stale.

Service statuses

Only Enterprise produces the unreachable status. It means that the service did not respond, rejected the token, returned an unknown response format, or its health endpoint is unavailable. The unhealthy status means that the service responded and reported a critical error itself.

Module states

The detailed response contains a checks object with the status of each module:

The critical field shows whether a module failure affects the readiness of the whole service. The code field contains a stable reason code, and checkedAt contains the time of the last check.

Abbreviated response example:

{
  "status": "degraded",
  "service": "enterprise",
  "checks": {
    "git-proxy": {
      "state": "enabled",
      "status": "degraded",
      "critical": true,
      "code": "GIT_SERVER_TOKEN_EXPIRING",
      "checkedAt": "2026-09-01T10:00:00.000Z"
    },
    "postgresql": {
      "state": "disabled",
      "critical": false,
      "checkedAt": "2026-09-01T10:00:00.000Z"
    }
  }
}

Checked modules

Enterprise checks:

• Enterprise API, configuration, and the permissions provider.

• License validity and expiration.

• Git Proxy, Git server availability, and GIT_SERVER_TOKEN expiration.

• PostgreSQL, when enabled through ENTERPRISE_DB_TYPE.

• Metrics, when PostgreSQL is available for them.

The documentation portal checks:

• Content reading: workspace availability and errors from actual catalog and article requests.

• Auto-pull: startup and the result of the latest content update.

• Search: availability of the configured search module.

A disabled non-critical module does not degrade the overall status. For example, if PostgreSQL is not configured and no ENTERPRISE_DB_* variables are passed, postgresql and its dependent metrics modules are reported as disabled.