Queue Notify Server

A Flask-based notification service that sends notifications via ntfy and optionally Telegram.

Features

• Always notifies via ntfy using UUID as topic
• Optionally notifies via Telegram if user has registered
• Self-hosted ntfy server (not public ntfy.sh)
• UUID-based topics for security and privacy

---

Table of Contents

• Docker Compose (Recommended)
• Quick Start (Local Development)
• VPS Production Deployment
• Configuration
• API Endpoints
• User Flow

---

Docker Compose (Recommended)

The easiest way to run everything - just one command!

Prerequisites

• Docker and Docker Compose installed

Setup

# 1. Clone the repository
git clone https://github.com/your-repo/queue-notify-server.git
cd queue-notify-server

# 2. Create config files from examples
cp config.docker.json config.json

# 3. (Optional) For Telegram support:
cp bot.token.example bot.token
# Edit bot.token with your actual Telegram bot token
head -c 32 /dev/urandom > encryption.key

# 4. Start everything!
docker compose up -d

# 5. Test it works
curl -X POST http://localhost:5000/notify \
  -H "Content-Type: application/json" \
  -d '{"uuid": "test-123", "message": "Hello!"}'

That's it! 🎉

• Queue Notify API: http://localhost:5000
• ntfy Web UI: http://localhost:8090

Management Commands

# View logs
docker compose logs -f

# Stop services
docker compose down

# Restart after config changes
docker compose restart

# Rebuild after code changes
docker compose up -d --build

---

Quick Start (Local Development)

Windows (with WSL2)

# 1. Start ntfy server (in WSL)
wsl -d Ubuntu-24.04 -- ntfy serve --listen-http :8090

# 2. Install dependencies
pip install -r requirements.txt

# 3. Run Flask app
python app.py

# 4. Test notification
curl -X POST http://localhost:5000/notify -H "Content-Type: application/json" -d "{\"uuid\": \"test-123\", \"message\": \"Hello!\"}"

---

VPS Production Deployment

Prerequisites

• Ubuntu 20.04+ or Debian 11+ VPS
• Root/sudo access
• Domain name (optional, for HTTPS)

Step 1: Connect to Your VPS

ssh root@your-vps-ip

Step 2: Install System Dependencies

apt update && apt upgrade -y
apt install -y python3 python3-pip python3-venv curl wget git nginx

Step 3: Install ntfy Server

# Download ntfy binary
curl -sSL https://github.com/binwiederhier/ntfy/releases/download/v2.15.0/ntfy_2.15.0_linux_amd64.tar.gz -o /tmp/ntfy.tar.gz
tar -xzf /tmp/ntfy.tar.gz -C /tmp
mv /tmp/ntfy_2.15.0_linux_amd64/ntfy /usr/bin/ntfy
chmod +x /usr/bin/ntfy

# Verify installation
ntfy --help

Step 4: Configure ntfy Server

# Create ntfy user and directories
useradd -r -s /bin/false ntfy
mkdir -p /etc/ntfy /var/cache/ntfy /var/log/ntfy

# Create config file
cat > /etc/ntfy/server.yml << 'EOF'
listen-http: "127.0.0.1:8090"
cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "12h"
log-level: "info"
web-root: "app"
EOF

# Set permissions
chown -R ntfy:ntfy /var/cache/ntfy /var/log/ntfy

Step 5: Create ntfy Systemd Service

cat > /etc/systemd/system/ntfy.service << 'EOF'
[Unit]
Description=ntfy Notification Server
After=network.target

[Service]
Type=simple
User=ntfy
Group=ntfy
ExecStart=/usr/bin/ntfy serve --config /etc/ntfy/server.yml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable ntfy
systemctl start ntfy

# Verify
systemctl status ntfy

Step 6: Deploy Queue Notify Application

# Create app directory
mkdir -p /opt/queue-notify
cd /opt/queue-notify

# Clone or copy your code
git clone https://github.com/your-repo/queue-notify-server.git .
# Or: scp -r your-local-path/* root@your-vps:/opt/queue-notify/

# Create virtual environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install gunicorn
deactivate

# Create config file
cp config.production.json config.json

# Create encryption key (for Telegram chat IDs)
head -c 32 /dev/urandom > encryption.key

# Set permissions
chown -R www-data:www-data /opt/queue-notify
mkdir -p /var/log/queue-notify
chown www-data:www-data /var/log/queue-notify

Step 7: Create Queue Notify Systemd Service

cat > /etc/systemd/system/queue-notify.service << 'EOF'
[Unit]
Description=Queue Notify Server
After=network.target ntfy.service
Wants=ntfy.service

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/opt/queue-notify
Environment="PATH=/opt/queue-notify/venv/bin"
ExecStart=/opt/queue-notify/venv/bin/gunicorn --workers 4 --bind 127.0.0.1:5000 app:app
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable queue-notify
systemctl start queue-notify

# Verify
systemctl status queue-notify

Step 8: Configure Nginx Reverse Proxy

cat > /etc/nginx/sites-available/queue-notify << 'EOF'
server {
    listen 80;
    server_name your-domain.com;  # Or use IP

    # Queue Notify API
    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # ntfy Server (optional - expose if users need web UI)
    location /ntfy/ {
        proxy_pass http://127.0.0.1:8090/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
EOF

ln -sf /etc/nginx/sites-available/queue-notify /etc/nginx/sites-enabled/
rm -f /etc/nginx/sites-enabled/default
nginx -t && systemctl reload nginx

Step 9: (Optional) Enable HTTPS with Let's Encrypt

apt install -y certbot python3-certbot-nginx
certbot --nginx -d your-domain.com

Step 10: Configure Telegram (Optional)

If you want Telegram notifications:

# Save your Telegram bot token
echo "YOUR_BOT_TOKEN_HERE" > /opt/queue-notify/bot.token
chown www-data:www-data /opt/queue-notify/bot.token
chmod 600 /opt/queue-notify/bot.token

# Restart service
systemctl restart queue-notify

Step 11: Test the Deployment

# Test ntfy directly
curl -X POST http://localhost:8090/test-topic -d "Test notification"

# Test queue-notify API
curl -X POST http://localhost:5000/notify \
  -H "Content-Type: application/json" \
  -d '{"uuid": "test-uuid-123", "message": "Hello from production!"}'

# Expected response:
# {"backends": ["ntfy"], "status": "notifications sent"}

Step 12: Configure Firewall (Optional)

ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

---

Configuration

Edit /opt/queue-notify/config.json:

{
  "ntfy": {
    "server": "http://localhost:8090",
    "token": ""
  },
  "telegram": {
    "enabled": true,
    "bot_token_file": "/opt/queue-notify/bot.token"
  }
}

---

API Endpoints

POST /notify

Send a notification.

{
  "uuid": "user-unique-id",
  "message": "Your notification",
  "notifyRetries": 1
}

Response:

{
  "status": "notifications sent",
  "backends": ["ntfy", "telegram"]
}

POST /register

Register Telegram mapping (user must first send UUID to bot).

{
  "uuid": "user-unique-id"
}

GET /config

Returns safe configuration (no secrets).

GET /counter

Returns notification statistics.

---

User Flow

For ntfy (All Users)

1. Install ntfy app on phone
2. Add server: http://your-domain.com/ntfy/ or http://your-vps-ip:8090
3. Subscribe to your UUID topic
4. Done!

For Telegram (Optional)

1. Find the bot and send your UUID
2. Your app calls /register with same UUID
3. Now notifications go to both ntfy AND Telegram

---

Logs and Troubleshooting

# View ntfy logs
journalctl -u ntfy -f

# View queue-notify logs
journalctl -u queue-notify -f

# Check service status
systemctl status ntfy queue-notify

# Restart services
systemctl restart ntfy queue-notify

---

Quick Commands Reference

# Start services
systemctl start ntfy queue-notify

# Stop services
systemctl stop ntfy queue-notify

# Restart after config changes
systemctl restart ntfy queue-notify

# View logs
journalctl -u queue-notify -f

---

License

This project is provided "as is" with no warranties.