PieHost

PieSocket Self Hosted

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
LOG_STORAGE_DRIVER Same as PIE_DB_DRIVER Database driver used specifically for message logs (sqlite, mysql, or mongodb). Lets you send high-volume logs to a different database than the rest of the app — e.g. keep users/apps on MySQL while logging to MongoDB.
LOG_PARTITIONING — Set to daily to rotate message logs into daily tables (message_logs_YYYY_MM_DD) instead of one unbounded message_logs table, off by default.
LOG_RETENTION_DAYS — Auto-delete log data older than this many days. With LOG_PARTITIONING=daily, whole daily tables are dropped; without it, matching rows are deleted from message_logs directly either way. Unset or 0 keeps logs forever (default).
ANALYTICS_INTERVAL 1000 How often (in ms) buffered message logs are flushed from disk into the database.
WEBHOOK_LOGS_ENABLED false Log webhook delivery attempts and failures to the console — useful when debugging a webhook that isn't firing as expected.
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 - visit the Licenses section in your Pie.host dashboard to purchase one. 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.

Instead of --cluster, you can set PIE_CLUSTER=master-host:4000 as an environment variable — useful for Docker or orchestrated deployments where workers are configured via env vars rather than the container command.

If multiple independent clusters share the same database, set PIE_CLUSTER_ID (default default) on every node in a cluster so worker listings and cluster membership stay scoped to the right cluster.

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, cache channels, client events, and the Pusher Events REST API (POST /apps/:id/events) are all supported.

Advanced tuning (optional)

Variable Default Description
PUSHER_CACHE_TTL_SECONDS 1800 How long data published to a cache channel (cache-*) is retained.
PIE_PRESENCE_HEARTBEAT_MS 20000 Presence channel heartbeat interval, in ms.
PIE_PRESENCE_STALE_MS 60000 How long before an unresponsive presence member is considered gone, in ms.

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

Metrics storage

The dashboard's Analytics charts are powered by a lightweight built-in scraper that polls the server's own Prometheus endpoint and stores samples for querying.

Variable Default Description
METRICS_SCRAPER_ENABLED true Enable the built-in scraper that powers dashboard charts. Set to false to disable.
METRICS_RETENTION_SECONDS 604800 (7 days) How long to keep scraped samples. Set to 0 to keep forever.
TIMESERIES_BACKEND sqlite Where dashboard queries read samples from: sqlite uses the configured database (PIE_DB_DRIVER); prometheus queries an external Prometheus server directly instead.
PROMETHEUS_URL http://localhost:9090 Prometheus server URL, used when TIMESERIES_BACKEND=prometheus.

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.

Changelog

All notable changes to PieSocket Server are documented in the following file.

CHANGELOG.md