PortGuard 🛡️¶

A lightweight, configurable HTTP service for monitoring port availability and health checking. Perfect for load balancers, Kubernetes health probes, and service monitoring.

PortGuard

📚 Quick Start | 📖 Examples | ❓ FAQ

Features¶

✨ Simple & Lightweight - Single binary, minimal dependencies
⚙️ Configurable - YAML-based configuration
🔍 Detailed Health Checks - JSON responses with per-port status
🔒 Secure - Optional HTTP Basic Authentication
🚀 Production Ready - Systemd, Docker, Kubernetes support

Quick Start¶

# Download latest release
wget https://github.com/mrwogu/portguard/releases/latest/download/portguard-linux-amd64.tar.gz
tar -xzf portguard-*.tar.gz

# Create config
mkdir -p /etc/portguard
cp config.yaml.example /etc/portguard/config.yaml
nano /etc/portguard/config.yaml

# Run
./portguard

📖 See Quick Start Guide for detailed installation instructions including Docker, systemd, and other platforms.

Configuration¶

server:
  port: "8888"
  timeout: 2s  # Default timeout for all checks

  # Optional: HTTP Basic Authentication
  auth:
    enabled: false  # Set to true to enable
    username: "admin"
    password: "secure-password"

checks:
  - host: "mail.example.com"
    port: 25
    name: "SMTP"
    description: "Mail Transfer Protocol"
    # Uses default timeout (2s)

  - host: "remote-api.example.com"
    port: 443
    name: "Remote API"
    description: "Remote API endpoint"
    timeout: 10s  # Custom timeout for this check

📖 See Examples for more configuration examples (web apps, databases, Kubernetes, microservices).

API Endpoints¶

/health - Detailed JSON status (200 OK = healthy, 503 = unhealthy)
/live - Simple liveness probe (always returns 200 OK)
/ - HTML info page

📖 See FAQ for integration examples with HAProxy, Nginx, and Kubernetes.

Development¶

make build          # Build binary
make test           # Run tests with coverage
make test-coverage  # Generate HTML coverage report
make lint           # Run linter
make build-all      # Build for all platforms

See Makefile for all available commands.

👨‍💻 For contributors: See Release Process for creating new releases.

Support & Documentation¶

📚 Quick Start Guide - Installation & setup
📖 Configuration Examples - Various use cases
❓ FAQ - Common questions & troubleshooting
🚀 Release Process - For maintainers

Made with ❤️ for reliable service monitoring