This Docker image combines:

• Nginx Open Source (v1.24.0) compiled from source
• Active Health Check Module (nginx_upstream_check_module)
• Nginx UI (Web-based management interface)

🎯 A free alternative to Nginx Plus active health checks - Get enterprise-grade health checking without the enterprise price tag!

• ✅ Active health checks for upstream servers (similar to Nginx Plus)
• ✅ Web-based UI for managing Nginx configurations
• ✅ SSL/TLS support with HTTP/2
• ✅ Stream module for TCP/UDP load balancing
• ✅ Real-time upstream health status monitoring
• ✅ Configuration editor with syntax highlighting
• ✅ Let's Encrypt certificate management

docker pull ghcr.io/deviant101/nginx-active-healthcheck-ui:latest

docker run -d \
  --name nginx-healthcheck-ui \
  -p 80:80 \
  -p 443:443 \
  -p 8080:8080 \
  -p 9000:9000 \
  -v nginx_config:/etc/nginx \
  -v nginx_ui_config:/etc/nginx-ui \
  --restart unless-stopped \
  ghcr.io/deviant101/nginx-active-healthcheck-ui:latest

git clone https://github.com/deviant101/nginx-active-healthcheck-ui.git
cd nginx-active-healthcheck-ui

Option A: Using Docker Compose

docker-compose up -d --build

Option B: Build and run manually

docker build -t nginx-healthcheck-ui .

docker run -d \
  --name nginx-healthcheck-ui \
  -p 80:80 \
  -p 443:443 \
  -p 8080:8080 \
  -p 9000:9000 \
  -v nginx_config:/etc/nginx \
  -v nginx_ui_config:/etc/nginx-ui \
  --restart unless-stopped \
  nginx-healthcheck-ui

1. Access Nginx UI at http://localhost:9000
2. Create your admin account on first visit
3. Configure your upstream servers and sites through the UI

Add active health checks to your upstream blocks in nginx configuration:

upstream backend {
    server backend1.example.com:8080;
    server backend2.example.com:8080;
    server backend3.example.com:8080;

    # Active health check configuration
    check interval=3000 rise=2 fall=3 timeout=1000 type=http;
    check_http_send "HEAD /health HTTP/1.0\r\n\r\n";
    check_http_expect_alive http_2xx http_3xx;
}

• tcp: Simple TCP connection check
• http: HTTP request check
• ssl_hello: SSL handshake check
• mysql: MySQL protocol check
• ajp: AJP protocol check

/etc/nginx/
├── nginx.conf           # Main configuration
├── conf.d/              # Additional configurations
├── sites-available/     # Available site configurations
├── sites-enabled/       # Enabled site configurations
├── streams-available/   # Available stream configurations
├── streams-enabled/     # Enabled stream configurations
└── ssl/                 # SSL certificates

/etc/nginx-ui/
├── app.ini              # Nginx UI configuration
└── database.db          # Nginx UI database

/var/log/nginx/
├── access.log           # Nginx access log
└── error.log            # Nginx error log

You can customize the Nginx UI configuration by mounting your own app.ini file or setting these in the configuration:

• HttpPort: Nginx UI port (default: 9000)
• JWTSecret: JWT secret for authentication
• Database: Path to SQLite database

1. Change default secrets: Update JWTSecret and Secret in /etc/nginx-ui/app.ini
2. Restrict status endpoints: The status endpoints are restricted to private networks by default
3. Use HTTPS: Configure SSL/TLS for production environments
4. Firewall: Consider restricting access to port 9000 (Nginx UI)

upstream api_servers {
    server api1.internal:3000;
    server api2.internal:3000;
    server api3.internal:3000;

    # Health check every 5 seconds
    # Mark as UP after 2 successful checks
    # Mark as DOWN after 3 failed checks
    check interval=5000 rise=2 fall=3 timeout=2000 type=http;
    check_http_send "GET /api/health HTTP/1.1\r\nHost: localhost\r\n\r\n";
    check_http_expect_alive http_2xx;
}

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://api_servers;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

A sample nginx configuration file (backend-nginx.conf) is included for your backend servers. This config provides a /health endpoint that the load balancer uses for health checks.

1. Copy backend-nginx.conf to your backend server:

   scp backend-nginx.conf user@backend-server:/etc/nginx/nginx.conf

2. Restart nginx on the backend:

   sudo nginx -t && sudo systemctl restart nginx

3. Verify the health endpoint:

   curl http://localhost/health
   # Should return: healthy

docker exec nginx-ui-healthcheck nginx -t
docker exec nginx-ui-healthcheck nginx -s reload

# Nginx logs
docker logs nginx-ui-healthcheck

# Or access log files directly
docker exec nginx-ui-healthcheck tail -f /var/log/nginx/error.log

curl http://localhost:8080/upstream_status
curl http://localhost:8080/upstream_status_json

• Nginx: BSD-like license
• nginx_upstream_check_module: BSD license
• Nginx UI: AGPL-3.0 license