Edge Deployment

Complete guide to installing and configuring a Whsipder edge node on your PBX server. Covers automated installation, manual setup, full configuration reference, and troubleshooting.

Prerequisites

Ubuntu 22.04+, Debian 12+, or RHEL 9+ (x86_64)
Root or sudo access
Port 5060/UDP open inbound for SIP from carriers
Port 5080/UDP available for local PBX SIP
Ports 10000–60000/UDP open for RTP media
Outbound HTTPS (443) for API sync to central server
Redis 7+ (installed automatically if not present)
Node.js 20+ (installed automatically if not present)
A Whsipder bootstrap key from your tenant dashboard

Architecture

The edge node consists of four tightly coupled processes managed by PM2: the SIP proxy (Drachtio), the scoring engine (Node.js), the media relay (RTPEngine), and a Redis instance for transient call state. Together they form a transparent SIP B2BUA that intercepts every INVITE before it reaches your PBX.


  Carrier (SIP trunk)
       │
       │  INVITE (port 5060/UDP)
       v
  ┌──────────────────────────────────────┐
  │           Whsipder Edge              │
  │                                      │
  │  Drachtio SIP Server (:5060)         │
  │    ├── Scoring Engine (25 layers)    │
  │    ├── CAPTCHA challenger            │
  │    └── Call state (Redis :6379)      │
  │                                      │
  │  RTPEngine (:22222 ctrl)             │
  │    └── Media relay (10000-60000/UDP) │
  │                                      │
  │  Audio Forwarder ──> GPU Server      │
  └──────────────┬───────────────────────┘
                 │
                 │  INVITE (port 5080/UDP)
                 v
           Your PBX (Asterisk, FS, etc.)

Automated Installation

The fastest way to get running. The installer detects your PBX type, installs all dependencies, reconfigures SIP ports, generates the edge configuration, and starts all services under PM2.

bash

curl -sSL https://get.whsipder.com/edge | bash -s -- \
  --bootstrap-key YOUR_KEY \
  --public-ip YOUR_IP

Or clone and run manually:

bash

git clone https://github.com/dial-labs/whsipder-edge.git
cd whsipder-edge
sudo ./install.sh --bootstrap-key YOUR_KEY --public-ip YOUR_IP

Install flags

Flag	Required	Description
`--bootstrap-key`	Yes	Single-use key from the dashboard for initial registration
`--public-ip`	Yes	Public IP that carriers send SIP traffic to
`--pbx-port`	No	Port to forward calls to (default: 5080)
`--pbx-address`	No	PBX IP if on a separate host (default: 127.0.0.1)
`--skip-pbx-reconfig`	No	Don't auto-reconfigure the PBX listen port
`--gpu-url`	No	URL of the GPU server gateway (e.g. http://gpu:8067)
`--no-redis`	No	Skip Redis install (use if Redis is already running)

What install.sh Does

The automated installer runs these steps in order:

System detection — identifies OS, package manager, and installed PBX type
Dependency installation — installs Node.js 20, Redis 7, PM2, build tools
Drachtio build — compiles Drachtio SIP server from source with TLS support
RTPEngine build — compiles RTPEngine kernel module and userspace daemon
PBX reconfiguration — moves your PBX SIP listener from port 5060 to 5080 (see PBX Guides)
Edge configuration — generates edge.yaml with your bootstrap key, public IP, and detected settings
Bootstrap registration — calls the central server API to register this edge node and exchange the bootstrap key for persistent API credentials
PM2 setup — configures ecosystem.config.js and starts all four processes (drachtio, rtpengine, edge-app, redis)
Verification — runs a health check to confirm all ports are listening and the edge can reach the central server

Manual PBX Setup (setup-pbx.sh)

If you already have Drachtio installed or want to manage the SIP proxy separately, usesetup-pbx.sh to only handle the PBX port reconfiguration:

bash

sudo ./setup-pbx.sh --pbx-port 5080

This script detects your PBX type and updates the SIP bind port. It creates a backup of every config file it modifies. Use --dry-run to preview changes without applying them.

Configuration Reference: edge.yaml

The edge node is configured via a single YAML file at /opt/whsipder-edge/edge.yaml. Below is the complete reference with all fields, defaults, and descriptions.

yaml

# Whsipder Edge Configuration
# /opt/whsipder-edge/edge.yaml

# --- Identity ---
tenant_id: "your-tenant-uuid"        # Assigned during bootstrap
edge_id: "your-edge-uuid"            # Assigned during bootstrap
api_key: "ek_live_..."               # Persistent API key (post-bootstrap)

# --- Network ---
sip:
  public_ip: "203.0.113.10"          # Public IP for SIP/RTP
  listen_port: 5060                  # Inbound SIP port (carrier-facing)
  transport: udp                     # udp | tcp | tls

pbx:
  address: "127.0.0.1"              # PBX IP address
  port: 5080                        # PBX SIP port (after reconfiguration)

rtp:
  port_min: 10000                   # RTP port range start
  port_max: 60000                   # RTP port range end

# --- Central Server ---
central:
  url: "https://api.whsipder.io"    # Central server API endpoint
  sync_interval: 30                 # Config sync interval (seconds)
  heartbeat_interval: 15            # Heartbeat interval (seconds)

# --- Scoring ---
scoring:
  block_threshold: 75               # Score >= this blocks the call
  challenge_threshold: 45           # Score >= this triggers CAPTCHA
  pass_threshold: 0                 # Score < challenge passes through

# --- GPU Server (optional) ---
gpu:
  enabled: false
  url: "http://127.0.0.1:8067"     # GPU gateway URL
  api_key: "gk_..."                # GPU API key
  timeout: 5000                    # Request timeout (ms)
  sample_rate: 100                 # % of calls to send for analysis

# --- Audio CAPTCHA ---
captcha:
  enabled: true
  timeout: 12000                   # Time to solve CAPTCHA (ms)
  max_attempts: 2                  # Retries before blocking
  audio_dir: "./captcha-audio"     # Path to CAPTCHA audio files

# --- Redis ---
redis:
  host: "127.0.0.1"
  port: 6379
  db: 0
  password: ""                     # Leave empty for no auth

# --- Logging ---
logging:
  level: "info"                    # debug | info | warn | error
  file: "/var/log/whsipder/edge.log"
  max_size: "50m"                  # Max log file size before rotation
  max_files: 10                    # Number of rotated files to keep

Verification

After installation, verify everything is running correctly:

Check PM2 processes

bash

pm2 status

You should see four processes in "online" status: drachtio, rtpengine, edge-app, and redis.

Check listening ports

bash

ss -ulnp | grep -E "5060|5080|6379|22222"

Port 5060 should be bound to Drachtio, port 5080 to your PBX, 6379 to Redis, and 22222 to RTPEngine.

Make a test call

Place a call from an external number or SIP phone. In the dashboard Live Feed, you should see the call appear with scoring details within one second of the INVITE arriving. On the PBX, confirm the call rings the expected extension.

✔

Tip: Use pm2 logs edge-app --lines 50 to see real-time scoring decisions for each call. Look for the SCORE_RESULT log entry which shows the composite score and per-layer breakdown.

Troubleshooting

Calls not reaching the PBX

Verify Drachtio is listening on 5060 with ss -ulnp | grep 5060. If it's not running, check pm2 logs drachtio for startup errors. Common causes: another process already bound to port 5060, or the public IP in edge.yaml doesn't match the server's actual IP.

Edge not appearing in dashboard

Check outbound HTTPS connectivity: curl -v https://api.whsipder.io/health. If the central server is unreachable, the edge cannot register or sync. Also verify the api_key inedge.yaml was populated after bootstrap (it should start with ek_live_).

RTPEngine not relaying audio

Ensure the RTP port range (10000–60000) is open in your firewall for UDP traffic. Checkpm2 logs rtpengine for kernel module errors. On some VPS providers, you may need to run RTPEngine in userspace mode by adding --no-kernel to the start command inecosystem.config.js.

High scoring false positives

If legitimate calls are being challenged or blocked, lower the scoring.challenge_thresholdand scoring.block_threshold in edge.yaml. You can also adjust individual layer weights from the dashboard under Scoring > Layer Configuration.

⚠

Warning: Never expose Drachtio's admin port (9022) to the public internet. It is bound to localhost by default. If you need remote admin access, use an SSH tunnel.

What's Next

GPU Server Setup →

Add real-time ASR, deepfake detection, and voice fingerprinting.

PBX Integration Guides →

Platform-specific configuration for Asterisk, FreeSwitch, Kamailio.

Dashboard Guide →

Monitoring, scoring configuration, and tenant management.