gorush

A push notification micro server using Gin framework written in Go (Golang) and see the demo app.

Quick Start

Get started with gorush in 3 simple steps:

# 1. Download the latest binary
wget https://github.com/appleboy/gorush/releases/download/v1.18.9/gorush-1.18.9-linux-amd64 -O gorush
chmod +x gorush

# 2. Start the server (default port 8088)
./gorush

# 3. Send your first notification
curl -X POST http://localhost:8088/api/push \
  -H "Content-Type: application/json" \
  -d '{
    "notifications": [{
      "tokens": ["your_device_token"],
      "platform": 2,
      "title": "Hello World",
      "message": "Your first notification!"
    }]
  }'

Contents

• Quick Start - Get up and running in 3 steps
• Support Platform - iOS, Android, Huawei
• Features - What gorush can do
• Configuration - YAML config and options
  • Basic Configuration
  • Advanced Configuration
• Installation - Binary, package managers, Docker, source
  • Recommended: Install Script
  • Manual Download
  • Package Managers
  • Build from Source
  • Docker
• Usage - CLI commands and REST API examples
  • Starting the Server
  • Command Line Notifications
  • REST API Usage
  • CLI Options Reference
• Web API - Complete API reference
  • Overview
  • Send Notifications
  • Statistics APIs
  • Request Parameters
• Deployment - Docker, Kubernetes, AWS Lambda, gRPC
  • Docker Deployment
  • Kubernetes
  • AWS Lambda
  • Netlify Functions
  • gRPC Service
• FAQ - Common issues and best practices
  • Common Issues
  • Performance Tips
  • Security Best Practices
• Stargazers over time
• License

Support Platform

📱 Platform codes: 1 = iOS (APNS), 2 = Android (FCM), 3 = Huawei (HMS)

• APNS
• FCM
• HMS

A live server on Netlify and get notification token on Firebase Cloud Messaging web. You can use the token to send a notification to the device.

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
  "notifications": [
    {
      "tokens": [
        "your_device_token"
      ],
      "platform": 2,
      "title": "Test Title",
      "message": "Test Message"
    }
  ]
}' \
  https://gorush.netlify.app/api/push

Features

• Support Firebase Cloud Messaging using go-fcm library for Android.
• Support HTTP/2 Apple Push Notification Service using apns2 library.
• Support HMS Push Service using go-hms-push library for Huawei Devices.
• Support YAML configuration.
• Support command line to send single Android or iOS notification.
• Support Web API to send push notification.
• Support HTTP/2 or HTTP/1.1 protocol.
• Support notification queue and multiple workers.
• Support /api/stat/app show notification success and failure counts.
• Support /api/config show your YAML config.
• Support store app stat to memory, Redis, BoltDB, BuntDB, LevelDB or BadgerDB.
• Support p8, p12 or pem format of iOS certificate file.
• Support /sys/stats show response time, status code count, etc.
• Support for HTTP, HTTPS or SOCKS5 proxy.
• Support retry send notification if server response is fail.
• Support expose prometheus metrics.
• Support install TLS certificates from Let's Encrypt automatically.
• Support send notification through RPC protocol, we use gRPC as default framework.
• Support running in Docker, Kubernetes or AWS Lambda (Native Support in Golang)
• Support graceful shutdown that workers and queue have been sent to APNs/FCM before shutdown service.
• Support different Queue as backend like NSQ, NATS or Redis streams, default engine is local Channel.

Performance: Average memory usage ~28MB. Supports high-throughput notification delivery with configurable workers and queue systems.

Configuration

Gorush uses YAML configuration. Create a config.yml file with your settings:

Basic Configuration

core:
  port: "8088" # HTTP server port
  worker_num: 0 # Workers (0 = CPU cores)
  queue_num: 8192 # Queue size
  mode: "release" # or "debug"

# Enable platforms you need
android:
  enabled: true
  key_path: "fcm-key.json" # FCM service account key

ios:
  enabled: true
  key_path: "apns-key.pem" # APNS certificate
  production: true # Use production APNS

huawei:
  enabled: false
  appid: "YOUR_APP_ID"
  appsecret: "YOUR_APP_SECRET"

Advanced Configuration

<details> <summary>Click to expand full configuration options</summary>

core:
  enabled: true
  address: ""
  shutdown_timeout: 30
  port: "8088"
  worker_num: 0
  queue_num: 0
  max_notification: 100
  sync: false
  feedback_hook_url: ""
  feedback_timeout: 10
  feedback_header:
  mode: "release"
  ssl: false
  cert_path: "cert.pem"
  key_path: "key.pem"
  cert_base64: ""
  key_base64: ""
  http_proxy: ""
  pid:
    enabled: false
    path: "gorush.pid"
    override: true
  auto_tls:
    enabled: false
    folder: ".cache"
    host: ""

grpc:
  enabled: false
  port: 9000

api:
  push_uri: "/api/push"
  stat_go_uri: "/api/stat/go"
  stat_app_uri: "/api/stat/app"
  config_uri: "/api/config"
  sys_stat_uri: "/sys/stats"
  metric_uri: "/metrics"
  health_uri: "/healthz"

android:
  enabled: true
  key_path: ""
  credential: ""
  max_retry: 0

huawei:
  enabled: false
  appsecret: "YOUR_APP_SECRET"
  appid: "YOUR_APP_ID"
  max_retry: 0

queue:
  engine: "local"
  nsq:
    addr: 127.0.0.1:4150
    topic: gorush
    channel: gorush
  nats:
    addr: 127.0.0.1:4222
    subj: gorush
    queue: gorush
  redis:
    addr: 127.0.0.1:6379
    group: gorush
    consumer: gorush
    stream_name: gorush
    with_tls: false
    username: ""
    password: ""
    db: 0

ios:
  enabled: false
  key_path: ""
  key_base64: ""
  key_type: "pem"
  password: ""
  production: false
  max_concurrent_pushes: 100
  max_retry: 0
  key_id: ""
  team_id: ""

log:
  format: "string"
  access_log: "stdout"
  access_level: "debug"
  error_log: "stderr"
  error_level: "error"
  hide_token: true
  hide_messages: false

stat:
  engine: "memory"
  redis:
    cluster: false
    addr: "localhost:6379"
    username: ""
    password: ""
    db: 0
  boltdb:
    path: "bolt.db"
    bucket: "gorush"
  buntdb:
    path: "bunt.db"
  leveldb:
    path: "level.db"
  badgerdb:
    path: "badger.db"

See the complete example config file.

</details>

Installation

Recommended: Install Script

The easiest way to install gorush is using the install script:

curl -fsSL https://raw.githubusercontent.com/appleboy/gorush/master/install.sh | bash

This will automatically:

• Detect your OS and architecture
• Download the latest version
• Install to ~/.gorush/bin
• Add to your PATH

Options

# Install specific version (replace X.Y.Z with the desired version, e.g., 1.19.2)
VERSION=X.Y.Z curl -fsSL https://raw.githubusercontent.com/appleboy/gorush/master/install.sh | bash

# Custom install directory
INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/appleboy/gorush