🚀 NitroPing

Self-hosted push notification service built with Vite, Vue 3 & Nitro

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

📋 Table of Contents

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

✨ Features

🌍 Multi-Platform iOS (APNs) Android (FCM) Web Push React Native (planned) Flutter (planned)	🏗️ Modern Stack Vite + Vue 3 & Nitro GraphQL API PostgreSQL TypeScript	🔒 Self-Hosted Full data control No vendor lock-in Custom deployment Privacy-focused
📊 Analytics Delivery tracking Performance metrics Real-time updates Custom dashboards	🛡️ Secure JWT authentication API key management Rate limiting Encrypted credentials	🐳 DevOps Ready Docker support Easy deployment Environment configs Health monitoring

🎯 Why Choose NitroPing?

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

🏗️ Architecture

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]

Core Components

• 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

🚀 Quick Start

Environment Setup

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 5433:5432 -d postgres:18
   
   # 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
   

Docker

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

🐳 Docker Hub Image

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"

Your First Notification

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
     }
   }
   

📱 SDKs

🍎 iOS Swift Package Native iOS integration

🤖 Android Kotlin SDK Native Android support

⚛️ React Native Coming Soon Cross-platform mobile

🎯 Flutter Coming Soon Google's framework

iOS Quick Setup

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()

🧪 Development

Tech Stack

• Frontend: Vite + Vue 3
• Backend: Nitro
• Database: PostgreSQL with Drizzle ORM
• API: GraphQL via Nitro GraphQL
• UI: shadcn/vue + Tailwind CSS v4
• Testing: Vitest
• Linting: @antfu/eslint-config

Commands

# 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

# Build
pnpm build         # Build for production

🤝 Contributing

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

🐛 Found a Bug? Open an issue Provide reproduction steps Include system information

💡 Have an idea? Start a discussion Propose new features Share architectural thoughts

🧑‍💻 Want to code? Fork the repository Create a feature branch Submit a pull request

Development Setup

# Clone and setup
git clone https://github.com/productdevbook/nitroping.git
cd nitroping/app
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 5433:5432 postgres:18

pnpm db:generate && pnpm db:migrate

# Start development
pnpm dev --host

🗺️ Roadmap

✅ Completed Features

• Core service architecture with Vite + Vue 3 & Nitro
• Multi-platform push providers (APNs, FCM, Web Push)
• GraphQL API with type safety
• Dashboard UI with analytics
• Device management and targeting
• Delivery tracking and metrics
• Encrypted credential storage
• JWT-based authentication
• Docker deployment & Docker Hub publishing

🚧 In Progress

• Swift iOS SDK - Native iOS integration
• Queue System - Background job processing
• Advanced scheduling features

📋 Planned

SDKs & Integrations

• Android SDK - Kotlin/Java support
• React Native SDK - Cross-platform mobile
• Flutter SDK - Google’s framework
• Unity SDK - Game development

Platform Features

• Authentication System - User management
• Advanced analytics and reporting
• Template system for notifications
• A/B testing capabilities
• Webhook integrations

📄 License

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!