Nhost Monitoring with Vigilmon

Nhost is an open-source, self-hostable backend-as-a-service platform that bundles Hasura (GraphQL over Postgres), an authentication service, a file storage service, and serverless functions into a single deployable stack. Teams use Nhost to build full-stack applications without writing backend boilerplate. Because Nhost ties together multiple services — Hasura, Auth, Storage, and Postgres — a failure in any one of them can silently degrade your application.

This guide covers how to monitor every layer of a Nhost deployment using Vigilmon, from the GraphQL engine down to the storage API.

Nhost Architecture and What Can Go Wrong

A self-hosted Nhost deployment exposes several independent services:

| Service | Default Port | Role | |---------|-------------|------| | Hasura GraphQL Engine | 8080 | GraphQL API over Postgres | | Nhost Auth | 4000 | User authentication and sessions | | Nhost Storage | 5000 | File uploads and downloads | | Nhost Dashboard | 3030 | Admin console | | Traefik (proxy) | 443/80 | Reverse proxy and TLS termination |

Each service runs as a separate Docker container. A crash or misconfiguration in one service does not necessarily take down the others. Without external monitoring, you may have a working GraphQL API while Auth is silently rejecting all login requests.

Health Endpoints to Monitor

Hasura GraphQL Engine — /healthz

GET https://your-nhost-domain.com/v1/graphql/healthz

Or if your Hasura instance is exposed directly:

GET https://hasura.your-nhost-domain.com/healthz

A healthy response:

HTTP 200 OK

OK

This endpoint verifies that Hasura is running and connected to Postgres. A non-200 response means your entire GraphQL API is down.

Nhost Auth — /healthz

GET https://your-nhost-domain.com/v1/auth/healthz

Response when healthy:

{
  "status": "OK"
}

The Auth service handles user registration, login, JWT issuance, and OAuth flows. When it is down, users cannot sign in or register, and existing sessions may not be validated.

Nhost Storage — /health

GET https://your-nhost-domain.com/v1/storage/health

Response:

{
  "status": "OK"
}

Storage handles file uploads and serves files to users. Monitor it separately — a storage outage means users cannot upload avatars, documents, or other assets even while GraphQL queries still work.

Hasura Metadata Consistency

GET https://your-nhost-domain.com/v1/graphql/v1/version

Response:

{
  "version": "v2.36.0",
  "is_metadata_inconsistent": false
}

The is_metadata_inconsistent field signals that Hasura has loaded but its table relationships, permissions, or event triggers are broken. This can happen after a migration failure and will not cause /healthz to fail — only this endpoint reveals the problem.

Setting Up Vigilmon Monitors

Monitor 1: Hasura GraphQL Health

1. Log in to Vigilmon → Monitors → New Monitor
2. Type: HTTP
3. Method: GET
4. URL: https://your-nhost-domain.com/v1/graphql/healthz
5. Interval: 1 minute
6. Expected status: 200
7. Keyword check: OK

This catches Hasura process failures and Postgres connectivity issues within 60 seconds.

Monitor 2: Auth Service Health

1. Type: HTTP
2. Method: GET
3. URL: https://your-nhost-domain.com/v1/auth/healthz
4. Interval: 1 minute
5. Expected status: 200
6. Keyword check: OK

Configure an alert to fire after 1 failed check — authentication failures are immediately user-visible.

Monitor 3: Storage Service Health

1. Type: HTTP
2. Method: GET
3. URL: https://your-nhost-domain.com/v1/storage/health
4. Interval: 2 minutes
5. Expected status: 200
6. Keyword check: OK

Monitor 4: Hasura Metadata Consistency

1. Type: HTTP
2. Method: GET
3. URL: https://your-nhost-domain.com/v1/graphql/v1/version
4. Interval: 5 minutes
5. Keyword check: "is_metadata_inconsistent":false

This catches silent metadata corruption that /healthz alone will not surface.

Monitor 5: Dashboard Availability

1. Type: HTTP
2. Method: GET
3. URL: https://your-nhost-domain.com
4. Interval: 5 minutes
5. Expected status: 200

Docker Compose Health Checks

Nhost uses Docker Compose for self-hosted deployments. Add health checks to your docker-compose.yml to complement Vigilmon's external perspective:

services:
  hasura:
    image: hasura/graphql-engine:v2.40.0
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3

  auth:
    image: nhost/hasura-auth:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4000/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3

  storage:
    image: nhost/hasura-storage:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Docker health checks catch internal container failures, but Vigilmon catches failures at the network boundary — including Traefik misconfigurations, TLS errors, and DNS failures that internal checks cannot see.

Alert Configuration

Slack Alerts

Go to Alert Channels → Slack in Vigilmon and add your workspace webhook. For Auth and GraphQL monitors, set alerts to trigger on 1 failed check since these failures immediately affect users. For the metadata consistency monitor, allow 2 failed checks to avoid false positives from momentary inconsistency windows during migrations.

Webhook for Incident Routing

// Node.js webhook handler
app.post('/webhooks/vigilmon', express.json(), (req, res) => {
  const { event, monitor } = req.body;

  const severity = monitor.url.includes('/auth/') ? 'critical' : 'warning';

  if (event === 'down') {
    createIncident({
      title: `Nhost service DOWN: ${monitor.url}`,
      severity,
      source: 'vigilmon',
    });
  } else if (event === 'up') {
    resolveIncident({ source: 'vigilmon', url: monitor.url });
  }

  res.json({ received: true });
});

Register this URL under Alert Channels → Webhook in Vigilmon.

Alerting Strategy

| Component | Endpoint | Alert Threshold | |-----------|----------|-----------------| | Hasura GraphQL | /v1/graphql/healthz | 1 failed check | | Auth service | /v1/auth/healthz | 1 failed check | | Storage service | /v1/storage/health | 1 failed check | | Metadata consistency | /v1/graphql/v1/version | 2 failed checks | | Dashboard | / | 3 failed checks |

Summary

| Component | Endpoint | Vigilmon Check | |-----------|----------|----------------| | Hasura GraphQL Engine | /v1/graphql/healthz | Status 200 + keyword OK | | Nhost Auth | /v1/auth/healthz | Status 200 + keyword OK | | Nhost Storage | /v1/storage/health | Status 200 + keyword OK | | Metadata consistency | /v1/graphql/v1/version | Keyword "is_metadata_inconsistent":false | | Admin dashboard | / | Status 200 |

Nhost's multi-service architecture means a single health check is not enough. With Vigilmon's per-service monitors and 1-minute check intervals, you'll catch Auth failures, Storage outages, and metadata corruption as soon as they happen — not when users start filing support tickets.

Further Reading

• Hasura GraphQL Engine Monitoring with Vigilmon
• Supabase Monitoring with Vigilmon
• Docker Container Monitoring with Vigilmon
• Monitoring MinIO Object Storage with Vigilmon