mcpField
S
serverpod-health-checks

serverpod-health-checks

github.com/serverpodCloud & DevOps3.3k43 installsUpdated 1d ago
Repository

About serverpod-health-checks

A skill for adding HTTP health endpoints to Serverpod’s main API server. It explains liveness, readiness, and startup checks, built-in dependency indicators, and custom indicators for probe responses.

Key features

  1. 01Provide /livez, /readyz, and /startupz endpoints
  2. 02Check startup, database, and Redis indicators
  3. 03Add custom health indicators
  4. 04Configure indicator timeouts and result caching
  5. 05Return status-only or authenticated JSON details

Use cases

  1. 01Configure Kubernetes liveness probes
  2. 02Check dependency readiness before serving traffic
  3. 03Report server startup completion
  4. 04Include a custom service in readiness checks

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/serverpod/serverpod --skill serverpod-health-checks

After installing, type/serverpod-health-checksin Claude Code to confirm it loaded.

Details

From the project README

Serverpod Health Checks

Kubernetes-style HTTP health endpoints on the main API server (default port 8080), not the optional web server (default port 8082). Unauthenticated: HTTP status only (200/503). Authenticated requests get detailed JSON (RFC Health Check Response Format) through the server's normal authentication handler.

Endpoints

  • /livez — Process alive? Does not check DB/Redis. Use for liveness probes.
  • /readyz — Dependencies healthy? Returns 503 if not. Use for readiness probes.
  • /startupz — Server finished initializing? Use for startup probes.

Built-in indicators

  • ServerpodStartupIndicator — startup complete
  • DatabaseHealthIndicator — configured database (if enabled)
  • RedisHealthIndicator — Redis (if enabled)

Custom health indicator

class StripeApiIndicator extends HealthIndicator<double> {
  @override String get name => 'stripe:api';
  @override String get componentType => HealthComponentType.component.name;
  @override String get observedUnit => 'ms';
  @override Duration get timeout => const Duration(seconds: 3);

  @override
  Future<HealthCheckResult> check() async {
    final sw = Stopwatch()..start();
    try {
      await stripeClient.ping();
      return pass(observedValue: sw.elapsedMilliseconds.toDouble());
    } catch (e) {
      return fail(output: 'Stripe unavailable: $e');
    }
  }
}

Registration

final pod = Serverpod(
  args,
  healthConfig: HealthConfig(
    cacheTtl: Duration(seconds: 2), // default is 1 second
    additionalReadinessIndicators: [StripeApiIndicator()],
    additionalStartupIndicators: [CacheWarmupIndicator()],
  ),
);

Each indicator can override timeout (default 5s). cacheTtl caches results to reduce load under frequent probing. Serverpod also has a legacy GET / health response with a different, simpler contract; use /livez, /readyz, and /startupz for Kubernetes probes.

Comments

Markdown supported