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

Click to expand full configuration options

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.

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/master/install.sh | bash

# Skip SSL verification (not recommended)
INSECURE=1 curl -fsSL https://raw.githubusercontent.com/appleboy/gorush/master/install.sh | bash

Manual Download

Download from releases page:

Package Managers

Homebrew (macOS/Linux)

brew tap appleboy/tap
brew install gorush

Go Install

# Latest stable version
go install github.com/appleboy/gorush@latest

# Development version
go install github.com/appleboy/gorush@master

Build from Source

Requirements: Go 1.25+, Git

git clone https://github.com/appleboy/gorush.git
cd gorush
make build
# Binary will be in the root directory

Docker

# Run directly
docker run --rm -p 8088:8088 appleboy/gorush

# With custom config
docker run --rm -p 8088:8088 -v $(pwd)/config.yml:/home/gorush/config.yml appleboy/gorush

Usage

Starting the Server

# Use default config (port 8088)
./gorush

# Use custom config file
./gorush -c config.yml

# Set specific options
./gorush -p 9000 -c config.yml

Command Line Notifications

Android (FCM) Command Line

Prerequisites: Generate FCM service account key from Firebase Console → Settings → Service Accounts → Generate New Private Key.

# Android: Single notification
gorush -android -m "Hello Android!" --fcm-key "path/to/fcm-key.json" -t "device_token"

# Android: Using environment variable (recommended)
export GOOGLE_APPLICATION_CREDENTIALS="path/to/fcm-key.json"
gorush -android -m "Hello Android!" -t "device_token"

# Android: Topic message
gorush --android --topic "news" -m "Breaking News!" --fcm-key "path/to/fcm-key.json"

iOS (APNS) Command Line

# iOS: Development environment
gorush -ios -m "Hello iOS!" -i "cert.pem" -t "device_token" --topic "com.example.app"

# iOS: Production environment
gorush -ios -m "Hello iOS!" -i "cert.pem" -t "device_token" --topic "com.example.app" -production

# iOS: With password-protected certificate
gorush -ios -m "Hello iOS!" -i "cert.p12" -P "cert_password" -t "device_token"

Huawei (HMS) Command Line

# Huawei: Single notification
gorush -huawei -title "Hello" -m "Hello Huawei!" -hk "APP_SECRET" -hid "APP_ID" -t "device_token"

# Huawei: Topic message
gorush --huawei --topic "updates" -title "Update" -m "New version available" -hk "APP_SECRET" -hid "APP_ID"

REST API Usage

Health Check

curl http://localhost:8088/healthz

Send Notifications

curl -X POST http://localhost:8088/api/push \
  -H "Content-Type: application/json" \
  -d '{
    "notifications": [{
      "tokens": ["device_token_1", "device_token_2"],
      "platform": 2,
      "title": "Hello World",
      "message": "This is a test notification"
    }]
  }'

Get Statistics

# Application stats
curl http://localhost:8088/api/stat/app

# Go runtime stats
curl http://localhost:8088/api/stat/go

# System stats
curl http://localhost:8088/sys/stats

# Prometheus metrics
curl http://localhost:8088/metrics

CLI Options Reference

Click to expand all CLI options

```bash Server Options: -A, --address

Address to bind (default: any) -p, --port Use port for clients (default: 8088) -c, --config Configuration file path -m, --message Notification message -t, --token Notification token -e, --engine Storage engine (memory, redis ...) --title Notification title --proxy <proxy> Proxy URL --pid <pid path> Process identifier path --redis-addr <redis addr> Redis addr (default: localhost:6379) --ping </p>