---
title: "🖥️ Single Server Installation Guide"
description: "Documentation for Single Server"
---

> Complete step-by-step guide for installing Ring2All PBX on a single server

---

## 🏛️ Architecture Diagram

```mermaid
flowchart TB
    subgraph External["External Network"]
        Endpoints[SIP Phones & WebRTC Clients]
        PSTN[Carrier SIP Trunk Provider]
    end

    subgraph SingleServer["Single Server Infrastructure (Debian 13)"]
        Nginx["Reverse Proxy (Nginx 1.26+ SSL/TLS)"]
        
        subgraph Apps["Web Applications"]
            Admin["Ring2All Admin Web (:443)"]
            Portal["User Portal (:443/portal)"]
            Switch["Switchboard (:443/switchboard)"]
            BSS["Ring2All BSS (:443/billing)"]
        end
        
        subgraph BackendServices["Backend Services (Node.js 22 & Fastify 5)"]
            Api["Platform API (:3000)"]
            MonitorApi["Monitoring API (:3001)"]
        end

        subgraph Telephony["Telephony Core (FreeSWITCH 1.11+)"]
            Sofia["Sofia SIP Profile (UDP/TCP/TLS :5060)"]
            RTP["RTP Audio Media (UDP 16384-32768)"]
            Lua["Lua Routing Engine"]
        end

        subgraph Data["Database & Storage"]
            PG[("PostgreSQL 17 DB Engine")]
            Recordings[("Local Audio & Recordings (/var/lib/softswitch)")]
        end
    end

    Endpoints -->|SIP / WebRTC| Sofia
    Endpoints -->|HTTPS| Nginx
    PSTN -->|SIP Inbound/Outbound| Sofia
    PSTN -.->|Audio RTP| RTP
    Endpoints -.->|Audio RTP| RTP

    Nginx --> Admin
    Nginx --> Portal
    Nginx --> Switch
    Nginx --> BSS
    Nginx --> Api
    Nginx --> MonitorApi

    Admin --> Api
    Portal --> Api
    Switch --> MonitorApi
    BSS --> Api

    Api --> PG
    MonitorApi --> PG
    Telephony --> PG
    Telephony --> Recordings
```

---

## 📋 Prerequisites

### Hardware Requirements

| Component | Minimum | Recommended | High Performance |
|-----------|---------|-------------|------------------|
| **CPU** | 4 vCPU | 8 vCPU | 16+ vCPU |
| **RAM** | 8 GB | 16 GB | 32+ GB |
| **Storage** | 100 GB SSD | 250 GB SSD | 500+ GB NVMe |
| **Network** | 100 Mbps | 1 Gbps | 10 Gbps |

### Software Requirements

- **Operating System:** Debian 13 (Trixie) - 64-bit
- **Network:** Static IP address configured
- **Root Access:** Required for installation

### Capacity Reference

| Configuration | Extensions | Concurrent Calls |
|---------------|------------|------------------|
| Minimum (4 vCPU, 8GB) | ~500 | ~50 |
| Recommended (8 vCPU, 16GB) | ~2,500 | ~400 |
| High Performance (16+ vCPU, 32GB+) | ~10,000 | ~1,500 |

---

import { Tabs, TabItem } from '@astrojs/starlight/components';

## ⚡ Option 1: Automated One-Command Installation (Recommended)

For rapid all-in-one deployment on a clean Debian 13 (Trixie) server, run the official bootstrap installer as `root`:

```bash
wget -O- https://repo.softswitchone.com/apt/install-softswitch.sh | bash
```

### What this script performs automatically:
1. Configures Debian system prerequisites and DNS settings.
2. Installs Node.js 22 LTS, PostgreSQL 17, and security packages (`fail2ban`, `nftables`).
3. Registers the official Ring2All APT repository components (`base`, `core`, `devel`, `extras`, `audios`).
4. Installs the `softswitch-all` orchestrator meta-package, deploying all 10 core packages in correct dependency order.
5. Bootstraps databases, initializes system DSNs, and starts systemd services.

---

## 🛠️ Option 2: Step-by-Step Package Installation

If you prefer installing individual packages or customizing dependencies:

### Step 1: Add Ring2All Repository

<Tabs>
  <TabItem label="Debian 13 (Trixie) - Recommended">
```bash
# Install prerequisites
apt update && apt install -y curl gnupg2 lsb-release

# Add GPG key
mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.softswitchone.com/gpg.key | gpg --dearmor -o /etc/apt/keyrings/ring2all.gpg

# Add repository
echo "deb [signed-by=/etc/apt/keyrings/ring2all.gpg] https://repo.softswitchone.com/apt trixie main" > /etc/apt/sources.list.d/ring2all.list

# Update package list
apt update
```
  </TabItem>
  <TabItem label="Debian 12 (Bookworm)">
```bash
# Install prerequisites
apt update && apt install -y curl gnupg2 lsb-release

# Add GPG key
mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.softswitchone.com/gpg.key | gpg --dearmor -o /etc/apt/keyrings/ring2all.gpg

# Add repository
echo "deb [signed-by=/etc/apt/keyrings/ring2all.gpg] https://repo.softswitchone.com/apt bookworm main" > /etc/apt/sources.list.d/ring2all.list

# Update package list
apt update
```
  </TabItem>
  <TabItem label="Ubuntu 24.04 LTS (Noble)">
```bash
# Install prerequisites
sudo apt update && sudo apt install -y curl gnupg2 lsb-release

# Add GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.softswitchone.com/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/ring2all.gpg

# Add repository
echo "deb [signed-by=/etc/apt/keyrings/ring2all.gpg] https://repo.softswitchone.com/apt noble main" | sudo tee /etc/apt/sources.list.d/ring2all.list

# Update package list
sudo apt update
```
  </TabItem>
</Tabs>

### Step 2: Install Packages

#### Quick Method (AIO Meta-Package):
```bash
apt install -y softswitch-all
```

#### Granular Method (Individual Packages):
```bash
# 1. Database (creates schemas, users, tables)
apt install -y softswitch-db

# 2. API Backend & Telemetry
apt install -y softswitch-api softswitch-monitoring-api

# 3. Web Frontends (Admin, Portal, Switchboard) & Authoritative Nginx config
apt install -y softswitch-admin softswitch-portal softswitch-switchboard

# 4. Telephony Core (FreeSWITCH 1.11+ & Lua Routing)
apt install -y softswitch-telephony

# 5. Audio Assets & Multilingual Voice Prompts
apt install -y softswitch-music softswitch-voiceguide-emma softswitch-voiceguide-paloma

# 6. (Optional) Ring2All BSS Carrier Billing & Storefront on same node
apt install -y softswitch-bss-all
```

### Step 3: Enable & Start Services

```bash
# Database
systemctl enable --now postgresql

# Telephony Core
systemctl enable --now freeswitch

# Backend APIs
systemctl enable --now softswitch-api
systemctl enable --now softswitch-monitoring-api

# Web Server (Nginx)
systemctl enable --now nginx
```

**That's it!** 🎉 Your Ring2All PBX is now running.

---

## ✅ Post-Installation Verification

### Check Services Status

```bash
# All services should show "active (running)"
systemctl status postgresql
systemctl status freeswitch
systemctl status softswitch-api
systemctl status softswitch-monitoring-api
systemctl status nginx
```

### Check Database Connection

```bash
# Read generated credentials
cat /etc/softswitch/db-credentials

# Test connection (should show 6 databases)
sudo -u postgres psql -c "\l"
# Expected: ss_admin, ss_telephony, ss_cdr, ss_cc, ss_logs, freeswitch
```

### Check Telephony Server

```bash
# Enter Telephony Server CLI
fs_cli

# Check status (should show internal and external profiles)
sofia status

# Exit
/exit
```

### Access Web Interfaces

| Interface | URL | Description |
|-----------|-----|-------------|
| **Admin Dashboard** | `https://your-server/admin` | System administration |
| **User Portal** | `https://your-server/portal` | End-user self-service |
| **Switchboard** | `https://your-server/switchboard` | Operator console |

Default login: `admin` / *(check setup wizard or database)*

---

## 🔒 Firewall Configuration

```bash
# Allow essential ports
ufw allow 22/tcp      # SSH
ufw allow 80/tcp      # HTTP (redirect to HTTPS)
ufw allow 443/tcp     # HTTPS
ufw allow 5060/udp    # SIP
ufw allow 5060/tcp    # SIP over TCP
ufw allow 5061/tcp    # SIP TLS
ufw allow 16384:32768/udp  # RTP media

# Enable firewall
ufw enable
```

---

## 🔐 SSL Certificate (Let's Encrypt)

```bash
# Install certbot
apt install certbot python3-certbot-nginx

# Obtain certificate (replace with your domain)
certbot --nginx -d pbx.example.com

# Auto-renewal is configured automatically
systemctl status certbot.timer
```

---

## ⚙️ Nginx Configuration

The `softswitch-admin` package includes a default Nginx configuration. For customization:

```bash
nano /etc/nginx/sites-available/softswitch
```

```nginx
server {
    listen 80;
    server_name _;
    
    # Redirect all HTTP to HTTPS
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name _;
    
    # SSL Certificates
    ssl_certificate /etc/ssl/certs/softswitch.crt;
    ssl_certificate_key /etc/ssl/private/softswitch.key;
    
    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    
    # API Backend (Node.js)
    location /api {
        proxy_pass http://127.0.0.1:3000;
        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;
    }
    
    # WebSocket (Monitoring API)
    location /ws {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }
    
    # Admin Dashboard
    location /admin {
        alias /var/www/softswitch/web;
        try_files $uri $uri/ /admin/index.html;
    }
    
    # User Portal
    location /portal {
        alias /var/www/softswitch/portal;
        try_files $uri $uri/ /portal/index.html;
    }
    
    # Switchboard Console
    location /switchboard {
        alias /var/www/softswitch/switchboard;
        try_files $uri $uri/ /switchboard/index.html;
    }
    
    # Root redirect to Admin
    location = / {
        return 302 /admin;
    }
}
```

Apply changes:

```bash
ln -sf /etc/nginx/sites-available/softswitch /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
```

---

## 📁 Credentials & Configuration Files

| File | Description |
|------|-------------|
| `/etc/softswitch/db-credentials` | Database username and password |
| `/etc/softswitch/api.env` | API environment variables |
| `/etc/odbc.ini` | ODBC connections for Telephony Server |
| `/etc/freeswitch/` | Telephony Server configuration |

### View Credentials

```bash
cat /etc/softswitch/db-credentials
```

```
# Softswitch Database Credentials
# Generated: 2026-01-27 15:00:00
DB_USER=ss_db_user
DB_PASSWORD=Xk9mN2pQ4rT7
DB_HOST=127.0.0.1
DB_PORT=5432
```

---

## 🔧 Resource Optimization

Since all services share the same server, optimize resource allocation:

### PostgreSQL Tuning

```bash
nano /etc/postgresql/17/main/postgresql.conf
```

```ini
# Memory (adjust based on available RAM)
shared_buffers = 2GB          # 25% of RAM
effective_cache_size = 6GB    # 75% of RAM
work_mem = 32MB
maintenance_work_mem = 512MB

# Connections
max_connections = 200

# WAL
wal_buffers = 64MB
checkpoint_completion_target = 0.9
```

### Telephony Server Tuning

```bash
nano /etc/freeswitch/autoload_configs/switch.conf.xml
```

```xml
<configuration name="switch.conf">
  <settings>
    <!-- Limit concurrent sessions based on server capacity -->
    <param name="max-sessions" value="200"/>
    <param name="sessions-per-second" value="30"/>
    
    <!-- RTP port range -->
    <param name="rtp-start-port" value="16384"/>
    <param name="rtp-end-port" value="32768"/>
  </settings>
</configuration>
```

---

## 💾 Backup Strategy

### Automated Daily Backup Script

Create `/opt/softswitch-backup.sh`:

```bash
#!/bin/bash
# Softswitch Single Server Backup Script

BACKUP_DIR="/var/backups/softswitch"
DATE=$(date +%Y%m%d_%H%M%S)
RETENTION_DAYS=7

mkdir -p $BACKUP_DIR

# Backup all databases
for db in ss_admin ss_telephony ss_cdr ss_cc ss_logs ss_switchboard; do
    sudo -u postgres pg_dump $db | gzip > "$BACKUP_DIR/${db}_${DATE}.sql.gz"
done

# Backup Telephony Server configs
tar -czf "$BACKUP_DIR/freeswitch_config_${DATE}.tar.gz" /etc/freeswitch

# Backup recordings (if any)
if [ -d "/var/lib/freeswitch/recordings" ]; then
    tar -czf "$BACKUP_DIR/recordings_${DATE}.tar.gz" /var/lib/freeswitch/recordings
fi

# Backup credentials
cp /etc/softswitch/db-credentials "$BACKUP_DIR/db-credentials_${DATE}"

# Remove old backups
find $BACKUP_DIR -type f -mtime +$RETENTION_DAYS -delete

echo "Backup completed: $BACKUP_DIR"
```

Enable and schedule:

```bash
chmod +x /opt/softswitch-backup.sh

# Add to cron (daily at 2 AM)
echo "0 2 * * * root /opt/softswitch-backup.sh" >> /etc/crontab
```

---

## 🔍 Troubleshooting

### Service Not Starting

```bash
# Check logs
journalctl -u softswitch-api -f
journalctl -u freeswitch -f

# Check ports
ss -tlnp | grep -E '3000|3001|5060|5432'
```

### Database Connection Issues

```bash
# Test PostgreSQL
sudo -u postgres psql -c "SELECT 1"

# Check ODBC
isql -v ss_telephony ss_db_user YOUR_PASSWORD
```

### Telephony Server SIP Issues

```bash
# Check SIP profiles
fs_cli -x "sofia status"

# Check registrations
fs_cli -x "sofia status profile internal reg"

# Debug SIP traffic
fs_cli -x "sofia profile internal siptrace on"
```

### Nginx 502 Bad Gateway

```bash
# Check if API is running
curl http://127.0.0.1:3000/api/health

# Check API logs
journalctl -u softswitch-api --since "5 minutes ago"
```

---

## 📈 Scaling Up

When your single server reaches capacity, consider:

1. **Vertical Scaling:** Upgrade CPU/RAM
2. **Database Separation:** Move PostgreSQL to dedicated server
3. **Distributed Deployment:** See [Distributed Installation Guide](distributed-overview.md)

### Capacity Indicators (Time to Scale)

| Metric | Warning | Critical |
|--------|---------|----------|
| CPU Usage | > 70% sustained | > 85% |
| RAM Usage | > 80% | > 90% |
| Concurrent Calls | > 100 | > 150 |
| Database Connections | > 150 | > 180 |

---

## 📊 Installation Summary

| Component | Location | Port |
|-----------|----------|------|
| Admin Dashboard | `/var/www/softswitch/web` | 443 (/admin) |
| User Portal | `/var/www/softswitch/portal` | 443 (/portal) |
| Switchboard | `/var/www/softswitch/switchboard` | 443 (/switchboard) |
| API | `/var/www/softswitch/api` | 3000 |
| Monitoring WS | `/var/www/softswitch/monitoring-api` | 3001 |
| PostgreSQL | System service | 5432 |
| Telephony Server | `/etc/freeswitch` | 5060/5061 |
| Credentials | `/etc/softswitch/db-credentials` | - |

---

*Next: [Distributed Deployment Overview](distributed-overview.md)*