🚀 RayanPBX

Modern, elegant SIP Server Management Toolkit with Web UI, TUI, and CLI

╭──────────────────────────────────────────────────────────────╮
│                                                              │
│             🎯 RayanPBX - SIP Server Management             │
│                                                              │
│        A modern, beautiful, and powerful toolkit for         │
│          managing Asterisk-based PBX systems                 │
│                                                              │
╰──────────────────────────────────────────────────────────────╯

✨ Features

┌─────────────────────────────────────────────────────────────┐
│ 🌐 Web Admin Panel    │  Modern, responsive SPA/PWA        │
│ 🖥️ Terminal UI (TUI)  │  Beautiful CLI interface           │
│ ⚡ Real-time Events   │  WebSocket-based live updates      │
│ 🔐 JWT Authentication │  Secure, token-based auth          │
│ 🎨 Dark Mode          │  Elegant dark/light themes         │
│ 🌍 i18n Support       │  English & Persian (RTL)           │
│ 📱 Extension Manager  │  Complete SIP extension lifecycle  │
│ 🔗 Trunk Routing      │  Advanced outbound call routing    │
│ 🖥️ Asterisk Console   │  Interactive CLI from web UI       │
│ 📊 Live Monitoring    │  Real-time call & system status    │
│ ⚙️ Config Management  │  CLI/TUI/Web .env management       │
│ 🔍 Phone Discovery    │  LLDP/nmap-based phone detection   │
│ 🧪 SIP Testing Suite  │  Comprehensive extension testing   │
└─────────────────────────────────────────────────────────────┘

🏗️ Architecture

╭────────────────────────────────────────────────────────────────╮
│                     RayanPBX Architecture                      │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐    │
│   │   Web UI     │   │     TUI      │   │     CLI      │    │
│   │ (Nuxt/Vue3)  │   │  (Go/Bubble) │   │   (Bash)     │    │
│   └──────┬───────┘   └──────┬───────┘   └──────┬───────┘    │
│          │                  │                   │             │
│          └──────────────────┼───────────────────┘             │
│                             │                                 │
│   ┌────────────────────────────────────────────────────┐     │
│   │         API Server (Laravel 11 / PHP 8.3)         │     │
│   │  ┌─────────────┐  ┌─────────────┐  ┌───────────┐ │     │
│   │  │  JWT Auth   │  │   Console   │  │  WebSocket │ │     │
│   │  └─────────────┘  └─────────────┘  └───────────┘ │     │
│   └────────────────────────┬───────────────────────────┘     │
│                            │                                  │
│   ┌────────────┬───────────┴────────┬─────────────┐         │
│   │            │                    │             │         │
│   ▼            ▼                    ▼             ▼         │
│ ┌─────┐   ┌─────────┐        ┌──────────┐   ┌────────┐    │
│ │MySQL│   │Asterisk │        │  Redis   │   │  PAM   │    │
│ └─────┘   │   22    │        └──────────┘   └────────┘    │
│           └─────────┘                                       │
╰────────────────────────────────────────────────────────────────╯

📦 Tech Stack

Backend

• Laravel 11 - Modern PHP framework
• PHP 8.3 - Latest PHP version
• MySQL/MariaDB - Database
• Redis - Caching & sessions
• JWT - Stateless authentication

Frontend

• Nuxt 3 - Vue.js framework for SPA/PWA
• Vue 3 - Progressive JavaScript framework
• TypeScript - Type-safe development
• Tailwind CSS - Utility-first CSS
• SCSS - Enhanced styling with logical properties
• Pinia - State management

TUI/CLI

• Go 1.23 - Systems programming language
• Bubble Tea - Terminal UI framework
• Lipgloss - Styling for terminals
• Figlet - ASCII art generation

DevOps

• PM2 - Process manager for Node.js
• systemd - Linux service management
• GitHub Actions - CI/CD pipeline
• nala - Modern APT wrapper

SIP/Telephony

• Asterisk 22 - Open source PBX
• PJSIP - Modern SIP stack
• AMI - Asterisk Manager Interface

🚀 Quick Start

One-Line Installation

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/atomicdeploy/rayanpbx/main/install.sh)"

Manual Installation

# Clone the repository
git clone https://github.com/atomicdeploy/rayanpbx.git
cd rayanpbx

# Run the installer (standard mode)
sudo ./install.sh

# Or with verbose mode for debugging
sudo ./install.sh --verbose

Installation Options

The installer supports several command-line options:

# Show help and available options
./install.sh --help

# Show version
./install.sh --version

# List all available installation steps
./install.sh --list-steps

# Install with verbose output (recommended for debugging)
sudo ./install.sh --verbose

# Run only specific steps (for upgrades or partial installations)
sudo ./install.sh --steps=backend,frontend,tui

# Skip certain steps (e.g., skip Asterisk installation)
sudo ./install.sh --skip=asterisk,asterisk-ami

# Automatic upgrade mode (no prompts)
sudo ./install.sh --upgrade

# Create backup before updates
sudo ./install.sh --upgrade --backup

Step-Based Installation

For faster upgrades or when you only need to update specific components:

# Update only the backend API
sudo ./install.sh --steps=source,env-config,backend,systemd

# Update only the frontend
sudo ./install.sh --steps=source,env-config,frontend,pm2

# Update only the TUI
sudo ./install.sh --steps=source,tui,pm2

# Install without Asterisk (development environment)
sudo ./install.sh --skip=asterisk,asterisk-ami

Important: When using --steps or --skip, ensure all dependencies are already installed. See docs/install-steps.md for detailed dependency information.

For detailed information about command-line options, see docs/cli-options.md.

Troubleshooting Installation

If the installation fails or exits unexpectedly:

1. Use verbose mode to see detailed information:

   sudo ./install.sh --verbose 2>&1 | tee install.log

2. Check the log to identify where it failed.

3. Report issues with the log file at: https://github.com/atomicdeploy/rayanpbx/issues

Configuration

Interactive configuration tool:

cd /opt/rayanpbx
./scripts/config-tui.sh

Non-interactive configuration:

./scripts/config-tui.sh /opt/rayanpbx/.env /opt/rayanpbx/.env.example --non-interactive

🚀 Hello World Setup - Your First Call

After installation, get your first phone call working in minutes with the automated Hello World Setup:

# Launch TUI with root permissions
sudo rayanpbx-tui

# Select "Hello World Setup" from the menu
# Click "Run Complete Setup" - everything is automated!
# Note the SIP credentials: Username: 101, Password: 101pass
# Configure your SIP phone and dial 100 to hear "Hello World!"

📖 See the full guide: docs/HELLO_WORLD_GUIDE.md

📖 Usage

Web Interface

╭────────────────────────────────────────────────────╮
│  🌐 Web UI: http://your-server-ip:3000           │
│  📡 API:    http://your-server-ip:8000/api       │
│  🔌 WebSocket: ws://your-server-ip:9000/ws       │
╰────────────────────────────────────────────────────╯

Default login uses your Linux username and password via PAM authentication.

Terminal UI

rayanpbx-tui

Artisan Commands

RayanPBX provides comprehensive Laravel Artisan commands for system management:

# Check system status
php artisan rayanpbx:status

# Run health checks
php artisan rayanpbx:health

# Manage services
php artisan rayanpbx:service restart asterisk

# Manage extensions
php artisan rayanpbx:extension list
php artisan rayanpbx:extension create 101

# Manage trunks
php artisan rayanpbx:trunk list
php artisan rayanpbx:trunk create

# Configuration management
php artisan rayanpbx:config validate
php artisan rayanpbx:config reload

# Backup and restore
php artisan rayanpbx:backup --compress
php artisan rayanpbx:restore /path/to/backup

# Execute Asterisk CLI commands
php artisan rayanpbx:asterisk "core show calls"

For complete documentation, see docs/artisan-commands.md.

Shell Scripts

# Using health check script
/opt/rayanpbx/scripts/health-check.sh full-check

# Using config TUI
/opt/rayanpbx/scripts/config-tui.sh

# Using INI helper
/opt/rayanpbx/scripts/ini-helper.sh modify-manager

Service Management

# Check services
systemctl status rayanpbx-api
systemctl status asterisk

# View PM2 services
pm2 list
pm2 logs

# View logs
journalctl -u rayanpbx-api -f
journalctl -u asterisk -f

🔧 Development

Backend Development

cd /opt/rayanpbx/backend
composer install
php artisan serve

Frontend Development

cd /opt/rayanpbx/frontend
npm install
npm run dev

TUI Development

cd /opt/rayanpbx/tui
go build -o rayanpbx-tui main.go config.go
./rayanpbx-tui

📚 Documentation

╭──────────────────────────────────────────────────────────╮
│  🔧 API Reference:      docs/api.md                      │
│  ⚙️ CLI Options:        docs/cli-options.md              │
│  📦 Artisan Commands:   docs/artisan-commands.md         │
│  📋 Install Steps:      docs/install-steps.md            │
│  🌐 CORS Configuration: docs/cors.md                     │
│  ⚙️ Configuration:      docs/configuration.md            │
│  🔍 Phone Discovery:    docs/phone-discovery.md          │
│  📱 Phone Management:   docs/phone-management.md         │
│  📡 PJSIP Setup:        docs/pjsip-setup.md              │
│  🧪 SIP Testing Guide:  docs/sip-testing.md              │
│  🖥️ UI Documentation:   docs/ui.md                       │
│  📞 VoIP Management:    docs/voip-management.md          │
│  🔐 Security:           docs/security.md                 │
│  📊 Implementation:     docs/implemention.md             │
│  🚀 Deployment:         docs/deployment.md               │
│  🏗️ Architecture:       docs/architecture.md             │
╰──────────────────────────────────────────────────────────╯

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💙 Acknowledgments

• Asterisk - The world's leading open source PBX
• Laravel - The PHP framework for web artisans
• Vue.js - The progressive JavaScript framework
• Go - Build simple, secure, scalable systems
• pollination.ai - AI-powered assistance

📞 Support

╭──────────────────────────────────────────────────────╮
│  🐛 Issues:  github.com/atomicdeploy/rayanpbx/issues │
│  💬 Discussions: github.com/atomicdeploy/rayanpbx    │
│  📧 Email:   support@rayanpbx.local                  │
╰──────────────────────────────────────────────────────╯

---

Built with ❤️ by the RayanPBX Team

╭────────────────────────────────────────╮
│  🚀 Modern • 🎨 Elegant • 💪 Powerful  │
╰────────────────────────────────────────╯