Health Checks

A health check tells Spark to wait until a service is actually ready before running the test. Without one, Spark might send a request before the server has finished starting — leading to a false failure.

Most services need a few seconds to boot. A health check is a command that Spark retries until it succeeds (e.g., "can I reach port 8080?").

Always add health checks to your services. Without them, Spark starts the container and immediately runs the test. If the service hasn't finished booting, you'll get "connection refused" errors that look like test failures.

Formats

Spark supports three ways to define health checks:

The simplest form — a shell command that Spark retries until it exits with code 0.

healthcheck:
  test: "curl -f http://localhost:8080/health"
  retries: 30

Docker Compose compatible syntax. Also supports ["CMD", "arg1", "arg2"] for commands without a shell, and ["NONE"] to disable.

healthcheck:
  test: ["CMD-SHELL", "curl -f http://localhost:8080/health"]
  retries: 30

If the Docker image already has a built-in HEALTHCHECK instruction, just enable it:

healthcheck: true

Fields

Field	Default	Description
`test`	—	Command to run (required)
`retries`	`30`	How many times to retry before giving up
`interval`	`1s`	Time between retries
`timeout`	`3s`	Timeout per check attempt
`startPeriod`	`0s`	Grace period before checks start
`startInterval`	—	Interval during the start period

Spark polls Docker's health status every 500ms until the container reports healthy or all retries are exhausted.

Common patterns

Copy-paste these. Here are ready-to-use health checks for the most popular services:

# HTTP server
healthcheck:
  test: "curl -f http://localhost:8080/health"
  retries: 30

# PostgreSQL
healthcheck:
  test: "pg_isready"
  retries: 10

# Redis
healthcheck:
  test: "redis-cli ping"
  retries: 10

# MySQL
healthcheck:
  test: "mysqladmin ping -h localhost"
  retries: 30

# Generic TCP port check
healthcheck:
  test: "nc -z localhost 3000"
  retries: 20