dzecevic/pulsequay-checker repository overview

⁠PulseQuay

PulseQuay is an open-source URL monitoring platform built with Go microservices and a React/TypeScript frontend. It continuously checks your targets for HTTP status, DNS resolution, TCP connectivity, TLS validity, certificate expiry, and response body patterns — then alerts you the moment something goes wrong.

Key features:

• HTTP, TCP, DNS, TLS, and cert-expiry checks with configurable intervals
• HMAC-secured checker agents — run your own checker instances anywhere
• Email alerts for down, recovered, cert-expiring, and cert-invalid events
• JWT-based auth with admin/user RBAC

🔗 Live demo: https://pulsequay.zecevic-ninja.com⁠

⁠Running a Remote Checker

This guide explains how to add a checker to your workspace via the PulseQuay UI and then deploy the checker container using the public Docker Hub image.

A checker is a lightweight agent that performs uptime/latency checks against your monitored targets. Running a checker on a separate machine lets you monitor from a different network location or region.

⁠Prerequisites

• Docker 24+ on the machine that will run the checker
• The checker machine must be reachable by the PulseQuay API (the API health-polls every registered checker every 30 seconds via its URL)
• The PulseQuay API must be reachable from the checker machine (the API sends check requests to it)
• A PulseQuay account with workspace admin access

⁠Step 1 — Register the checker in the UI

1. Log in to PulseQuay and navigate to Workspace → Checkers (/workspace/checkers).
2. In the Register a workspace checker form, fill in:
   • Name — a human-readable label (e.g. eu-west-checker)
   • Base URL — the URL at which the PulseQuay API will reach your checker machine (e.g. http://203.0.113.10:8081)
3. Click Register checker.
4. A banner immediately appears showing your one-time HMAC secret (the checker's HMAC_SECRET):
   • Click Copy key to copy it to the clipboard.
   • This key is only shown once. Store it securely before dismissing the banner.

⁠Step 2 — Pull the checker image

On the machine that will run the checker:

docker pull dzecevic/pulsequay-checker:latest

⁠Step 3 — Start the checker container

Use the HMAC_SECRET you copied in Step 1:

docker run -d \
  --name pulsequay-checker \
  --restart unless-stopped \
  -p 8081:8081 \
  -e APP_ENV=production \
  -e LOG_LEVEL=info \
  -e CHECKER_ADDR=:8081 \
  -e HMAC_SECRET=<paste-your-key-here> \
  -e HMAC_ALLOWED_SKEW=30s \
  -e ALLOW_PRIVATE_TARGETS=false \
  dzecevic/pulsequay-checker:latest

Environment variables:

⁠Step 4 — Verify the checker is running

On the checker machine:

curl http://localhost:8081/healthz
# expected: {"status":"ok"}

From another machine (confirm the PulseQuay API can reach it):

curl http://<checker-public-ip>:8081/healthz
# expected: {"status":"ok"}

⁠Step 5 — Confirm the checker is healthy in PulseQuay

The API polls every registered checker every 30 seconds. After about 30 seconds:

1. Go back to Workspace → Checkers (/workspace/checkers).
2. Find your checker in the Available checkers table.
3. The Status column should show up.

⁠Step 6 — Assign targets to the checker (optional)

When creating or editing a monitored target, select your new checker from the Checker dropdown. Targets that have no checker assigned fall back to the workspace default checker.

⁠Updating the checker

docker pull dzecevic/pulsequay-checker:latest
docker stop pulsequay-checker && docker rm pulsequay-checker
# Re-run the docker run command from Step 3 with the same HMAC_SECRET

⁠Viewing logs

docker logs -f pulsequay-checker