PieSocket Onprem

Run your own PieSocket real-time infrastructure. Full control, no usage limits, deploy anywhere.

Installation

npm i -g piectl

Then start the server:

pie socket serve

The dashboard will be available at http://localhost:4000 on first run.

If the command is not found

Your system may not have the npm global bin directory in PATH. Fix it with:

macOS / Linux (bash or zsh):

export PATH="$(npm bin -g):$PATH"

Add that line to your ~/.bashrc, ~/.zshrc, or ~/.profile to make it permanent, then reload with source ~/.zshrc.

Windows (PowerShell):

$env:PATH += ";$(npm root -g).bin"

SDK Usage

Once the server is running your can use PieSocket realtime SDKs such as piesocket-js, piesocket-android, piesocket-swift, piesocket-flutter with your self-hosted server.

Simply use clusterDomain and ssl options to initialize PieSocket

var pieSocket = new PieSocket({
    clusterDomain: "localhost:4000",
    ssl:false,
    apiKey: "testkey",
    notifySelf: true
});

Default Ports

Port	Service
4000	Dashboard UI
4001	WebSocket server
4002	Publisher API (server-to-client events)

Change all ports at once

Use --port to set a base port. The server assigns the next two ports automatically:

pie socket serve --port 8000
# WebSocket → 8000, Publisher → 8001, Dashboard → 8002

Set ports individually via environment variables

SOCKETPORT=4001 PUBLISHERPORT=4002 PORT=4000 pie socket serve

Configuration

All configuration is done via environment variables. Create a .env file in the directory where you run the server — it is loaded automatically.

Database

By default the server uses SQLite with a local file. Switch to MySQL or MongoDB for production deployments or multi-node clusters.

Variable	Default	Description
PIE_DB_DRIVER	sqlite	sqlite, mysql, or mongodb
PIE_SQLITE_PATH	./data/piesocket.db	Path to the SQLite database file
PIE_MYSQL_HOST	127.0.0.1	MySQL host
PIE_MYSQL_PORT	3306	MySQL port
PIE_MYSQL_USER	—	MySQL user
PIE_MYSQL_PASSWORD	—	MySQL password
PIE_MYSQL_DATABASE	—	MySQL database name
PIE_MONGODB_URI	—	MongoDB connection URI
PIE_MONGODB_DATABASE	—	MongoDB database name

Pub/Sub

Controls how messages are routed between connections. Use Redis when running multiple server nodes.

Variable	Default	Description
PIE_PUBSUB_DRIVER	local	local (single process) or redis
PIE_REDIS_URL	redis://localhost	Redis connection URL

Logging

Variable	Default	Description
LOG_DIR	/var/tmp/piesocket/logs	Directory for message logs
DEBUG	false	Set to true for verbose output

Security

Variable	Default	Description
JWT_SECRET	Auto-generated	Secret used to sign dashboard session tokens. Set explicitly if you need sessions to survive restarts.

Pro Features

Pro features require a license key from piehost.com. Set it in your environment:

PRO_LICENSE_KEY=your-key-here pie socket serve

Horizontal Scaling (Cluster Mode)

Run multiple worker nodes behind a single master. Each worker handles its own WebSocket connections; messages are routed across workers via Redis.

Requirements:

Valid Pro license
Redis (PIE_PUBSUB_DRIVER=redis with PIE_REDIS_URL pointing to a shared Redis instance)
All nodes sharing the same database

Start the master node (normal startup):

PRO_LICENSE_KEY=your-key PIE_PUBSUB_DRIVER=redis PIE_REDIS_URL=redis://your-redis pie socket serve

Start a worker node:

PRO_LICENSE_KEY=your-key PIE_PUBSUB_DRIVER=redis PIE_REDIS_URL=redis://your-redis pie socket serve --cluster master-host:4000

Workers self-register with the master, send heartbeats every 30 seconds, and automatically re-register if the master restarts. If the master is unreachable at startup, workers continue operating with their last known configuration for up to 1 hour.

The cluster secret is generated automatically on first run and shared from master to workers — you do not need to configure it manually.

Publishing Events from Your Backend

Send events to connected clients via the Publisher API (port 4002 by default):

curl -X POST http://localhost:4002/publish \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your-api-key",
    "secret": "your-api-secret",
    "channel": "room-1",
    "event": "new-message",
    "data": { "text": "Hello!" }
  }'

Pusher-Compatible Mode

The server can act as a drop-in replacement for Pusher, letting you use the official Pusher client SDKs without any code changes.

Enable it:

ENABLE_PUSHER=true pie socket serve

Point your Pusher SDK to the self-hosted server:

const pusher = new Pusher('your-app-key', {
  wsHost: 'your-server-host',
  wsPort: 4001,
  forceTLS: false,
  cluster: 'mt1', // required by SDK but ignored by the server
});

Presence channels, client events, and the Pusher Events REST API (POST /apps/:id/events) are all supported.

Metrics & Health

Health check

GET http://localhost:4000/api/health
→ { "status": "ok" }

Prometheus metrics

GET http://localhost:4001/v3/metrics

Returns metrics in Prometheus text format. In cluster mode, this endpoint automatically aggregates metrics from all live worker nodes.

To scrape only the local node (useful when Prometheus scrapes workers individually):

GET http://localhost:4001/v3/metrics?local=1

Reverse Proxy Setup (nginx)

To serve the dashboard and WebSocket server from a single domain:

server {
    listen 80;
    server_name your-domain.com;

    # Dashboard
    location / {
        proxy_pass http://localhost:4000;
    }

    # WebSocket
    location /ws/ {
        proxy_pass http://localhost:4001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
    }
}

Upgrading

pie socket update

Database migrations run automatically on startup — no manual steps required.