💳 Ring2All BSS (Billing & OCS) Deployment Guide

Complete step-by-step guide for installing and configuring Ring2All BSS on Debian 13 (Trixie), decoupling back-office carrier rating from the public customer self-care store.

🏗️ Architecture Overview

The Ring2All BSS (Business Support System) serves as the monetization and commercial intelligence engine for telecom operators. It translates raw network events (SIP INVITEs, Call Detail Records, active media sessions) into billed transactions, manages prepaid customer wallets in real time, and exposes self-service purchasing for virtual DIDs, trunks, and extensions.

flowchart TB
    subgraph DMZ["Public Edge / DMZ (Customer Storefront)"]
        ClientWeb["Customer Self-Care Store<br/>(softswitch-bss-client)<br/>store.carrier.com"]
        EdgeProxy["Nginx DMZ Reverse Proxy / WAF<br/>(Passes ONLY /api/client/*)"]
    end

    subgraph InternalLAN["Internal Management LAN (Zero Direct Public Exposure)"]
        AdminWeb["Back-Office Admin Portal<br/>(softswitch-bss-web)<br/>bss-admin.carrier.com"]
        BssApi["BSS & Real-Time OCS Engine<br/>(softswitch-bss-api :3002)<br/>Fastify 5 / Node.js 22"]
        DB[("PostgreSQL 17 HA Cluster<br/>(customers, wallets, rates, ocs_cdrs)")]
        Redis[("Redis In-Memory Cache<br/>(Sub-millisecond Rate Lookups)")]
    end

    subgraph TelecomNodes["Telecom Execution Nodes"]
        SBC["Ring2All SBC Gateway<br/>(Kamailio 6.1)"]
        PBX["Ring2All PBX Cluster<br/>(FreeSWITCH 1.11+)"]
    end

    ClientWeb -->|HTTPS| EdgeProxy
    EdgeProxy -->|Passes /api/client/*| BssApi
    AdminWeb -->|Internal HTTPS / VPN| BssApi

    BssApi <--> DB
    BssApi <--> Redis

    SBC <-->|Sub-millisecond OCS Auth / Balance Check| BssApi
    PBX <-->|Real-Time CDR & Balance Updates| BssApi

Core Tenets of the BSS Architecture:

Strict Separation of Admin and Storefront:
- Back-Office Admin (softswitch-bss-web): Confined to internal management LANs or secure VPNs. Telecom administrators manage rate decks, carrier costs, customer accounts, and telecom nodes.
- Customer Self-Care Store (softswitch-bss-client): Exposed to the public internet. Subscribers purchase subscription plans, order virtual DID numbers, manage autodialer campaigns, top up wallets, and review CDR usage.
Zero Database Exposure at the Perimeter:
- The customer store is a client-side React 18 Single Page Application. It has zero direct access to PostgreSQL.
DMZ Perimeter Reverse Proxy Filtering:
- The customer edge reverse proxy passes only authenticated customer endpoints (/api/client/*) while aggressively returning 403 Forbidden for administrative routes (/api/v1/users, /api/v1/telecom-nodes, /api/v1/firewall).
Sub-Millisecond Online Charging System (OCS):
- Evaluates call authorization, balance verification, and destination pricing using high-speed caching and sub-millisecond PostgreSQL rating queries before an outbound call is established.

📦 Modular Debian Package Breakdown

Ring2All BSS is distributed via four decoupled Debian packages:

Package Name	Function	Staging Path	Dependencies
`softswitch-bss-api`	Fastify 5 / Node.js 22 OCS rating engine, customer API, billing daemon, background CDR synchronizer	`/var/www/softswitch/bss/api`	`nodejs (>= 22)`, `postgresql-client`
`softswitch-bss-web`	React 18 administrative back-office web application	`/var/www/softswitch/bss/web`	`nginx`
`softswitch-bss-client`	React 18 customer-facing self-care store & billing portal	`/var/www/softswitch/bss/client`	`nginx`
`softswitch-bss-all`	Metapackage for single-server all-in-one deployments	N/A	Depends on all 3 packages above

🚀 Deployment Topologies

Topology A: Single-Server All-in-One

Ideal for small to mid-sized telecom operators. The API daemon, Admin UI, and Customer Store run on the same Debian 13 host:

Admin UI: Accessed at https://bss.carrier.com (or port 443).
Customer Store: Accessed at https://store.carrier.com (or dedicated port :8443).
BSS API: Runs locally on 127.0.0.1:3002, reverse-proxied by Nginx.

Topology B: Distributed Multi-Server DMZ Deployment

Recommended for enterprise carriers and public cloud environments:

Server 1 (Internal LAN / Billing Core):
- Runs softswitch-bss-api, softswitch-bss-web, and PostgreSQL 17.
- Not reachable directly from the public internet. Accessible only via corporate VPN or WireGuard tunnel.
Server 2 (Public Edge / DMZ Store):
- Runs softswitch-bss-client and Nginx.
- Serves static assets for the Customer Store and proxies /api/client/ across the internal network to Server 1.

🛠️ Step-by-Step Installation (Debian 13)

Step 1: System Preparation & Prerequisites

On your target Debian 13 server, install foundational dependencies:

apt-get update
apt-get install -y curl wget gnupg2 openssl nginx postgresql-client

Ensure Node.js 22 LTS is registered:

curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt-get install -y nodejs build-essential

curl -fsSL https://repo.softswitchone.com/apt/setup_repo | bash
apt-get update

Step 2: Database Setup & Schemas

If using a dedicated PostgreSQL host or local database, create the ss_bss database and user:

sudo -u postgres psql << 'EOF'
CREATE DATABASE ss_bss;
CREATE USER bss_user WITH ENCRYPTED PASSWORD 'StrongBssPassword2026!';
GRANT ALL PRIVILEGES ON DATABASE ss_bss TO bss_user;
ALTER DATABASE ss_bss OWNER TO bss_user;
EOF

Step 3: Install BSS Packages

For All-in-One Deployment:

apt-get install -y -o Dpkg::Options::="--force-overwrite" softswitch-bss-all

For Distributed DMZ Deployment:

On Internal Core Server:

apt-get install -y -o Dpkg::Options::="--force-overwrite" softswitch-bss-api softswitch-bss-web

On Public DMZ Edge Server:

apt-get install -y -o Dpkg::Options::="--force-overwrite" softswitch-bss-client

Step 4: Configure Environment Variables

Edit /etc/softswitch/bss-api.env:

NODE_ENV=production
PORT=3002
HOST=127.0.0.1

# Database Configuration
DATABASE_URL=postgresql://bss_user:StrongBssPassword2026!@127.0.0.1:5432/ss_bss

# JWT Security
JWT_SECRET=super-secret-hex-key-minimum-32-chars-long
JWT_EXPIRES_IN=7d

# Telecom Nodes Sync (Ring2All SBC / PBX)
SBC_API_URL=http://127.0.0.1:3003
SBC_API_KEY=sbc_internal_bearer_token

# Stripe Payment Gateway (Optional / Recommended)
STRIPE_SECRET_KEY=sk_live_YourStripeSecretKeyHere
STRIPE_WEBHOOK_SECRET=whsec_YourStripeWebhookSecretHere
STRIPE_CURRENCY=usd

# OCS Real-Time Rating Cache
REDIS_URL=redis://127.0.0.1:6379

Secure permissions and restart the API daemon:

chmod 600 /etc/softswitch/bss-api.env
systemctl daemon-reload
systemctl enable --now softswitch-bss-api
systemctl status softswitch-bss-api

Step 5: Configure Nginx Virtual Hosts

1. Back-Office Administrative Portal (`/etc/nginx/sites-available/bss-admin`)

server {
    listen 80;
    server_name bss-admin.carrier.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name bss-admin.carrier.com;

    ssl_certificate /etc/ssl/certs/bss-admin.crt;
    ssl_certificate_key /etc/ssl/private/bss-admin.key;

    root /var/www/softswitch/bss/web;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # Internal REST API proxy
    location /api/ {
        proxy_pass http://127.0.0.1:3002/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

2. Public Customer Storefront & DMZ Proxy (`/etc/nginx/sites-available/bss-store`)

server {
    listen 80;
    server_name store.carrier.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name store.carrier.com;

    ssl_certificate /etc/ssl/certs/bss-store.crt;
    ssl_certificate_key /etc/ssl/private/bss-store.key;

    root /var/www/softswitch/bss/client;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # DMZ Filtering: ONLY allow customer-facing endpoints
    location /api/client/ {
        proxy_pass http://127.0.0.1:3002/api/client/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Block administrative routes from public store edge
    location /api/v1/ {
        return 403;
    }
}

Enable and reload Nginx:

ln -sf /etc/nginx/sites-available/bss-admin /etc/nginx/sites-enabled/
ln -sf /etc/nginx/sites-available/bss-store /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

💳 Stripe Payment Gateway Integration

Ring2All BSS includes native Stripe integration for automated prepaid wallet recharges and recurring monthly DID/line subscriptions.

1. Webhook Endpoint Registration

In the Stripe Developer Dashboard (https://dashboard.stripe.com/webhooks), create an endpoint:

URL: https://store.carrier.com/api/client/payments/webhook
Events to listen for:
- checkout.session.completed
- payment_intent.succeeded
- invoice.paid
- customer.subscription.deleted

2. Auto-Top-Up Flow

When a customer tops up their prepaid balance via credit card or Apple Pay, Stripe sends an authenticated webhook payload signed with STRIPE_WEBHOOK_SECRET. The BSS API atomically increments the customer’s wallet balance in PostgreSQL and refreshes the in-memory OCS balance cache instantly.

⚡ Interconnecting OCS with Ring2All SBC & PBX

To enforce real-time prepaid balance limits on outbound calling:

In the Ring2All BSS Admin (https://bss-admin.carrier.com), go to Telecom Nodes and register your Ring2All SBC:
- Node Type: Ring2All SBC (Kamailio)
- Internal Host: 10.9.0.1 (or private LAN IP)
- Shared API Token: Generate a secure bearer token.

In Ring2All SBC, configure Kamailio’s HTTP client module (http_client) to query BSS before routing external PSTN calls:

# Kamailio OCS Pre-Call Authorization Hook
http_client_query("http://192.168.10.50:3002/api/ocs/authorize?caller=$fU&callee=$rU", "$var(ocs_res)");
if ($rc != 200) {
    sl_send_reply("402", "Payment Required - Insufficient Funds");
    exit;
}

If balance is sufficient, the call proceeds without noticeable setup latency (< 5ms). When the call ends, Kamailio or FreeSWITCH transmits the final duration to /api/ocs/cdr, deducting the exact cost from the prepaid wallet.

🔍 Verification & Health Checks

1. Service Status

systemctl status softswitch-bss-api
systemctl status nginx

2. API Health Check

curl -s http://127.0.0.1:3002/health
# Expected: {"status":"ok","service":"softswitch-bss-api","version":"1.0.0"}

3. DMZ Reverse Proxy Security Validation

# Permitted customer endpoint (should return 401 Unauthorized or 200 OK)
curl -I https://store.carrier.com/api/client/auth/me

# Prohibited administrative endpoint (MUST return 403 Forbidden)
curl -I https://store.carrier.com/api/v1/users
# Expected: HTTP/1.1 403 Forbidden

🔧 Production Troubleshooting

1. Customers see “Network Error” when browsing store

Cause: Nginx reverse proxy configuration for /api/client/ is misconfigured or softswitch-bss-api is stopped.

Solution: Check API service status and Nginx error logs:

systemctl status softswitch-bss-api
tail -f /var/log/nginx/error.log

2. Wallet does not update after successful Stripe payment

Cause: Stripe webhook secret mismatch or endpoint not receiving POST requests.
Solution: Check journalctl -u softswitch-bss-api -f while testing a webhook event in the Stripe CLI. Verify STRIPE_WEBHOOK_SECRET matches your Stripe dashboard.

🚀 Next Steps

Web Cluster & Load Balancing Guide: Scale your web frontends.
Ring2All SBC Deployment: Secure your perimeter signaling.
Distributed PBX Cluster Guide: Scale out telephony core nodes.