Health checks in Nginx - Commands & Configuration

Introduction

Health checks help you know if your web server is working well. They automatically test if your server can respond to requests. This helps keep your website reliable and available.

When you want to make sure your nginx server is running and ready to serve web pages.

When you have multiple servers and want to send traffic only to the healthy ones.

When you want to monitor your server status automatically without manual checks.

When you want to restart or fix your server quickly if it stops responding.

When you want to improve user experience by avoiding broken or slow servers.

Config File - nginx.conf

nginx.conf

worker_processes 1;
events {
    worker_connections 1024;
}
http {
    server {
        listen 8080;

        location / {
            add_header Content-Type text/plain;
            return 200 'Server is healthy';
        }

        location /health {
            access_log off;
            add_header Content-Type text/plain;
            return 200 'OK';
        }
    }
}

This nginx configuration sets up a simple web server listening on port 8080.

The /health location is the health check endpoint. It returns a plain text 'OK' with HTTP status 200 to indicate the server is healthy.

The main / location returns a simple message to show the server is running.

Commands

Start nginx using the custom configuration file to enable the health check endpoint.

Terminal

nginx -c $(pwd)/nginx.conf

Expected Output

No output (command runs silently)

→

-c - Specify the path to the nginx configuration file.

Send a request to the health check endpoint to verify the server is healthy and responding.

Terminal

curl -i http://localhost:8080/health

Expected Output

HTTP/1.1 200 OK

Server: nginx/1.24.0

Date: Thu, 01 Jun 2024 12:00:00 GMT

Content-Type: text/plain

Content-Length: 2

Connection: keep-alive



OK

Send a request to the main server endpoint to confirm the server is running and serving content.

Terminal

curl -i http://localhost:8080/

Expected Output

HTTP/1.1 200 OK

Server: nginx/1.24.0

Date: Thu, 01 Jun 2024 12:00:00 GMT

Content-Type: text/plain

Content-Length: 16

Connection: keep-alive



Server is healthy

Stop the nginx server after testing to free system resources.

Terminal

nginx -s stop

Expected Output

No output (command runs silently)

→

-s - Send a signal to the nginx process (stop in this case).

Key Concept

If you remember nothing else from this pattern, remember: a simple HTTP endpoint returning 200 OK is the easiest way to check if your nginx server is healthy.

Common Mistakes

Not creating a dedicated /health endpoint and checking the main page instead.

The main page might be complex or slow, causing false negatives in health checks.

Create a lightweight /health endpoint that returns a simple 200 OK response quickly.

Forgetting to reload or restart nginx after changing the configuration.

Changes won't take effect until nginx reloads the config, so health checks may fail or be outdated.

Always reload nginx with 'nginx -s reload' or restart it after config changes.

Using a health check that returns non-200 status codes or large content.

Health check systems expect a quick 200 OK response; other codes or big responses may cause false alarms.

Ensure the health check endpoint returns HTTP 200 with minimal content.

Summary

Configure nginx with a simple /health endpoint that returns HTTP 200 OK.

Start nginx with the custom configuration to enable health checks.

Use curl to verify the /health endpoint responds correctly.

Stop nginx after testing to clean up.