message-pusher

To upgrade your database from version v0.3 to v0.4 (using SQLite as an example), follow these steps:

1. Backup: Create a backup of your existing database file.
2. Schema Migration: Download the latest v0.4 version and start the program. The program will automatically migrate the database table structure.
3. Stop: Terminate the running program.
4. Data Migration: Execute the migration script: ./bin/migrate_v3_to_v4.py to migrate the actual data.
5. Restart: Start the program again.

CRITICAL: Before running the script, ensure that the column order in the users table matches the order expected by the script to prevent data corruption.

The Message Pusher service provides an API to send notifications via various channels. The base API URL follows the pattern: https://<domain>/push/<username>. You must replace <domain> and <username> with your actual configured values.

Request Methods

• GET: Use query parameters to send messages.
• POST: Use form data or JSON. If sending JSON, you must set the Content-Type header to application/json.

Run the message-pusher service as a Docker container. By default, it listens on port 3000 and uses SQLite for data storage. Ensure the host directory for data exists and has write permissions.

If you cannot pull from Docker Hub, use the GitHub Container Registry mirror: ghcr.io/songquanpeng/message-pusher.

docker run -d --restart always --name message-pusher -p 3000:3000 -e TZ=Asia/Shanghai -v /home/ubuntu/data/message-pusher:/data justsong/message-pusher

To deploy manually, you must build the web frontend using npm and the backend using Go.

1. Build the web assets.
2. Download Go dependencies and build the binary.
3. Run the binary with desired flags.

Initial credentials: Username root, Password 123456.

# Build
git clone https://github.com/songquanpeng/message-pusher.git
cd message-pusher/web
npm install
npm run build
cd ..
go mod download
go build -ldflags "-s -w" -o message-pusher

# Run
chmod u+x message-pusher
./message-pusher --port 3000 --log-dir ./logs

You can build desktop, mobile, or web applications to receive messages by connecting to the server via WebSocket. Note that only one client per user can be connected at a time; connecting a new client will disconnect the previous one.

Connection Protocol

• Endpoint: ws://<domain>:<port>/api/register_client/<username>?secret=<secret>
• Secure Connection: If HTTPS is enabled, use wss:// instead of ws://.
• Authentication: The secret parameter must be the 服务器连接密钥 (Server Connection Secret) configured in the backend, not the 推送 token (Push Token).

Message Format

Messages are encoded in JSON. Your client should handle the following fields:

{
 "title": "标题",
 "description": "描述",
 "content": "内容",
 "html_content": "转换为 HTML 后的内容",
 "url": "链接"
}

Note: You may ignore any additional fields returned in the JSON object.

To use a custom domain and SSL, configure Nginx as a reverse proxy.

Important: If you are using the WebSocket client feature, you MUST set proxy_read_timeout and proxy_send_timeout to more than 1 minute (recommended: 300s) to prevent connection drops.

server{
   server_name push.justsong.cn;  # Replace with your domain
   
   location / {
          client_max_body_size  64m;
          proxy_http_version 1.1;
          proxy_pass http://localhost:3000;  # Replace with your port
          proxy_set_header Host $host;
          proxy_set_header X-Forwarded-For $remote_addr;
          proxy_cache_bypass $http_upgrade;
          proxy_set_header Accept-Encoding gzip;
          
          # Required for WebSocket support
          proxy_read_timeout 300s;
          proxy_send_timeout 300s;   
   }
}

Use standard npm commands to manage the React Template application. You can install dependencies, start the application in development mode, or build the application for production.

# Install dependencies
npm install

# Runs the app in the development mode
npm start

# Builds the app for production to the `build` folder
npm run build

To change the default server used by the application, set the REACT_APP_SERVER environment variable before running the build command. For example, to point to a specific domain:

REACT_APP_SERVER=http://your.domain.com

You can deploy the message-pusher service using Docker Compose. The service runs on port 3000 by default and requires a persistent volume for data storage.

Key configuration details:

• Image: justsong/message-pusher
• Port Mapping: Maps host port 3000 to container port 3000.
• Environment Variables: Supports TZ to set the system timezone (e.g., Asia/Shanghai).
• Volumes:
  • ./data:/data: Persists application data to a local ./data directory.
  • /etc/localtime:/etc/localtime:ro: Synchronizes the container timezone with the host system.

version: "3"

services:
  message-pusher:
    image: justsong/message-pusher
    restart: unless-stopped
    ports:
      - 3000:3000
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/data
      - /etc/localtime:/etc/localtime:ro

Use the migrate_v3_to_v4.py script to migrate your SQLite database schema and data from version 3 to version 4. This script transforms user-specific channel configurations (like email, WeChat, Lark, DingTalk, etc.) into the new channels table format.

Warning: This script performs a DELETE FROM channels operation before migrating. Ensure you have a backup of your database before running this script.