Skip to main content
Get Pongo up and running on your local machine in just a few minutes. This guide will walk you through installation, configuration, and creating your first monitor.

​
Prerequisites

Before you begin, make sure you have:
  • Bun installed (v1.0 or later)
  • Git installed
  • A code editor (VS Code, Cursor, etc.)

​
Installation

1

Clone the repository

Clone Pongo from GitHub and navigate to the project directory:
git clone https://github.com/TimMikeladze/pongo.git
cd pongo
2

Install dependencies

Install all required dependencies using Bun:
bun install
Pongo uses Bun as its runtime. If you don’t have Bun installed, visit bun.sh for installation instructions.
3

Configure environment variables

Copy the example environment file to create your own configuration:
cp .env.example .env
The default configuration uses SQLite, which requires no additional setup. For production deployments, see the Database Configuration guide.
4

Run database migrations

Create the required database tables:
bun run db:sqlite:migrate
This creates a SQLite database file at pongo/pongo.db.
The database driver is auto-detected from your DATABASE_URL. No additional configuration needed.
5

Start the development server

Start the Next.js development server:
bun dev
Open http://localhost:3000 in your browser. You should see the Pongo dashboard.
6

Start the scheduler

Open a second terminal in the same directory and start the scheduler service:
bun scheduler
The scheduler runs your monitors on their configured schedules and evaluates alert conditions.
The scheduler runs as a separate process. In production, you can run it on the same server or deploy it separately. See Scheduler Setup for details.

​
Create Your First Monitor

Now that Pongo is running, let’s create a simple HTTP health check monitor.
1

Create a monitor file

Create a new file in pongo/monitors/ called my-api.ts:
pongo/monitors/my-api.ts
import { monitor } from "../../src/lib/config-types";

export default monitor({
  name: "My API",
  interval: "1m",
  timeout: "30s",

  async handler() {
    const start = Date.now();
    
    try {
      const res = await fetch("https://api.example.com/health");
      const responseTime = Date.now() - start;
      
      return {
        status: res.ok ? "up" : "down",
        responseTime,
        statusCode: res.status,
      };
    } catch (error) {
      return {
        status: "down",
        responseTime: Date.now() - start,
        message: error instanceof Error ? error.message : "Unknown error",
      };
    }
  },
});
Replace https://api.example.com/health with your actual API endpoint.
2

Register the monitor

Add your monitor to pongo/monitors/index.ts:
pongo/monitors/index.ts
import myApi from "./my-api";

export default {
  myApi,
};
3

View your monitor

The scheduler will automatically pick up your new monitor and start running it every minute. Visit http://localhost:3000/monitors to see it in action.
It may take up to a minute for the first check to run. Refresh the page to see the latest results.

​
Add Alerts (Optional)

Make your monitor more useful by adding alerts that notify you when things go wrong.
1

Configure a notification channel

Edit pongo/channels.ts to add a webhook endpoint:
pongo/channels.ts
import { channels } from "../src/lib/config-types";

export default channels({
  slack: {
    type: "webhook",
    url: process.env.SLACK_WEBHOOK_URL!,
  },
});
Then add your Slack webhook URL to .env:
.env
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
2

Add an alert to your monitor

Update your monitor to include alert configuration:
pongo/monitors/my-api.ts
import { monitor } from "../../src/lib/config-types";

export default monitor({
  name: "My API",
  interval: "1m",
  timeout: "30s",
  
  alerts: [
    {
      id: "my-api-down",
      name: "API Down",
      condition: { consecutiveFailures: 3 },
      channels: ["slack"],
      severity: "critical",
    },
  ],

  async handler() {
    // ... same as before
  },
});
This alert fires after 3 consecutive failures and sends a webhook to your Slack channel.

​
Create a Status Page (Optional)

Share your monitor status publicly with a beautiful status page.
1

Create a dashboard

Create a new file pongo/dashboards/public.ts:
pongo/dashboards/public.ts
import type { DashboardConfig } from "@/lib/config-types";

export default {
  name: "Public Status",
  slug: "status",
  public: true,
  monitors: ["myApi"],
  slaTarget: 99.9,
} satisfies DashboardConfig;
2

Register the dashboard

Add it to pongo/dashboards/index.ts:
pongo/dashboards/index.ts
import publicDashboard from "./public";

export default {
  public: publicDashboard,
};
3

View your status page

Visit http://localhost:3000/shared/status to see your public status page.The page includes:
  • Current monitor status
  • Response time charts
  • Uptime percentage
  • Historical data
  • RSS/Atom feeds

​
Next Steps

You now have a working Pongo installation! Here’s what to explore next:

Core Concepts

Learn about monitors, alerts, dashboards, and channels in depth

Deployment Guide

Deploy Pongo to production with Vercel, Fly.io, Docker, or self-hosted

Creating Monitors

Explore different monitor types and advanced patterns

Configuring Alerts

Set up sophisticated alert conditions and notifications

​
Troubleshooting

Make sure:
  1. The scheduler is running (bun scheduler)
  2. Your monitor is registered in pongo/monitors/index.ts
  3. There are no TypeScript errors in your monitor file
  4. You’ve waited at least one interval period
If using PostgreSQL:
  1. Verify your DATABASE_URL in .env is correct
  2. Make sure PostgreSQL is running
  3. Check that the database exists
  4. Verify user permissions
If using SQLite:
  1. Check that pongo/pongo.db exists
  2. Verify file permissions
If port 3000 or 3001 is already in use:
.env
PORT=3001  # For Next.js app
SCHEDULER_PORT=3002  # For scheduler

​
Getting Help

  • Check the Guides for detailed instructions
  • Review the API Reference for complete type documentation
  • Open an issue on GitHub

Build docs developers (and LLMs) love

Get started for freeTalk to us