superstackinc/pingwatch repository overview

# Pingwatch

**Self-hosted uptime monitoring for NAS, storage, servers, DNS, APIs, and game servers.**

Pingwatch is a lightweight, infrastructure-focused uptime monitoring platform designed to help teams monitor the availability, response time, and historical health of critical infrastructure from a single dashboard.

Monitor NAS devices, storage arrays, servers, network endpoints, DNS records, APIs, WebSocket services, gRPC services, and 100+ game-server protocols without installing agents on the monitored systems.

> **Docker image:** This image contains the Pingwatch **web application**. For the complete deployment, use Docker Compose so that MySQL, health checks, networking, and monitoring components work together correctly.

## Supported Architectures

- `linux/amd64`
- `linux/arm64`

## Image Tags

| Tag | Description |
| --- | --- |
| `latest` | Latest build from the `main` branch |
| `1.2.0` | Specific Pingwatch application version |
| `sha-<git>` | Immutable build identified by Git commit |

---

# Quick Start

The easiest way to install Pingwatch is using the official installation script:

```bash
curl -fsSL https://raw.githubusercontent.com/superstack-oss/Pingwatch/main/install.sh | bash -s -- --yes

Or clone the repository and start the application using Docker Compose:

git clone https://github.com/superstack-oss/Pingwatch.git
cd Pingwatch

cp .env.example .env

docker compose up --build

Once the containers are running, open:

http://127.0.0.1:8000

MySQL is started automatically by Docker Compose, and the application waits for the database health check before starting.

⁠What is Pingwatch?

Know when your infrastructure is reachable.

Infrastructure can fail quietly. A NAS, storage array, hypervisor, DNS service, API, or game server can become unreachable without anyone noticing until a backup, application, or user is affected.

Pingwatch continuously checks the infrastructure that matters to you and provides:

• Real-time status
• Response-time monitoring
• Historical availability
• Outage information
• Last-down information
• Error details
• Analytics
• Incident tracking
• Work notes
• Fleet-wide monitoring statistics

Pingwatch focuses on availability and reachability, rather than attempting to replace a full APM, SIEM, or network-management platform.

⁠Key Features

⁠Six Monitor Types

Monitor infrastructure using the check that makes sense for each device or service:

• Ping / ICMP — Check whether a host or IP responds to ICMP echo requests.
• TCP Port — Verify that a TCP service is accepting connections on a configured port.
• DNS — Resolve DNS records using the resolver and record type you specify.
• WebSocket — Validate ws:// and wss:// WebSocket handshakes.
• gRPC — Use the gRPC health-check protocol and verify the service is SERVING.
• Game Server — Query game servers using their native protocols. Supports 100+ game-server types, including Minecraft, Source, and Bedrock.

⁠Real-Time Status

The dashboard provides a simple operational view with:

• Up
• Down
• Warning
• Unknown
• Paused

⁠Response-Time Monitoring

Every check records round-trip time.

Configure latency thresholds and identify endpoints where response time is increasing before they become completely unavailable.

⁠Device & CI Management

Create and manage monitored configuration items with:

• Display name
• Hostname or IP address
• Asset type
• Monitor type
• Monitoring interval
• Status
• Availability information

Administrators can also import devices using CSV.

⁠Historical Availability

Keep monitoring samples for the configured retention period.

Review availability over:

• 24 hours
• 7 days
• 30 days

⁠Outage History

For each monitored device, view:

• Last-down time
• Outage duration
• Last response time
• Error returned by the monitor
• Historical outages

⁠Analytics

Get a fleet-wide view of your infrastructure with:

• Availability KPIs
• Monitor-type breakdown
• Estate health overview
• Response-time statistics
• Recent attention events
• Average, minimum, and maximum RTT

⁠Incidents & Work Notes

Repeated monitoring failures can be associated with incidents and work notes, allowing operators to preserve operational context instead of losing troubleshooting information in chat or email.

⁠Lightweight Architecture

Pingwatch is designed to stay simple:

• FastAPI application
• MySQL database
• Background monitoring engine
• No agents required on monitored systems

The Pingwatch host performs the monitoring checks and stores the results in MySQL.

⁠Monitor Types

The asset type remains independent from the monitor type. For example, a storage array can be monitored using Ping or TCP Port, while an API can be monitored using TCP, WebSocket, or another supported check.

⁠Dashboard

Pingwatch provides a clean operational dashboard focused on infrastructure availability.

The dashboard allows operators to quickly identify:

• Which devices are currently down
• Which devices have elevated latency
• Current fleet health
• Recent monitoring events
• Availability trends
• Devices requiring attention

Selecting a device opens its detailed monitoring view with status, response time, availability, outages, and historical information.

⁠Certificate Monitoring

Pingwatch can also check public HTTPS endpoints for certificate and domain information.

Certificate monitoring can provide visibility into:

• SSL/TLS certificate status
• Certificate details
• Certificate expiration
• Domain registration expiration

This helps identify certificate and domain-expiry risks before they affect availability.

⁠How It Works

                   ┌─────────────────────┐
                   │     Pingwatch UI    │
                   └──────────┬──────────┘
                              │
                              ▼
                   ┌─────────────────────┐
                   │     FastAPI App     │
                   └──────────┬──────────┘
                              │
              ┌───────────────┴───────────────┐
              │                               │
              ▼                               ▼
     ┌─────────────────┐             ┌─────────────────┐
     │ Monitor Engine  │             │      MySQL      │
     └────────┬────────┘             └─────────────────┘
              │
              ▼
    ┌──────────────────────────────┐
    │ NAS / Storage / Servers      │
    │ DNS / APIs / Game Servers    │
    │ TCP / WebSocket / gRPC       │
    └──────────────────────────────┘

⁠1. Add a Device

Provide:

• Device name
• Hostname or IP
• Asset type
• Monitor type
• Monitoring configuration

Administrators can also upload devices through CSV.

⁠2. Pingwatch Monitors

The background monitoring engine periodically checks every configured device according to its monitoring interval.

⁠3. Metrics Are Collected

Each check records:

• Up/down state
• Response time
• Error information
• Timestamp

Monitoring samples are retained according to the configured retention period.

⁠4. Review Status & History

The dashboard, device details, Analytics, and Incidents sections provide visibility into current and historical infrastructure health.

⁠Use Cases

⁠NAS Monitoring

Monitor NAS devices used for:

• File sharing
• Backups
• Media
• Storage
• Home labs

Identify unreachable NAS devices before they affect dependent workloads.

⁠Storage Infrastructure

Monitor storage arrays and storage-related endpoints alongside the rest of your infrastructure.

Useful for environments containing:

• SAN infrastructure
• Storage arrays
• NAS systems
• Storage management endpoints

⁠Linux & Windows Servers

Monitor application servers, utility servers, hypervisors, and infrastructure hosts using ICMP or TCP-port checks.

⁠Network Infrastructure

Monitor network endpoints and infrastructure devices using ICMP and supported service checks.

⁠DNS Monitoring

Monitor DNS names and validate that required DNS records can be resolved successfully.

⁠API & Service Monitoring

Monitor service endpoints and infrastructure services using TCP, WebSocket, gRPC, and other supported checks.

⁠Game Servers

Monitor more than 100 game-server protocols, including popular Minecraft, Source, and Bedrock environments.

⁠Home Labs

Run Pingwatch locally to monitor:

• NAS
• Servers
• DNS
• Network devices
• APIs
• Game servers

⁠Small Businesses

Maintain a clear operational view of critical infrastructure without deploying a large observability platform.

⁠Docker Deployment

Pingwatch is designed to run with Docker Compose.

⁠Start the Application

cp .env.example .env

docker compose up --build

The Compose deployment starts the required services, including MySQL, and waits for the database health check before starting the application.

Open:

http://127.0.0.1:8000

⁠Run in the Background

docker compose up -d --build

⁠View Logs

docker compose logs -f

⁠Stop Pingwatch

docker compose down

⁠Direct Host Deployment

For environments where ICMP access to LAN devices is important, Pingwatch can also be run directly on the host.

This is particularly useful with macOS Docker Desktop, where containers may not have the same native ICMP access to the LAN as the host operating system.

python3 -m venv .venv

source .venv/bin/activate

pip install -r requirements.txt

uvicorn app.main:app --host 0.0.0.0 --port 8000

Point the application configuration to your MySQL instance.

⁠Requirements

• Python 3.9+
• Python 3.12 recommended
• MySQL
• ICMP access for Ping monitoring

TCP, DNS, WebSocket, gRPC, and game-server checks can run normally when the required network connectivity is available.

⁠Why Pingwatch?

⁠Simple

Focus on the availability signals that operators actually need:

• Reachability
• Response time
• Uptime
• Downtime
• Historical availability

⁠Lightweight

No agents need to be installed on monitored devices.

The Pingwatch host performs the checks and MySQL stores the monitoring history.

⁠Self-Hosted

Run Pingwatch inside your own environment.

Your:

• Sessions
• Devices
• Monitoring data
• Historical results

remain under your control.

⁠Infrastructure-Focused

Designed specifically for infrastructure monitoring rather than application tracing.

Monitor:

• NAS
• Storage
• Servers
• Network endpoints
• DNS
• APIs
• WebSocket services
• gRPC services
• Game servers

⁠Easy to Understand

A straightforward status model:

UP
DOWN
WARNING
UNKNOWN
PAUSED

⁠Useful History

Historical information helps answer questions such as:

• When did the device last go down?
• How long was it unavailable?
• Is latency increasing?
• How often has it failed?
• What was the last error?
• What is the availability over the last 24 hours, 7 days, or 30 days?

⁠Architecture

Pingwatch consists of:

The Docker image provided here is the web application image. For a complete deployment, use the project's Docker Compose configuration.

⁠Data Retention

Pingwatch stores monitoring samples for the configured retention period.

The default history window is:

31 days

Historical availability can be reviewed through:

• Device details
• Availability views
• Outage history
• Analytics

⁠Security & Operations

Pingwatch is designed for self-hosted infrastructure environments.

Recommended deployment practices:

• Keep Pingwatch behind your organization's firewall or reverse proxy.
• Use HTTPS when exposing the dashboard outside a trusted network.
• Protect the .env file and database credentials.
• Restrict access to the monitoring dashboard to authorized users.
• Do not expose MySQL directly to the public internet.
• Keep Docker images and the Pingwatch application updated.

⁠Open Source

Pingwatch is self-hosted and distributed under the AGPL-3.0 license.

The project is designed around transparency, control, and self-hosted infrastructure monitoring.

⁠Project Links

GitHub: https://github.com/superstack-oss/Pingwatch⁠

Demo: https://demo-pingwatch.superstack.in⁠

Documentation: https://github.com/superstack-oss/Pingwatch⁠

⁠Support

For issues, feature requests, or contributions, please use the Pingwatch GitHub repository:

https://github.com/superstack-oss/Pingwatch⁠

⁠License

Pingwatch is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

See the repository for the complete license text and applicable project terms.

⁠Pingwatch

Uptime monitoring for NAS, storage, servers, APIs, DNS, and game infrastructure.

Self-hosted. Lightweight. Infrastructure-focused.