💳 Part 14: Deploying Ring2All BSS (Carrier Billing, Real-Time OCS & Customer Store Portal) on Debian 13

Welcome to the fourteenth installment of our “Debian 13 Clustering & Distribution” series. In previous guides, we covered the deployment of custom APT repositories, FreeSWITCH Class 5 nodes (Ring2All PBX), Kamailio Class 4 perimeter gateways (Ring2All SBC), and high-availability database clusters. In this guide, we complete the carrier ecosystem by deploying Ring2All BSS (Business Support System) on Debian 13 (Trixie). We will explore how modern telecom carriers decouple back-office billing operations from customer-facing storefronts, walk through single-server and distributed DMZ topologies, configure real-time Online Charging System (OCS) engines, and install the modular .deb packages (softswitch-bss-api, softswitch-bss-web, softswitch-bss-client, and softswitch-bss-all).

---

🏗️ Architectural Overview: The Carrier BSS Model

In Tier-1 and wholesale telecom architectures (such as PortaOne PortaBilling, Telnyx, Twilio, and Amdocs), the Business Support System (BSS) serves as the monetization and commercial intelligence engine. It translates raw network events (SIP INVITEs, Call Detail Records, RTP sessions) into monetized transactions, enforces prepaid balance limits in real time, and exposes customer self-service capabilities.

┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                               TIER-1 CARRIER BSS TOPOLOGY                               │
├────────────────────────────────────────┬────────────────────────────────────────────────┤
│          PUBLIC EDGE / DMZ             │           INTERNAL MANAGEMENT LAN              │
│  (Customer Portal / Store / Self-Care) │     (BSS Admin / Real-Time OCS / Databases)    │
│                                        │                                                │
│   ┌────────────────────────────────┐   │   ┌────────────────────────────────────────┐   │
│   │     softswitch-bss-client      │   │   │         softswitch-bss-web             │   │
│   │   (Customer Store / Portal)    │   │   │         (Back-Office Admin)            │   │
│   │    Host: store.carrier.com     │   │   │      Host: bss-admin.carrier.com       │   │
│   └───────────────┬────────────────┘   │   └───────────────────┬────────────────────┘   │
│                   │                    │                       │                        │
│                   │ HTTPS REST API     │                       │ Local Reverse Proxy    │
│                   ▼                    │                       ▼                        │
│   ┌────────────────────────────────┐   │   ┌────────────────────────────────────────┐   │
│   │     Nginx Edge Proxy / WAF     │   │   │           softswitch-bss-api           │   │
│   │   Allows ONLY: /api/client/*   │───┼──>│         (Fastify Core Engine)          │   │
│   │   Blocks: /api/v1/users, etc.  │   │   │         Listens: 127.0.0.1:3002        │   │
│   └────────────────────────────────┘   │   └───────────────────┬────────────────────┘   │
│                                        │                       │                        │
│                                        │                       ▼                        │
│                                        │   ┌────────────────────────────────────────┐   │
│                                        │   │         PostgreSQL 17 HA Cluster       │   │
│                                        │   │   (customers, wallets, rates, ocs_cdrs)│   │
│                                        │   └────────────────────────────────────────┘   │
└────────────────────────────────────────┴────────────────────────────────────────────────┘

Core Tenets of the Ring2All BSS Architecture:

1. Separation of Admin and Storefront:
   • Back-Office Admin (softswitch-bss-web): Confined to internal management subnets or secure VPNs. Telecom operators manage rate decks, customer accounts, telecom nodes (Ring2All SBC / PBX), and wholesale carrier margins.
   • Customer Self-Care Store (softswitch-bss-client): Exposed to the public internet or DMZ. Subscribers purchase VoIP subscription plans, order virtual DID telephone numbers, top up their prepaid wallet using Stripe, and review real-time CDR usage.
2. Zero Database Exposure at the Perimeter:
   • The customer portal is a 100% client-side React 18 Single Page Application (SPA). It never contains direct PostgreSQL database credentials or network access.
3. DMZ Perimeter Reverse Proxy Filtering:
   • The customer edge reverse proxy passes only authenticated customer endpoints (/api/client/*) and public branding metadata, while aggressively issuing 403 Forbidden for administrative routes (/api/v1/users, /api/v1/telecom-nodes, /api/v1/firewall, /api/v1/mcp-roles).
4. Real-Time Online Charging System (OCS):
   • Evaluates call authorization, balance verification, and destination pricing using high-speed in-memory caching (Redis) and sub-millisecond PostgreSQL rating queries.

---

📦 Modular Debian Package Breakdown

Ring2All BSS is distributed via four decoupled Debian packages:

Package Name	Function	Staging Path	Dependencies
softswitch-bss-api	Fastify 4 / 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 the 3 packages above

---

🚀 Deployment Topologies

Topology A: Single-Server All-in-One Deployment

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://bss.carrier.com:8443 (or dedicated virtual host store.carrier.com).
• 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.

---

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

Step 1: System Preparation & Prerequisites

On your target Debian 13 server, install foundational dependencies:

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

Ensure Node.js 22 LTS is available:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Step 2: Database Initialization

Ring2All BSS uses PostgreSQL 17 with the ss_billing database. Connect to your database cluster or local PostgreSQL instance:

# Create the billing database and assign permissions
sudo -u postgres psql << 'EOF'
CREATE DATABASE ss_billing;
GRANT ALL PRIVILEGES ON DATABASE ss_billing TO ss_db_user;
\c ss_billing
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "pgcrypto";
EOF

Ensure /etc/softswitch/db-credentials contains the connection parameters:

sudo mkdir -p /etc/softswitch
cat << 'EOF' | sudo tee /etc/softswitch/db-credentials
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=ss_db_user
DB_PASSWORD=Letacla01
EOF
sudo chmod 600 /etc/softswitch/db-credentials

Step 3: Installing the Ring2All BSS Packages

From your configured Ring2All APT repository, install the complete suite:

# For an All-in-One server:
sudo apt update
sudo apt install -y softswitch-bss-all

# OR for a separated DMZ Customer Store server:
# sudo apt install -y softswitch-bss-client

During package installation, the softswitch-bss-api post-installation script automatically:

1. Verifies the database connection and seeds the complete BSS schema (customers, wallets, plans, rate cards, subscriptions, and transactions).
2. Generates a cryptographically secure JWT_SECRET in /etc/softswitch/bss-api.env.
3. Activates and starts the softswitch-bss-api.service systemd daemon.

Step 4: Verifying the API Service

Inspect the background daemon:

sudo systemctl status softswitch-bss-api

Test the internal health check endpoint:

curl -s http://127.0.0.1:3002/health

Expected Output:

{"status":"ok","timestamp":"2026-09-11T23:00:00.000Z"}

---

🔒 Nginx Reverse Proxy & DMZ Perimeter Hardening

1. Back-Office Admin Configuration (/etc/nginx/sites-available/softswitch-bss-web)

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

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

    ssl_certificate /etc/nginx/ssl/nginx.crt;
    ssl_certificate_key /etc/nginx/ssl/nginx.key;

    # Core BSS Fastify API Proxy
    location /api/ {
        proxy_pass http://127.0.0.1:3002;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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;
    }

    # Admin Web SPA
    location / {
        root /var/www/softswitch/bss/web;
        index index.html;
        try_files $uri $uri/ /index.html;
    }
}

2. Customer Store DMZ Configuration (/etc/nginx/sites-available/softswitch-bss-client)

In a decoupled DMZ setup, the Customer Store Nginx configuration enforces perimeter security:

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

    ssl_certificate /etc/nginx/ssl/nginx.crt;
    ssl_certificate_key /etc/nginx/ssl/nginx.key;

    # ── CARRIER PERIMETER FILTER: BLOCK ADMINISTRATIVE APIS ──
    location ~* ^/api/(v1/)?(users|telecom-nodes|firewall|mcp|system|database|backups|migrations) {
        return 403 '{"error":"Forbidden: Administrative APIs are not accessible via customer perimeter"}';
        add_header Content-Type application/json;
    }

    # ── ALLOWED CUSTOMER APIS PROXY ──
    location /api/ {
        # If API is on a remote internal server, specify its IP: http://10.10.0.5:3002
        proxy_pass http://127.0.0.1:3002;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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;
    }

    # Customer Store SPA
    location / {
        root /var/www/softswitch/bss/client;
        index index.html;
        try_files $uri $uri/ /index.html;
    }
}

Enable both sites and reload Nginx:

sudo ln -sf /etc/nginx/sites-available/softswitch-bss-web /etc/nginx/sites-enabled/
sudo ln -sf /etc/nginx/sites-available/softswitch-bss-client /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

---

🔗 Interconnecting with Ring2All SBC & Ring2All PBX

Ring2All BSS acts as the central financial arbiter between your Session Border Controllers (Ring2All SBC) and Class 5 Media Servers (Ring2All PBX):

                       ┌───────────────────────────────┐
                       │         Ring2All BSS          │
                       │    (Rating, Wallet, Plans)    │
                       └───────┬───────────────┬───────┘
                               │               │
        SIP LCR & OCS Balance  │               │ Tenant & Extension Sync
                               ▼               ▼
                ┌─────────────────────┐ ┌─────────────────────┐
                │    Ring2All SBC     │ │    Ring2All PBX     │
                │   (Kamailio 6.x)    │ │ (FreeSWITCH 1.11.x) │
                └─────────────────────┘ └─────────────────────┘

1. Ring2All SBC Integration:
   • In the BSS Admin UI under Telecom Nodes, register your Ring2All SBC node (http://10.9.0.1:3003 or public IP).
   • The OCS automatically syncs customer prepaid balances to Kamailio memory tables (htable), preventing calls when balances are exhausted.
2. Ring2All PBX Integration:
   • Register your FreeSWITCH Class 5 nodes (http://10.9.0.2:3000).
   • When a customer purchases an extension or phone line in the Customer Store, Ring2All BSS automatically issues REST calls to Ring2All PBX to provision the tenant and extension.
3. Stripe Payment Gateway:
   • In /etc/softswitch/bss-api.env, add your Stripe production credentials:

     STRIPE_SECRET_KEY=sk_live_...
     STRIPE_WEBHOOK_SECRET=whsec_...

   • Restart the daemon: sudo systemctl restart softswitch-bss-api. Customers can immediately add funds with credit cards.

---

📋 Diagnostics & Troubleshooting

Issue	Verification Command	Solution
API won’t start	journalctl -u softswitch-bss-api -n 50 --no-pager	Verify DATABASE_URL in /etc/softswitch/bss-api.env and ensure PostgreSQL is running.
Customer Store shows 403 on API	tail -f /var/log/nginx/softswitch_bss_client_error.log	Verify you are not invoking administrative routes from the store front.
CORS errors in multi-server setup	Check CORS_ORIGINS in /etc/softswitch/bss-api.env	Add the client portal domain to the allowed origins list.
Stripe webhooks failing	curl -X POST http://127.0.0.1:3002/api/v1/client/payments/webhook	Ensure STRIPE_WEBHOOK_SECRET matches your Stripe Dashboard endpoint configuration.

---

You now have a production-ready, carrier-grade Ring2All BSS platform deployed on Debian 13 (Trixie), with secure separation between your internal administrative control plane and your public-facing customer self-care store.