Self-hosted checker

Deploy your own checker

Run the PulseQuay checker agent on your own infrastructure — a cloud VM, a machine inside your office, or anywhere inside a private network. You choose where checks originate; PulseQuay handles the scheduling, alerting, and history.

View on Docker Hub

1 Register the checker in the UI

You need workspace admin access in PulseQuay. All checker management happens at Workspace → Checkers (/workspace/checkers).

  1. Navigate to Workspace → Checkers and find the Register a workspace checker form.
  2. Fill in Name — a human-readable label, e.g. office-checker or eu-west.
  3. Fill in Base URL — the address at which the PulseQuay API will reach your checker machine, e.g. http://203.0.113.10:8081. This must be reachable from the PulseQuay server.
  4. Click Register checker.
A banner appears with your one-time HMAC_SECRET. Click Copy key and store it securely — it is shown only once. If you lose it, a SuperAdmin can rotate it and you will need to restart the container with the new value.

2 Pull the checker image

On the machine that will run the checker:

docker pull dzecevic/pulsequay-checker:latest

Pin to a specific version tag for production deployments. The Docker Hub page lists all available tags.

3 Start the checker container

Paste the HMAC_SECRET you copied in Step 1 into the command below: 

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
Variable Required Description
HMAC_SECRET required The one-time key shown after registration in Step 1.
CHECKER_ADDR required Address and port the checker listens on. Default: :8081
HMAC_ALLOWED_SKEW optional Clock-skew tolerance for HMAC validation. Default: 30s
ALLOW_PRIVATE_TARGETS optional Set to true to allow the checker to reach private/internal IP ranges (RFC 1918 addresses). Useful for monitoring internal services. Default: false
LOG_LEVEL optional debug, info, warn, error. Default: info
APP_ENV optional production or development. Default: production
Monitoring internal services? Set ALLOW_PRIVATE_TARGETS=true and deploy the checker inside your private network. It will then be able to reach addresses like 10.0.0.x, 192.168.x.x, and 172.16–31.x.x that a public checker cannot.

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"}

5 Confirm the checker is healthy in PulseQuay

PulseQuay polls every registered checker every 30 seconds. After about 30 seconds, return to Workspace → Checkers — your checker should show status up in the table.

6 Assign targets to the checker

When creating or editing a monitored target, select your checker from the Checker dropdown. Targets with no checker assigned fall back to the workspace default. This lets you route specific targets — internal services, region-sensitive endpoints — through your custom checker while keeping everything else on the default.

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