https://github.com/mrwogu/portguard
Port Monitoring Health Check Service
https://github.com/mrwogu/portguard
devops go golang health-check http-service kubernetes load-balancer monitoring port-monitoring sre systemd tcp
Last synced: about 2 months ago
JSON representation
Port Monitoring Health Check Service
- Host: GitHub
- URL: https://github.com/mrwogu/portguard
- Owner: mrwogu
- License: mit
- Created: 2025-10-26T13:03:19.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-10-26T19:12:42.000Z (5 months ago)
- Last Synced: 2025-10-26T19:22:44.437Z (5 months ago)
- Topics: devops, go, golang, health-check, http-service, kubernetes, load-balancer, monitoring, port-monitoring, sre, systemd, tcp
- Language: Go
- Homepage:
- Size: 30.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# PortGuard 🛡️
[](https://golang.org)
[](https://github.com/mrwogu/portguard?tab=MIT-1-ov-file)
[](https://github.com/mrwogu/portguard/actions/workflows/ci.yml)
[](https://codecov.io/gh/mrwogu/portguard)
[](https://github.com/mrwogu/portguard/releases/latest)
A lightweight, configurable HTTP service for monitoring port availability and health checking. Perfect for load balancers, Kubernetes health probes, and service monitoring.
📚 **[Quick Start](docs/QUICKSTART.md)** | 📖 **[Examples](docs/EXAMPLES.md)** | ❓ **[FAQ](docs/FAQ.md)**
## 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
```bash
# 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](docs/QUICKSTART.md) for detailed installation instructions including Docker, systemd, and other platforms.**
## Configuration
```yaml
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](docs/EXAMPLES.md) 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](docs/FAQ.md) for integration examples with HAProxy, Nginx, and Kubernetes.**
## Development
```bash
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](docs/RELEASING.md) for creating new releases.
## Support & Documentation
- 📚 [Quick Start Guide](docs/QUICKSTART.md) - Installation & setup
- 📖 [Configuration Examples](docs/EXAMPLES.md) - Various use cases
- ❓ [FAQ](docs/FAQ.md) - Common questions & troubleshooting
- 🚀 [Release Process](docs/RELEASING.md) - For maintainers
---
Made with ❤️ for reliable service monitoring