---
title: "💳 Part 14: Deploying Ring2All BSS (Carrier Billing, Real-Time OCS & Customer Store Portal) on Debian 13"
description: "Documentation for 14. Ring2All BSS Setup & Portal"
---

*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:

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

Ensure Node.js 22 LTS is available:
```bash
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:

```bash
# 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:
```bash
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:

```bash
# 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:
```bash
sudo systemctl status softswitch-bss-api
```

Test the internal health check endpoint:
```bash
curl -s http://127.0.0.1:3002/health
```
*Expected Output:*
```json
{"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`)

```nginx
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:

```nginx
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:
```bash
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:
     ```bash
     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.*