gorush

About gorush

This large README is shown as a plain-text preview. Read the full README at the source

# gorush

A push notification micro server using [Gin](https://github.com/gin-gonic/gin) framework written in Go (Golang) and see the [demo app](https://github.com/appleboy/flutter-gorush).

[![Run Lint and Testing](https://github.com/appleboy/gorush/actions/workflows/testing.yml/badge.svg)](https://github.com/appleboy/gorush/actions/workflows/testing.yml)
[![Trivy Security Scan](https://github.com/appleboy/gorush/actions/workflows/trivy-scan.yml/badge.svg)](https://github.com/appleboy/gorush/actions/workflows/trivy-daily-scan.yml)
[![GoDoc](https://godoc.org/github.com/appleboy/gorush?status.svg)](https://pkg.go.dev/github.com/appleboy/gorush)
[![codecov](https://codecov.io/gh/appleboy/gorush/branch/master/graph/badge.svg)](https://codecov.io/gh/appleboy/gorush)
[![Go Report Card](https://goreportcard.com/badge/github.com/appleboy/gorush)](https://goreportcard.com/report/github.com/appleboy/gorush)
[![Docker Pulls](https://img.shields.io/docker/pulls/appleboy/gorush.svg)](https://hub.docker.com/r/appleboy/gorush/)
[![Netlify Status](https://api.netlify.com/api/v1/badges/8ab14c9f-44fd-4d9a-8bba-f73f76d253b1/deploy-status)](https://app.netlify.com/sites/gorush/deploys)
[![Financial Contributors on Open Collective](https://opencollective.com/gorush/all/badge.svg?label=financial+contributors)](https://opencollective.com/gorush)

## Quick Start

Get started with gorush in 3 simple steps:

```bash
# 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](#quick-start) - Get up and running in 3 steps
- [Support Platform](#support-platform) - iOS, Android, Huawei
- [Features](#features) - What gorush can do
- [Configuration](#configuration) - YAML config and options
  - [Basic Configuration](#basic-configuration)
  - [Advanced Configuration](#advanced-configuration)
- [Installation](#installation) - Binary, package managers, Docker, source
  - [Recommended: Install Script](#recommended-install-script)
  - [Manual Download](#manual-download)
  - [Package Managers](#package-managers)
  - [Build from Source](#build-from-source)
  - [Docker](#docker)
- [Usage](#usage) - CLI commands and REST API examples
  - [Starting the Server](#starting-the-server)
  - [Command Line Notifications](#command-line-notifications)
  - [REST API Usage](#rest-api-usage)
  - [CLI Options Reference](#cli-options-reference)
- [Web API](#web-api) - Complete API reference
  - [Overview](#overview)
  - [Send Notifications](#send-notifications---post-apipush)
  - [Statistics APIs](#statistics-apis)
  - [Request Parameters](#request-parameters)
- [Deployment](#deployment) - Docker, Kubernetes, AWS Lambda, gRPC
  - [Docker Deployment](#docker-deployment)
  - [Kubernetes](#kubernetes)
  - [AWS Lambda](#aws-lambda)
  - [Netlify Functions](#netlify-functions)
  - [gRPC Service](#grpc-service)
- [FAQ](#faq) - Common issues and best practices
  - [Common Issues](#common-issues)
  - [Performance Tips](#performance-tips)
  - [Security Best Practices](#security-best-practices)
- [Stargazers over time](#stargazers-over-time)
- [License](#license)

## Support Platform

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

- [APNS](https://developer.apple.com/documentation/usernotifications)
- [FCM](https://firebase.google.com/)
- [HMS](https://developer.huawei.com/consumer/en/hms/)

[A live server on Netlify](https://gorush.netlify.app/) and get notification token on [Firebase Cloud Messaging web](https://fcm-demo-88b40.web.app/). You can use the token to send a notification to the device.

```bash
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](https://firebase.google.com/docs/cloud-messaging) using [go-fcm](https://github.com/appleboy/go-fcm) library for Android.
- Support [HTTP/2](https://http2.github.io/) Apple Push Notification Service using [apns2](https://github.com/sideshow/apns2) library.
- Support [HMS Push Service](https://developer.huawei.com/consumer/en/hms/huawei-pushkit) using [go-hms-push](https://github.com/msalihkarakasli/go-hms-push) library for Huawei Devices.
- Support [YAML](https://github.com/go-yaml/yaml) configuration.
- Support command line to send single Android or iOS notification.
- Support Web API to send push notification.
- Support [HTTP/2](https://http2.github.io/) 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](https://en.wikipedia.org/wiki/YAML) config.
- Support store app stat to memory, [Redis](http://redis.io/), [BoltDB](https://github.com/boltdb/bolt), [BuntDB](https://github.com/tidwall/buntdb), [LevelDB](https://github.com/syndtr/goleveldb) or [BadgerDB](https://github.com/dgraph-io/badger).
- 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](https://prometheus.io/) metrics.
- Support install TLS certificates from [Let's Encrypt](https://letsencrypt.org/) automatically.
- Support send notification through [RPC](https://en.wikipedia.org/wiki/Remote_procedure_call) protocol, we use [gRPC](https://grpc.io/) as default framework.
- Support running in Docker, [Kubernetes](https://kubernetes.io/) or [AWS Lambda](https://aws.amazon.com/lambda) ([Native Support in Golang](https://aws.amazon.com/blogs/compute/announcing-go-support-for-aws-lambda/))
- Support graceful shutdown that workers and queue have been sent to APNs/FCM before shutdown service.
- Support different Queue as backend like [NSQ](https://nsq.io/), [NATS](https://nats.io/) or [Redis streams](https://redis.io/docs/manual/data-types/streams/), default engine is local [Channel](https://tour.golang.org/concurrency/2).

**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

```yaml
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>

```yaml
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](config/testdata/config.yml).

</details>

## Installation

### Recommended: Install Script

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

```bash
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

```bash
# 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](https://github.com/appleboy/gorush/releases):

### Package Managers

#### Homebrew (macOS/Linux)

```bash
brew tap appleboy/tap
brew install gorush
```

#### Go Install

```bash
# 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+](https://go.dev/dl/), [Git](http://git-scm.com/)

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

### Docker

```bash
# 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

```bash
# 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](https://console.firebase.google.com/project/_/settings/serviceaccounts/adminsdk) → Settings → Service Accounts → Generate New Private Key.

```bash
# 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

```bash
# 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

```bash
# 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

```bash
curl http://localhost:8088/healthz
```

#### Send Notifications

```bash
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

```bash
# 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

<details>
<summary>Click to expand all CLI options</summary>

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

iOS Options:
    -i, --key <file>                 certificate key file path
    -P, --password <password>        certificate key password
    --ios                            enabled iOS (default: false)
    --production                     iOS production mode (default: false)

Android Options:
    --fcm-key <fcm_key_path>         FCM Key Path
    --android                        enabled android (default: false)

Huawei Options:
    -hk, --hmskey <hms_key>          HMS App Secret
    -hid, --hmsid <hms_id>           HMS App ID
    --huawei                         enabled huawei (default: false)

Common Options:
    --topic <topic>                  iOS, Android or Huawei topic message
    -h, --help                       Show this message
    -V, --version                    Show version
```

</details>

## Web API

### Overview

Gorush provides RESTful APIs for sending notifications and monitoring system status:

| Endpoint        | Method | Description                |
| --------------- | ------ | -------------------------- |
| `/api/push`     | POST   | Send push notifications    |
| `/api/stat/app` | GET    | Application statistics     |
| `/api/stat/go`  | GET    | Go runtime statistics      |
| `/sys/stats`    | GET    | System performance metrics |
| `/metrics`      | GET    | Prometheus metrics         |
| `/healthz`      | GET    | Health check               |
| `/api/config`   | GET    | Current configuration      |

### Send Notifications - `POST /api/push`

#### Basic Examples

##### iOS (APNS) API

```json
{
  "notifications": [
    {
      "tokens": ["ios_device_token"],
      "platform": 1,
      "title": "Hello iOS",
      "message": "Hello World iOS!"
    }
  ]
}
```

##### Android (FCM) API

```json
{
  "notifications": [
    {
      "tokens": ["android_device_token"],
      "platform": 2,
      "title": "Hello Android",
      "message": "Hello World Android!"
    }
  ]
}
```

##### Huawei (HMS) API

```json
{
  "notifications": [
    {
      "tokens": ["huawei_device_token"],
      "platform": 3,
      "title": "Hello Huawei",
      "message": "Hello World Huawei!"
    }
  ]
}
```

#### Advanced Examples

##### iOS with Custom Sound

```json
{
  "notifications": [
    {
      "tokens": ["ios_device_token"],
      "platform": 1,
      "title": "Important Alert",
      "message": "Critical notification",
      "apns": {
        "payload": {
          "aps": {
            "sound": {
              "name": "custom.wav",
              "critical": 1,
              "volume": 0.8
            }
          }
        }
      }
    }
  ]
}
```

##### Multiple Platforms

```json
{
  "notifications": [
    {
      "tokens": ["ios_token"],
      "platform": 1,
      "message": "Hello iOS!"
    },
    {
      "tokens": ["android_token"],
      "platform": 2,
      "message": "Hello Android!"
    }
  ]
}
```

### Statistics APIs

#### Application Stats - `GET /api/stat/app`

```json
{
  "version": "v1.18.9",
  "busy_workers": 0,
  "success_tasks": 150,
  "failure_tasks": 5,
  "submitted_tasks": 155,
  "total_count": 155,
  "ios": {
    "push_success": 80,
    "push_error": 2
  },
  "android": {
    "push_success": 65,
    "push_error": 3
  },
  "huawei": {
    "push_success": 5,
    "push_error": 0
  }
}
```

#### System Performance - `GET /sys/stats`

```json
{
  "pid": 12345,
  "uptime": "2h30m15s",
  "total_response_time": "45.2ms",
  "average_response_time": "1.2ms",
  "total_status_code_count": {
    "200": 1450,
    "400": 12,
    "500": 3
  }
}
```

### Request Parameters

<details>
<summary>Complete API request parameters</summary>

#### Request body

The Request body must have a notifications array. The following is a parameter table for each notification.

| name                    | type         | description                                                                                       | required | note                                                          |
| ----------------------- | ------------ | ------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------- |
| notif_id                | string       | A unique string that identifies the notification for async feedback                               | -        |                                                               |
| tokens                  | string array | device tokens                                                                                     | o        |                                                               |
| platform                | int          | platform(iOS,Android)                                                                             | o        | 1=iOS, 2=Android (Firebase), 3=Huawei (HMS)                   |
| message                 | string       | message for notification                                                                          | -        |                                                               |
| title                   | string       | notification title                                                                                | -        |                                                               |
| priority                | string       | Sets the priority of the message.                                                                 | -        | `normal` or `high`                                            |
| content_available       | bool         | data messages wake the app by default.                                                            | -        |                                                               |
| sound                   | interface{}  | sound type                                                                                        | -        |                                                               |

Frequently Asked Questions