pingd docs

Getting started

From zero to delivered notification in under five minutes. Assumes pingd is already running on http://localhost:7685. See Install if not.

1. Log in as the admin user

Use the ADMIN_USERNAME and ADMIN_PASSWORD you set on first boot:

curl -s http://localhost:7685/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"changeme","label":"local"}'
# the bundled CLI is already authenticated via cli-config.json,
# no login step needed inside the container
docker compose exec pingd ./pingd-cli users list
import requests

response = requests.post(
    "http://localhost:7685/auth/login",
    json={"username": "admin", "password": "changeme", "label": "local"},
).json()
token = response["token"]

Response:

{
  "token": "bearer-token-here",
  "userID": "uuid",
  "username": "admin"
}

Stash the token in your shell:

export TOKEN="bearer-token-here"

2. Create a topic

Topics route messages. Names use a-z 0-9 . - _ and are at least 3 characters long. The simplest public topic allows both public read and public publish.

curl -s http://localhost:7685/topics \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "alerts", "publicRead": true, "publicPublish": true }'
pingd-cli topics create --name alerts --public-read --public-publish
requests.post(
    "http://localhost:7685/topics",
    headers={"Authorization": f"Bearer {token}"},
    json={"name": "alerts", "publicRead": True, "publicPublish": True},
)

Public flags decide anonymous read and publish. For restricted topics, use bearer-token permissions or per-topic share tokens. Full rules are in Topics and Permissions.

3. Publish a message

curl -s http://localhost:7685/topics/alerts/messages \
  -H 'Content-Type: application/json' \
  -d '{ "payload": { "body": "Hello" } }'
pingd-cli messages publish --topic alerts --body "Hello"
requests.post(
    "http://localhost:7685/topics/alerts/messages",
    json={"payload": {"body": "Hello"}},
)

4. Watch the live stream

Tail the topic over Server-Sent Events. New messages arrive as they happen.

curl -N http://localhost:7685/topics/alerts/stream
pingd-cli messages watch --topic alerts
with requests.get(
    "http://localhost:7685/topics/alerts/stream",
    stream=True,
) as response:
    for line in response.iter_lines():
        if line:
            print(line.decode())

5. Subscribe a browser

Open http://localhost:7685 in a browser, log in, and click the bell icon to enable browser push. The dashboard registers a Web Push device for you and subscribes it to every topic you open. From then on, the browser receives notifications even when the dashboard tab is closed.

Note: Web Push requires HTTPS in browsers. localhost is exempt for development. To deliver to browsers from a public host, set up TLS and configure Web Push (VAPID).

What next?