GitHub - appleboy/gorush: A push notification server written in Go (Golang). (original) (raw)

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!" }] }'

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

Contents

• Quick Start - Get up and running in 3 steps
• Support Platform - iOS, Android, Huawei
• Features - What gorush can do
• Installation - Binary, package managers, Docker, source
• Configuration - YAML config and options
• Usage - CLI commands and REST API examples
• Web API - Complete API reference
• Deployment - Docker, Kubernetes, AWS Lambda, gRPC
• FAQ - Common issues and best practices
• License

Support Platform

• 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, defaut 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.24+, 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)

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

Single notification

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

Using environment variable (recommended)

export GOOGLE_APPLICATION_CREDENTIALS="path/to/fcm-key.json" gorush -android -m "Hello Android!" -t "device_token"

Topic message

gorush --android --topic "news" -m "Breaking News!" --fcm-key "path/to/fcm-key.json"

iOS (APNS)

Development environment

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

Production environment

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

With password-protected certificate

gorush -ios -m "Hello iOS!" -i "cert.p12" -P "cert_password" -t "device_token"

Huawei (HMS)

Single notification

gorush -huawei -title "Hello" -m "Hello Huawei!" -hk "APP_SECRET" -hid "APP_ID" -t "device_token"

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

Server Options: -A, --address