Self-hosted push notification service built with Nuxt 4 & Nitro

Take control of your push notifications with an open-source, developer-friendly platform

• ✨ Features
• 🚀 Quick Start
• 🏗️ Architecture
• 📱 SDKs
• 🧪 Development
• 🤝 Contributing
• 🗺️ Roadmap
• 📄 License

Take control of your push notifications with an open-source, developer-friendly platform

• 🚀 Performance: Built on Nitro for maximum efficiency
• 🔧 Developer Experience: Clean APIs, extensive documentation, great DX
• 🌐 Flexibility: Support for multiple notification providers
• 🔐 Privacy: Self-hosted means your data stays yours
• 🆓 Open Source: MIT licensed, community-driven development

NitroPing is built with a modern, scalable architecture:

graph TB
    Client[Client Apps] --> API[GraphQL API]
    API --> Auth[JWT Auth]
    API --> DB[(PostgreSQL)]
    API --> Providers[Push Providers]
    
    Providers --> APNs[Apple APNs]
    Providers --> FCM[Firebase FCM]
    Providers --> WebPush[Web Push]
    
    DB --> Apps[Apps]
    DB --> Devices[Devices] 
    DB --> Notifications[Notifications]
    DB --> Logs[Delivery Logs]

• GraphQL API: Type-safe API built with Nitro GraphQL
• Multi-tenant: App-based isolation with encrypted credentials
• Push Providers: Native APNs, FCM, and Web Push support
• Analytics: Comprehensive delivery tracking and metrics
• Security: JWT authentication with per-app API keys

1. Copy environment file

   cp .env.example .env

2. Generate required secrets

   JWT Secret (for API authentication):

   # Option 1: Using Node.js
   node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
   
   # Option 2: Using OpenSSL
   openssl rand -hex 64
   
   # Option 3: Using online generator
   # Visit: https://generate-secret.vercel.app/64

   Webhook Secret (for delivery callbacks):

   # Option 1: Using Node.js
   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
   
   # Option 2: Using OpenSSL
   openssl rand -hex 32

3. Set up database

   # Start PostgreSQL (using Docker)
   docker run --name nitroping-db -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=nitroping -p 5432:5432 -d postgres:15
   
   # Generate and run migrations
   pnpm db:generate
   pnpm db:migrate

4. Start development server

   pnpm dev --host  # Allows access from mobile devices on same network

If you prefer Docker, you can run NitroPing in a containerized environment. Make sure to set up the .env file with the necessary secrets and database connection details.

If running Docker compose for the first time, migration is needed. Run the docker compose with migrate profile to set up the database schema.

docker compose up --profile migrate --profile dev -d 

For subsequent runs, you can use the dev profile to start the application without migrating again.

docker compose up --profile dev -d

For production deployments, you can use the prod profile to run the application in production mode.

docker compose up --profile prod -d

Pull the latest image from Docker Hub:

# Pull latest version
docker pull productdevbook/nitroping:latest

# Or specific version
docker pull productdevbook/nitroping:v0.0.1

Using with docker-compose.yaml:

services:
  server:
    image: productdevbook/nitroping:latest
    environment:
      DATABASE_URL: postgres://user:password@db:5432/nitroping
    ports:
      - "3000:3000"

1. Create an app via GraphQL

   mutation CreateApp {
     createApp(input: {
       name: "My App"
       slug: "my-app"
       description: "My awesome app"
     }) {
       id
       apiKey
     }
   }

2. Configure push providers through the dashboard at http://localhost:3000

3. Register a device

   mutation RegisterDevice {
     registerDevice(input: {
       appId: "your-app-id"
       token: "device-token"
       platform: IOS
     }) {
       id
     }
   }

4. Send your first notification

   mutation SendNotification {
     sendNotification(input: {
       appId: "your-app-id"
       title: "Hello World!"
       body: "Your first push notification"
       targetDevices: ["device-id"]
     }) {
       id
       status
     }
   }

import NitroPingClient

// Configure in AppDelegate
NitroPingClient.configure(
    appId: "your-app-id",
    apiKey: "your-api-key",
    baseURL: "https://your-nitroping-instance.com"
)

// Register for push notifications
NitroPingClient.shared.registerForPushNotifications()

• Framework: Nuxt 4 with Nitro
• Database: PostgreSQL with Drizzle ORM
• API: GraphQL via Nitro GraphQL
• UI: shadcn-nuxt + Tailwind CSS v4
• Testing: Vitest
• Linting: @antfu/eslint-config

# Development
pnpm dev --host       # Start dev server (accessible from mobile devices)
pnpm typecheck        # Type checking
pnpm lint             # Run linter

# Database
pnpm db:generate      # Generate migrations
pnpm db:migrate       # Run migrations
pnpm db:studio        # Open Drizzle Studio

# Testing
pnpm test             # Run tests
pnpm test:ui          # Test with UI

We welcome all contributions! Whether you're fixing bugs, adding features, or improving documentation.

# Clone and setup
git clone https://github.com/productdevbook/nitroping.git
cd nitroping
pnpm install

# Setup environment
cp .env.example .env
# Edit .env with your configuration

# Setup database
docker run -d --name nitroping-db \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=nitroping \
  -p 5432:5432 postgres:15

pnpm db:generate && pnpm db:migrate

# Start development
pnpm dev --host

MIT Licensed - see the LICENSE file for details.

Built with ❤️ by the open source community

🌐 Visit Website • ⭐ Star us on GitHub • 💬 Join the discussion

Take control of your push notifications today!