🚀 NitroPing

Self-hosted push notification service built with Nuxt 4 & 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

undefined🌍 Multi-Platformundefined iOS (APNs) Android (FCM) Web Push React Native (planned) Flutter (planned)	undefined🏗️ Modern Stackundefined Nuxt 4 & Nitro GraphQL API PostgreSQL TypeScript	undefined🔒 Self-Hostedundefined Full data control No vendor lock-in Custom deployment Privacy-focused
undefined📊 Analyticsundefined Delivery tracking Performance metrics Real-time updates Custom dashboards	undefined🛡️ Secureundefined JWT authentication API key management Rate limiting Encrypted credentials	undefined🐳 DevOps Readyundefined Docker support Easy deployment Environment configs Health monitoring

🎯 Why Choose NitroPing?

undefinedTake control of your push notifications with an open-source, developer-friendly platformundefined

• undefined🚀 Performance: Built on Nitro for maximum efficiency
• undefined🔧 Developer Experience: Clean APIs, extensive documentation, great DX
• undefined🌐 Flexibility: Support for multiple notification providers
• undefined🔐 Privacy: Self-hosted means your data stays yours
• undefined🆓 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

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

🚀 Quick Start

Environment Setup

1. undefinedCopy environment fileundefined

   cp .env.example .env
   

2. undefinedGenerate required secretsundefined

   undefinedJWT 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
   

   undefinedWebhook 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. undefinedSet up databaseundefined

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

4. undefinedStart development serverundefined

   bun run 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

undefinedUsing with docker-compose.yaml:undefined

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

Your First Notification

1. undefinedCreate an app via GraphQLundefined

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

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

3. undefinedRegister a deviceundefined

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

4. undefinedSend your first notificationundefined

   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

• undefinedFramework: Nuxt 4 with Nitro
• undefinedDatabase: PostgreSQL with Drizzle ORM
• undefinedAPI: GraphQL via Nitro GraphQL
• undefinedUI: shadcn-nuxt + Tailwind CSS v4
• undefinedTesting: Vitest
• undefinedLinting: @antfu/eslint-config

Commands

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

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

# Testing
bun run test          # Run tests
bun run test:ui       # Test with UI

🤝 Contributing

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

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

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

undefined🧑‍💻 Want to code?undefined 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
bun 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:18

bun run db:generate && bun run db:migrate

# Start development
bun run dev --host

🗺️ Roadmap

✅ Completed Features

• Core service architecture with Nuxt 4
• 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

undefinedSDKs & Integrationsundefined

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

undefinedPlatform Featuresundefined

• 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!