OverviewQuickstartSDKAlertsAPISelf-host

Self-host

Run on one VPS

Puse is self-hostable by design: Fastify ingest, Next.js dashboard, alerts worker, Postgres. Your traces never leave your infrastructure.

Requirements

  • Node.js 22+, pnpm 9
  • Docker (for Postgres in development)
  • 2 vCPU, 4 GB RAM minimum (small VPS)

Local / VPS setup

git clone <your-puse-repo>
cd puse
cp .env.example .env
# set SESSION_SECRET (32+ chars) and DATABASE_URL

docker compose -f docker-compose.dev.yml up -d
pnpm install
pnpm build

# apply migrations once:
pnpm db:migrate

pnpm ingest:dev       # :8789
pnpm dashboard:dev    # :3002
pnpm worker:dev       # alerts

Services

  • ingest — Fastify API on port 8789
  • dashboard — Next.js marketing + admin on port 3002
  • worker — alert checks (error rate / cost spikes)
  • postgres — trace storage (dev Compose maps :5433)

First account

Open /signup to create an organization and owner. Then create a project, copy the pu-… API key, and point the SDK at your ingest URL.

SDK configuration

const puse = createPuse({
  apiKey: process.env.PUSE_API_KEY!,
  baseUrl: process.env.PUSE_BASE_URL ?? "http://localhost:8789",
});

Alerts

Configure Slack + thresholds per project in the dashboard. Optionally set a global SLACK_WEBHOOK_URL on the worker as a fallback.