pingd docs

Install

pingd ships as a single Docker image. The fastest way to a running server is Docker Compose.

Docker (recommended)

Published on GitHub Container Registry as ghcr.io/saeid/pingd.

Run directly

docker run --rm \
  --name pingd \
  -p 7685:7685 \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD=changeme \
  -e PINGD_DATA_DIR=/data \
  -v "$PWD/data:/data" \
  ghcr.io/saeid/pingd:latest

Open http://localhost:7685, log in with the admin credentials you supplied, and create your first topic.

Docker Compose

Save this as docker-compose.yml:

services:
  pingd:
    image: ghcr.io/saeid/pingd:latest
    ports:
      - "7685:7685"
    env_file:
      - .env
    volumes:
      - ./data:/data
    restart: unless-stopped

Use .env.example as the starting point for the .env file referenced above.

Then:

docker compose up -d
Change the admin password. ADMIN_USERNAME and ADMIN_PASSWORD are only used to seed the first user on a fresh database. See Configuration for the full environment variable list.

Build the image yourself

From a clone of the repo:

git clone https://github.com/saeid/pingd
cd pingd
docker build -t pingd:local .

Build from source (no Docker)

Requires Swift 6 or later. Tested on macOS 13+ and Ubuntu Noble; any Linux with a working Swift 6 toolchain should build.

swift build -c release --product pingd
.build/release/pingd serve

Using the CLI

pingd-cli is the command-line client for managing topics, users, tokens, permissions, webhooks, and for tailing messages. It ships inside the same Docker image, and can also be built standalone. 

docker compose exec pingd ./pingd-cli --help
docker compose exec pingd ./pingd-cli topics list
swift build -c release --product pingd-cli
sudo cp .build/release/pingd-cli /usr/local/bin/

pingd-cli --help
alias pingd-cli='docker compose exec -T pingd ./pingd-cli'

pingd-cli topics list

On first boot the server seeds an admin token into $PINGD_DATA_DIR/cli-config.json, so the bundled CLI works out of the box.

Health check

Once it is running, hit:

curl http://localhost:7685/health

The container has a built-in HEALTHCHECK on the same endpoint, so docker ps will show (healthy) when ready.

Reverse proxy

For HTTPS in production, run pingd behind a reverse proxy that handles TLS and forwards traffic to the pingd instance. See the Reverse proxy section for full Nginx and Caddy configs, including the SSE-specific tweaks needed for live streaming endpoints.