curl: Smoke-Test a Web Server in CI
curl -fsS makes curl fail (exit non-zero) on an HTTP error status while staying quiet on success, which is exactly what a smoke test needs.
The simplest post-deploy check is a curl against a health URL. The -f flag maps a 4xx/5xx to a failing exit code, and --retry rides out a server that is still coming up.
What it does
curl -f makes curl return exit code 22 on HTTP responses of 400 or higher instead of printing the error page and exiting 0. -s silences the progress meter and -S still shows real errors. Combined, curl -fsS URL is a clean gate: it succeeds only when the server answers with a success status.
Common usage
# fail the step on any HTTP error status
curl -fsS http://localhost:8080/health
# retry while the server comes up
curl -fsS --retry 5 --retry-delay 2 --retry-connrefused http://localhost:8080/health
# assert a specific status code
test "$(curl -s -o /dev/null -w '%{http_code}' http://localhost:8080/)" = "200"Options
| Flag | What it does |
|---|---|
| -f, --fail | Exit non-zero (22) on HTTP >= 400 |
| -s, --silent | Silence the progress meter |
| -S, --show-error | Show errors even with -s |
| --retry <n> | Retry the request up to n times on transient failure |
| --retry-connrefused | Also retry when the connection is refused |
| -o /dev/null -w "%{http_code}" | Print only the status code for assertions |
In CI
Use curl -fsS --retry 5 --retry-delay 2 --retry-connrefused for a smoke test right after starting a server, so the check tolerates the startup window instead of racing it. Note plain -f does not retry on connection refused unless you add --retry-connrefused. For exact status assertions, use the -w "%{http_code}" form.
Common errors in CI
exit code 7 is "Failed to connect" (server not up or wrong port). exit code 22 is an HTTP error status caught by -f. exit code 28 is a timeout (raise --max-time or add retries). exit code 35 or 60 are TLS errors: 60 is "SSL certificate problem" (add --cacert or, only for a local self-signed test, -k). curl: (6) Could not resolve host means a bad hostname or missing DNS.