notepush-ios-main

NotePush Documentation

Your.Server.Connect

NotePush is an enhanced iOS client for the ntfy notification service. Building on the solid foundation of the open-source ntfy project, NotePush adds powerful new features while maintaining the same privacy-first, server-agnostic approach you love.

Key Features

Enhanced over the Original ntfy iOS App

🆕 QR Code Server Configuration

🆕 Multi-Topic Subscriptions

🆕 Display Name Support

🆕 Improved Attachment Support

🆕 Enhanced User Experience

Core ntfy Features (Maintained)

📡 Server-Agnostic Design

🔒 Privacy-First Architecture

⚡ Real-Time Notifications

Quick Start

  1. Get a QR Code
    • Ask your server administrator for a setup QR code
    • Or generate one yourself using our configuration format
  2. Scan and Subscribe
    • Open NotePush → Tap “+” → “Scan QR Code”
    • Point camera at the QR code
    • Review and confirm the configuration
    • Done! All topics configured automatically

Option 2: Manual Setup

  1. Add Your Server
    • Open NotePush → Tap “+”
    • Enter your server URL (e.g., https://ntfy.sh or your own server)
    • Add authentication if required
  2. Subscribe to Topics
    • Create topic names (e.g., “alerts”, “updates”, “monitoring”)
    • Keep topics private and hard to guess
    • Subscribe to multiple topics as needed
  3. Start Receiving Notifications
    • Send HTTP requests to your topics
    • Notifications appear instantly on your device

Test QR Code for Reviewers

For App Store reviewers and testers: Use this QR code to quickly test the enhanced QR code functionality:

Test QR Code

This QR code will automatically configure NotePush to connect to the public ntfy.sh server and subscribe to two test topics. After scanning:

  1. Open NotePush
  2. Tap “+” → “Scan QR Code”
  3. Point camera at the QR code above
  4. Confirm the configuration (shows ntfy.sh server with two test topics)
  5. Test notifications by visiting: https://ntfy.sh/[topic-name] and sending a test message

What this demonstrates:

Server Options

🏠 Self-Hosted (Most Private)

Run your own server for maximum privacy:

# Quick Docker setup
docker run -p 80:80 -v /var/cache/ntfy:/var/cache/ntfy binwiederhier/ntfy

# Production with HTTPS
docker run -p 443:80 -v /var/cache/ntfy:/var/cache/ntfy \
  -v /etc/letsencrypt:/etc/letsencrypt \
  binwiederhier/ntfy serve --listen-https :443

Benefits:

🌐 Public Servers (Easy Setup)

Use existing public servers:

Benefits:

🏢 Enterprise Deployment

For organizations:

Enhanced Features Guide

QR Code Configuration

NotePush supports advanced QR code configurations for easy setup:

Basic Configuration:

{
  "version": 2,
  "defaultServer": {
    "server": "https://ntfy.example.com",
    "setAsDefault": true,
    "auth": {
      "type": "basic",
      "username": "user",
      "password": "pass"
    }
  },
  "topics": [
    {
      "topic": "alerts",
      "display_name": "System Alerts"
    },
    {
      "topic": "monitoring", 
      "display_name": "Server Monitoring"
    }
  ]
}

Multi-Server Configuration with Custom Display Names:

{
  "version": 2,
  "defaultServer": {
    "server": "https://primary-server.com",
    "setAsDefault": true
  },
  "topics": [
    {
      "topic": "a7b2c3d4-e5f6-7890-abcd-ef1234567890",
      "server": "https://ntfy.sh",
      "display_name": "🚨 Critical Alerts"
    },
    {
      "topic": "x9k3m7q2-p8n5-4567-bcde-f12345678901",
      "server": "https://ntfy.sh", 
      "display_name": "📦 System Updates"
    },
    {
      "topic": "b3f7k9m2-q5n8-3456-cdef-012345678abc",
      "display_name": "💾 Daily Backups"
    }
  ]
}

Security Benefits:

Multi-Topic Subscriptions

Simultaneous Setup:

Organization Benefits:

Enhanced Attachments

Improved Preview Support:

Images:

Files:

Sending Notifications

Basic Examples

Simple notification:

curl -d "Hello World!" https://your-server.com/your-topic

With title and priority:

curl -H "Title: System Alert" \
     -H "Priority: urgent" \
     -d "Server maintenance required" \
     https://your-server.com/alerts

With enhanced attachment preview:

# Image attachment (enhanced preview)
curl -H "Title: Server Status" \
     -H "Attach: https://status.example.com/chart.png" \
     -d "Current system metrics" \
     https://your-server.com/monitoring

# GIF attachment (animated preview)
curl -H "Title: Process Complete" \
     -H "Attach: https://example.com/celebration.gif" \
     -d "Deployment successful!" \
     https://your-server.com/deployments

Programming Examples

JavaScript/Node.js:

// Simple notification
fetch('https://your-server.com/alerts', {
  method: 'POST',
  body: 'Backup completed successfully'
});

// With attachment
fetch('https://your-server.com/reports', {
  method: 'POST',
  headers: {
    'Title': 'Daily Report',
    'Attach': 'https://reports.example.com/daily.pdf'
  },
  body: 'Daily metrics report is ready'
});

Python:

import requests

# Simple notification
requests.post('https://your-server.com/alerts', 
              data='System backup completed')

# With enhanced attachment
requests.post('https://your-server.com/monitoring',
              headers={
                  'Title': 'Performance Chart',
                  'Attach': 'https://monitoring.example.com/chart.png'
              },
              data='Weekly performance summary')

Server Configuration

Authentication Setup

Basic Authentication:

# server.yml
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"

User Management:

# Add users
ntfy user add --role=admin alice
ntfy user add bob

# Set topic permissions
ntfy access alice "alerts" write
ntfy access bob "updates" read

QR Code Generation for Admins

Generate setup QR codes for your users:

  1. Create configuration JSON (examples above)
  2. Host the JSON file on your server
  3. Generate QR code pointing to the JSON URL
  4. Share QR code with users for instant setup

Example QR code content:

https://your-server.com/config/user-setup.json

Privacy & Security

Privacy Protection

What NotePush Does NOT Collect:

What is Stored Locally:

Security Best Practices

App Security:

Server Security:

Troubleshooting

Common Issues

Notifications not appearing:

  1. Check iOS notification permissions
  2. Verify background app refresh is enabled
  3. Test with ntfy.sh to isolate server issues
  4. Run diagnostics in app settings

QR code scanning issues:

  1. Ensure camera permission is granted
  2. Verify good lighting and clear QR code
  3. Check QR code format with administrator
  4. Fall back to manual entry if needed

Server connection problems:

  1. Verify HTTPS is used for external servers
  2. Check server URL format
  3. Validate authentication credentials
  4. Test server accessibility in web browser

Diagnostic Tools

Built-in Diagnostics:

Manual Testing:

  1. Try connecting to ntfy.sh first
  2. Test with simple curl commands
  3. Verify server logs for connection attempts
  4. Check iOS Console for app logs

Comparison with Original ntfy iOS App

What’s New in NotePush

Feature Original ntfy iOS NotePush
Server Configuration Manual URL entry only ✅ QR code scanning + manual
Topic Subscription One at a time ✅ Multi-topic subscriptions
Display Names Raw topic names only ✅ Custom display names
Attachment Preview Basic support ✅ Enhanced with GIF support
Setup Experience Manual configuration ✅ Streamlined with QR codes
Credential Management Basic storage ✅ Enhanced security
Multi-Server Support Manual per topic ✅ Organized management

Maintained Features

Core functionality remains the same:

Migration from Original App

Easy Transition:

  1. Export/note your current server configurations
  2. Install NotePush
  3. Option A: Manually re-add servers (familiar process)
  4. Option B: Use QR codes for bulk setup (if available)
  5. Notifications continue working immediately

No Lock-in:

Support

Getting Help

📧 Email Support:

📖 Resources:

Community

Open Source Foundation:

About NotePush

NotePush enhances the excellent ntfy project with improved user experience and additional features while maintaining its core values: privacy, user control, and server independence.

Our Enhancements:

Built by notification enthusiasts, for notification enthusiasts.

*Documentation version 0.9.1 Last updated: [Date]*

Ready to get started? → Download NotePush