Installation

This guide will help you set up a self-hosted instance of PingPilot. Perfect for developers who want full control over their event monitoring infrastructure.

Looking to just use PingPilot? Check out the Quickstart guide instead. This installation guide is for self-hosting the platform.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js v18 or higher
npm or pnpm package manager
PostgreSQL database (local or hosted like Neon)
Git for version control

We recommend using Neon for PostgreSQL as it provides serverless Postgres with a generous free tier.

Clone the Repository

Start by cloning the PingPilot repository:

git clone https://github.com/vishnu-mouli-102408/ping-pilot.git
cd ping-pilot

Install Dependencies

Install all required packages:

npm install

The postinstall script will automatically run prisma generate to set up the database client.

Environment Configuration

Create Environment File

Create a .env file in the root directory:

cp .env.example .env

Configure Database

Add your PostgreSQL connection string:

.env

DATABASE_URL="postgresql://user:password@host:5432/pingpilot?sslmode=require"

Neon (Recommended)
Local PostgreSQL
Other Providers

Create a free account at neon.tech
Create a new project
Copy the connection string from the dashboard
Paste it into your .env file

DATABASE_URL="postgresql://postgres:password@localhost:5432/pingpilot"

Make sure your PostgreSQL service is running:

# macOS (Homebrew)
brew services start postgresql

# Linux (systemd)
sudo systemctl start postgresql

Configure Clerk Authentication

PingPilot uses Clerk for authentication. Set up your Clerk application:

Create a free account at clerk.com
Create a new application
Copy your API keys from the Clerk dashboard
Add them to your .env file:

.env

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
CLERK_SECRET_KEY="sk_test_..."

Never commit your CLERK_SECRET_KEY to version control. Keep it secure and use environment variables in production.

Configure Discord Bot

To send Discord notifications, create a Discord bot:

Go to Discord Developer Portal
Click “New Application” and give it a name
Navigate to the “Bot” section
Click “Reset Token” to get your bot token
Add the token to your .env file:

.env

DISCORD_BOT_TOKEN="your_discord_bot_token_here"

Enable the following Privileged Gateway Intents:
- Presence Intent
- Server Members Intent
- Message Content Intent

Configure Telegram Bot (Optional)

For Telegram notifications:

Message @BotFather on Telegram
Send /newbot and follow the instructions
Copy the bot token provided
Add it to your .env file:

.env

TELEGRAM_BOT_TOKEN="your_telegram_bot_token_here"

Configure Email (Optional)

For email notifications, configure an SMTP provider:

.env

SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="[email protected]"
SMTP_PASSWORD="your-app-password"
SMTP_FROM="[email protected]"

For Gmail, you’ll need to generate an App Password instead of using your regular password.

Configure Stripe (Optional)

If you want to enable paid plans:

Create a Stripe account
Get your API keys from the dashboard
Add them to your .env file:

.env

STRIPE_SECRET_KEY="sk_test_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

Configure Redis (Optional)

For caching and improved performance, add Redis:

.env

REDIS_URL="your_upstash_redis_url"
REDIS_TOKEN="your_upstash_redis_token"

We recommend Upstash Redis for serverless Redis.

Database Setup

Set up your database schema using Prisma:

Run Migrations

npx prisma migrate dev

This will:

Create all necessary tables (User, Event, EventCategory, Quota)
Set up relationships and indexes
Generate the Prisma Client

Verify Database

Open Prisma Studio to view your database:

npx prisma studio

This opens a visual database browser at http://localhost:5555.

Run the Application

Development
Production

Start the development server with hot reload:

npm run dev

Your application will be available at http://localhost:3000.

The development server includes hot module replacement for faster development.

Build and start the production server:

npm run build
npm run start

The production build is optimized for performance and includes:

Minified JavaScript and CSS
Optimized images
Server-side rendering

Deployment Options

PingPilot can be deployed to various platforms:

Vercel (Recommended)
Cloudflare Pages
Docker
Railway

The easiest way to deploy PingPilot:

Push your code to GitHub
Import your repository on Vercel
Add all environment variables from your .env file
Deploy!

# Or use Vercel CLI
npm i -g vercel
vercel

Vercel automatically detects Next.js projects and configures optimal build settings.

Deploy to Cloudflare’s edge network:

Update wrangler.toml with your project name:

wrangler.toml

name = "pingpilot"
main = "src/server/index.ts"
compatibility_date = "2024-03-29"
compatibility_flags = ["nodejs_compat"]

Deploy using Wrangler:
```
npm run deploy
```
Set environment variables in the Cloudflare dashboard

Create a Dockerfile:

Dockerfile

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npx prisma generate
RUN npm run build

FROM node:18-alpine AS runner
WORKDIR /app
COPY --from=builder /app/next.config.js ./
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json

EXPOSE 3000
CMD ["npm", "start"]

Build and run:

docker build -t pingpilot .
docker run -p 3000:3000 --env-file .env pingpilot

Post-Deployment

Test Your Deployment

Visit your deployed URL
Create a test account
Set up a category and send a test event
Verify notifications are working

Set Up Monitoring

Monitor your application health:

Enable Vercel Analytics
Set up error tracking (e.g., Sentry)
Monitor database performance
Track API response times

Configure Domain (Optional)

Add a custom domain:

Purchase a domain from your preferred registrar
Add it in your hosting platform’s dashboard
Update DNS records as instructed
Enable SSL (usually automatic)

Environment Variables Reference

Here’s a complete list of all environment variables:

.env

# Database
DATABASE_URL="postgresql://user:password@host:5432/pingpilot"

# Authentication (Clerk)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
CLERK_SECRET_KEY="sk_test_..."

# Notifications
DISCORD_BOT_TOKEN="your_discord_bot_token"
TELEGRAM_BOT_TOKEN="your_telegram_bot_token"

# Email (Optional)
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="[email protected]"
SMTP_PASSWORD="your-app-password"
SMTP_FROM="[email protected]"

# Payments (Optional)
STRIPE_SECRET_KEY="sk_test_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

# Caching (Optional)
REDIS_URL="your_upstash_redis_url"
REDIS_TOKEN="your_upstash_redis_token"

Troubleshooting

Database connection errors

Verify your DATABASE_URL is correct
Check that your database server is running
Ensure your IP is whitelisted (for hosted databases)
Try connecting with npx prisma db pull to test the connection

Build failures

Clear .next folder: rm -rf .next
Delete node_modules and reinstall: rm -rf node_modules && npm install
Check that all environment variables are set
Run npx prisma generate manually

Discord notifications not working

Verify your bot token is correct
Ensure the bot has necessary permissions
Check that Privileged Gateway Intents are enabled
The bot must be able to send DMs to users

Port already in use

Change the port in package.json or use:

PORT=3001 npm run dev

Next Steps

API Reference

Learn how to integrate PingPilot into your applications

Architecture

Understand how PingPilot works under the hood

Contributing

Contribute to the PingPilot open-source project

Support

Get help from the community or report issues

Get Started

Core Features

Integrations

Guides

Pricing & Plans

Prerequisites

Clone the Repository

Install Dependencies

Environment Configuration

Database Setup

Run the Application

Deployment Options

Post-Deployment

Environment Variables Reference

Troubleshooting

Next Steps

API Reference

Architecture

Contributing

Support

Build docs developers (and LLMs) love

Get Started

Core Features

Integrations

Guides

Pricing & Plans

​Prerequisites

​Clone the Repository

​Install Dependencies

​Environment Configuration

​Database Setup

​Run the Application

​Deployment Options

​Post-Deployment

​Environment Variables Reference

​Troubleshooting

​Next Steps

API Reference

Architecture

Contributing

Support

Build docs developers (and LLMs) love

Prerequisites

Clone the Repository

Install Dependencies

Environment Configuration

Database Setup

Run the Application

Deployment Options

Post-Deployment

Environment Variables Reference

Troubleshooting

Next Steps