appleboy/gorush

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.

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

Request body

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

iOS alert payload

See more detail about APNs Remote Notification Payload.

iOS sound payload

request format:

{
  "sound": {
    "critical": 1,
    "name": "default",
    "volume": 2.0
  }
}

Android notification payload

See more detail about Firebase Cloud Messaging HTTP Protocol reference.

Huawei notification

1. app_id: app id from huawei developer console
2. bi_tag:
3. fast_app_target:
4. huawei_data: mapped to data
5. huawei_notification: mapped to notification
6. huawei_ttl: mapped to ttl
7. huawei_collapse_key: mapped to collapse_key

See more detail about Huawei Mobulse Services Push API reference.

iOS Example

Send normal notification.

{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 1,
      "message": "Hello World iOS!"
    }
  ]
}

The following payload asks the system to display an alert with a Close button and a single action button.The title and body keys provide the contents of the alert. The “PLAY” string is used to retrieve a localized string from the appropriate Localizable.strings file of the app. The resulting string is used by the alert as the title of an action button. This payload also asks the system to badge the app’s icon with the number 5.

{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 1,
      "badge": 5,
      "alert": {
        "title": "Game Request",
        "body": "Bob wants to play poker",
        "action-loc-key": "PLAY"
      }
    }
  ]
}

The following payload specifies that the device should display an alert message, plays a sound, and badges the app’s icon.

{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 1,
      "message": "You got your emails.",
      "badge": 9,
      "sound": {
        "critical": 1,
        "name": "default",
        "volume": 1.0
      }
    }
  ]
}

Add other fields which user defined via data field.

{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 1,
      "message": "Hello World iOS!",
      "data": {
        "key1": "welcome",
        "key2": 2
      }
    }
  ]
}

Support send notification from different environment. See the detail of issue.

{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 1,
+     "production": true,
      "message": "Hello World iOS Production!"
    },
    {
      "tokens": ["token_a", "token_b"],
      "platform": 1,
+     "development": true,
      "message": "Hello World iOS Sandbox!"
    }
  ]
}

Send a Live Activity push-to-start notification (requires a push-to-start token and push_type / topic for Live Activities):

{
  "notifications": [
    {
      "tokens": ["push_to_start_token"],
      "platform": 1,
      "push_type": "liveactivity",
      "topic": "com.example.app.push-type.liveactivity",
      "event": "start",
      "timestamp": 1685952000,
      "content-state": {
        "homeScore": 0,
        "awayScore": 0,
        "minute": 1,
        "period": "1H"
      },
      "attributes-type": "FootballMatchAttributes",
      "attributes": {
        "homeTeam": "Team 1",
        "awayTeam": "Team 2",
        "league": "Premier League"
      },
      "alert": {
        "title": "Team 1 vs Team 2",
        "body": "Kick-off! The match has started."
      }
    }
  ]
}

Android Example

Send normal notification.

{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 2,
      "message": "Hello World Android!",
      "title": "You got message"
    }
  ]
}

Label associated with the message's analytics data.

{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 2,
      "message": "Hello World Android!",
      "title": "You got message",
      "fcm_options": {
        "analytics_label": "example"
      }
    }
  ]
}

Add notification payload.

{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 2,
      "message": "Hello World Android!",
      "title": "You got message",
      "notification": {
        "icon": "myicon",
        "color": "#112244"
      }
    }
  ]
}

Add other fields which user defined via data field.

{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 2,
      "message": "Hello World Android!",
      "title": "You got message",
      "data": {
        "Nick": "Mario",
        "body": "great match!",
        "Room": "PortugalVSDenmark"
      }
    }
  ]
}

Send messages to topic

{
  "notifications": [
    {
      "topic": "highScores",
      "platform": 2,
      "message": "This is a Firebase Cloud Messaging Topic Message"
    }
  ]
}

Huawei Example

Send normal notification.

{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 3,
      "message": "Hello World Huawei!",
      "title": "You got message"
    }
  ]
}

Add notification payload.

{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 3,
      "message": "Hello World Huawei!",
      "title": "You got message",
      "huawei_notification": {
        "icon": "myicon",
        "color": "#112244"
      }
    }
  ]
}

Add other fields which user defined via huawei_data field.

{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 3,
      "huawei_data": "{'title' : 'Mario','message' : 'great match!', 'Room' : 'PortugalVSDenmark'}"
    }
  ]
}

Send messages to topics

{
  "notifications": [
    {
      "topic": "foo-bar",
      "platform": 3,
      "message": "This is a Huawei Mobile Services Topic Message",
      "title": "You got message"
    }
  ]
}

Response body

Error response message table:

Success response:

{
  "counts": 60,
  "logs": [],
  "success": "ok"
}

If you need error logs from sending fail notifications, please set a feedback_hook_url and feedback_header for custom header. The server with send the failing logs asynchronously to your API as POST requests.

core:
  port: "8088" # ignore this port number if auto_tls is enabled (listen 443).
  worker_num: 0 # default worker number is runtime.NumCPU()
  queue_num: 0 # default queue number is 8192
  max_notification: 100
  sync: false
- feedback_hook_url: ""
+ feedback_hook_url: "https://example.com/api/hook"
+ feedback_header:
+   - x-gorush-token:4e989115e09680f44a645519fed6a976

You can also switch to sync mode by setting the sync value as true on yaml config. It only works when the queue engine is local.

core:
  port: "8088" # ignore this port number if auto_tls is enabled (listen 443).
  worker_num: 0 # default worker number is runtime.NumCPU()
  queue_num: 0 # default queue number is 8192
  max_notification: 100
- sync: false
+ sync: true

See the following error format.

{
  "counts": 60,
  "logs": [
    {
      "type": "failed-push",
      "platform": "android",
      "token": "*******",
      "message": "Hello World Android!",
      "error": "InvalidRegistration"
    },
    {
      "type": "failed-push",
      "platform": "ios",
      "token": "*****",
      "message": "Hello World iOS1111!",
      "error": "Post https://api.push.apple.com/3/device/bbbbb: remote error: tls: revoked certificate"
    },
    {
      "type": "failed-push",
      "platform": "ios",
      "token": "*******",
      "message": "Hello World iOS222!",
      "error": "Post https://api.push.apple.com/3/device/token_b: remote error: tls: revoked certificate"
    }
  ],
  "success": "ok"
}

Deployment

Docker Deployment

Docker Quick Start

# Run with default config
docker run --rm -p 8088:8088 appleboy/gorush

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

# Run in background
docker run -d --name gorush -p 8088:8088 appleboy/gorush

Docker Compose

version: "3"
services:
  gorush:
    image: appleboy/gorush
    ports:
      - "8088:8088"
    volumes:
      - ./config.yml:/home/gorush/config.yml
  redis:
    image: redis:alpine
    ports:
      - "6379:6379"

Kubernetes

Quick Deploy

# Create namespace and config
kubectl create -f k8s/gorush-namespace.yaml
kubectl create -f k8s/gorush-configmap.yaml

# Deploy Redis (optional, for queue/stats)
kubectl create -f k8s/gorush-redis-deployment.yaml
kubectl create -f k8s/gorush-redis-service.yaml

# Deploy Gorush
kubectl create -f k8s/gorush-deployment.yaml
kubectl create -f k8s/gorush-service.yaml

AWS Load Balancer

For AWS ELB:

kubectl create -f k8s/gorush-service.yaml

For AWS ALB, modify service type:

# k8s/gorush-service.yaml
spec:
  type: NodePort # Change from LoadBalancer

Then deploy ingress:

kubectl create -f k8s/gorush-aws-alb-ingress.yaml

Cleanup

kubectl delete -f k8s/

AWS Lambda

Build and Deploy

# Build Lambda binary
git clone https://github.com/appleboy/gorush.git
cd gorush
make build_linux_lambda

# Create deployment package
zip deployment.zip release/linux/lambda/gorush

# Deploy with AWS CLI
aws lambda update-function-code \
  --function-name gorush \
  --zip-file fileb://deployment.zip

Automated Deployment

Using drone-lambda:

AWS_ACCESS_KEY_ID=your_key \
AWS_SECRET_ACCESS_KEY=your_secret \
drone-lambda --region us-west-2 \
  --function-name gorush \
  --source release/linux/lambda/gorush

Netlify Functions

Alternative serverless deployment without AWS:

# netlify.toml
[build]
command = "make build_linux_lambda"
functions = "release/linux/lambda"

[build.environment]
GO_VERSION = "1.24"

[[redirects]]
from = "/*"
status = 200
to = "/.netlify/functions/gorush/:splat"

gRPC Service

Enable gRPC server for high-performance applications:

# config.yml
grpc:
  enabled: true
  port: 9000

Or via environment:

GORUSH_GRPC_ENABLED=true GORUSH_GRPC_PORT=9000 gorush

gRPC Client Example (Go)

package main

import (
    "context"
    "log"
    "github.com/appleboy/gorush/rpc/proto"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

func main() {
    conn, err := grpc.NewClient("localhost:9000", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    client := proto.NewGorushClient(conn)
    resp, err := client.Send(context.Background(), &proto.NotificationRequest{
        Platform: 2,
        Tokens:   []string{"device_token"},
        Message:  "Hello gRPC!",
        Title:    "Test Notification",
    })

    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Success: %v, Count: %d", resp.Success, resp.Counts)
}

FAQ

Common Issues

Q: How do I get FCM credentials?

A: Go to Firebase Console → Project Settings → Service Accounts → Generate New Private Key. Download the JSON file.

Q: iOS notifications not working in production?

A: Make sure you:

1. Use production APNS certificates (production: true)
2. Set correct bundle ID in certificate
3. Test with production app build

Q: Getting "certificate verify failed" error?

A: This usually means:

• Wrong certificate format (use .pem or .p12)
• Certificate expired
• Wrong environment (dev vs production)

Q: How to handle large notification volumes?

A: Configure workers and queue settings:

core:
  worker_num: 8 # Increase workers
  queue_num: 16384 # Increase queue size
queue:
  engine: "redis" # Use external queue

Q: Can I send to multiple platforms at once?

A: Yes, include multiple notification objects in the request:

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

Q: How to monitor notification failures?

A: Enable sync mode or feedback webhook:

core:
  sync: true # Get immediate response
  feedback_hook_url: "https://your-api" # Async webhook

Q: What's the difference between platforms?

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

Performance Tips

• Use Redis for queue and stats storage in production
• Enable gRPC for better performance
• Set appropriate worker numbers based on CPU cores
• Use connection pooling for high-volume scenarios

Security Best Practices

• Store credentials as files, not in config
• Use environment variables for sensitive data
• Enable SSL/TLS in production
• Rotate certificates before expiration
• Monitor failed notifications for security issues

Stargazers over time

License

Copyright 2026 Bo-Yi Wu @appleboy.

Licensed under the MIT License.