SETUP_GUIDE.md

vBot Setup Guide

Overview

This guide provides detailed instructions for setting up both the central vBot server and customer infrastructure. The system is designed with a distributed architecture where the central server handles only transcription and analysis, while customers maintain their own infrastructure.

Central Server Setup

1. Deploy to Hugging Face Space

1. Create a Hugging Face account if you don't have one

2. Create a new Space:

   • Go to https://huggingface.co/spaces
   • Click "New Space"
   • Choose "Gradio" as the SDK
   • Set the Space name (e.g., "vBot")
   • Set visibility (public/private)

3. Clone the repository:

   git clone https://huggingface.co/spaces/iajitpanday/vBot
   cd vBot
   

4. Configure environment variables:

   cp .env.example .env
   # Edit .env with your configuration
   

5. Push to Hugging Face:

   git add .
   git commit -m "Initial deployment"
   git push
   

2. Configure Admin Account

1. Access the admin interface:

   • URL: https://your-space.huggingface.space/admin
   • Default credentials: admin/admin

2. Change admin password:

   • Click "Change Password"
   • Enter new secure password
   • Save changes

3. Test System Health

1. Check health endpoint:

   curl https://your-space.huggingface.space/health
   

2. Verify logs:

   tail -f logs/app.log
   

Customer Infrastructure Setup

1. FreePBX Setup

1. Install FreePBX:

   • Download FreePBX 16 or higher
   • Follow the installation guide
   • Complete the setup wizard
   • Ensure all components are properly configured

2. Configure FreePBX:

   • Enable call recording in FreePBX Admin
   • Set up recording paths
   • Configure recording formats
   • Set up SSL certificates

3. Install the customer webhook package:

   git clone https://huggingface.co/spaces/iajitpanday/vBot
   cd vBot/customer_webhook
   composer install
   cp config/config.example.php config/config.php
   

4. Configure the webhook package:

   • Update config/config.php with FreePBX database details
   • Set the vBot API URL and your API key
   • Configure the webhook endpoint

5. Set up FreePBX integration:

   • Configure FreePBX to use the webhook endpoint
   • Set up recording post-processing
   • Configure SSL for secure communication

2. Database Setup

1. Create database:

   CREATE DATABASE vbot_calls;
   USE vbot_calls;
   
   CREATE TABLE call_records (
       id VARCHAR(36) PRIMARY KEY,
       customer_id INT NOT NULL,
       caller_number VARCHAR(20) NOT NULL,
       called_number VARCHAR(20) NOT NULL,
       transcription TEXT,
       summary TEXT,
       sentiment VARCHAR(50),
       keywords TEXT,
       created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
       updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
   );
   

2. Create database user:

   CREATE USER 'vbot_user'@'localhost' IDENTIFIED BY 'your_password';
   GRANT ALL PRIVILEGES ON vbot_calls.* TO 'vbot_user'@'localhost';
   FLUSH PRIVILEGES;
   

3. Webhook Handler Setup

1. Configure webhook handler:

   sudo cp /var/www/html/vbot-webhook/config/config.example.php /var/www/html/vbot-webhook/config/config.php
   sudo nano /var/www/html/vbot-webhook/config/config.php
   

   <?php
   return [
       'db' => [
           'host' => 'localhost',
           'name' => 'vbot_calls',
           'user' => 'vbot_user',
           'pass' => 'your_password'
       ],
       'api_key' => 'your_api_key'
   ];
   

2. Set permissions:

   sudo chown -R www-data:www-data /var/www/html/vbot-webhook
   sudo chmod -R 755 /var/www/html/vbot-webhook
   

4. Testing Setup

1. Test webhook endpoint:

   curl -X POST https://your-domain.com/vbot-webhook/webhook.php \
     -H "Content-Type: application/json" \
     -d '{"test": true}'
   

2. Test call recording:

   # Make a test call
   # Check /tmp/calls/ for recording
   # Check webhook logs
   tail -f /var/log/apache2/vbot-access.log
   

3. Test database:

   SELECT * FROM call_records ORDER BY created_at DESC LIMIT 1;
   

Security Considerations

1. Firewall Configuration:

   sudo ufw allow 80/tcp
   sudo ufw allow 443/tcp
   sudo ufw allow 5060/udp  # SIP
   sudo ufw allow 10000:20000/udp  # RTP
   

2. SSL/TLS:

   • Use Let's Encrypt for free SSL certificates
   • Configure automatic renewal
   • Use strong cipher suites

3. File Permissions:

   • Secure webhook handler files
   • Restrict access to call recordings
   • Use appropriate ownership

4. Database Security:

   • Use strong passwords
   • Limit database access
   • Regular backups
   • Encryption at rest

Monitoring Setup

1. Log Monitoring:

   # FreePBX logs
   tail -f /var/log/asterisk/messages
   
   # Webhook logs
   tail -f /var/log/apache2/vbot-access.log
   
   # Database logs
   tail -f /var/log/mysql/error.log
   

2. System Monitoring:

   # Install monitoring tools
   sudo apt install prometheus node-exporter
   
   # Configure monitoring
   sudo nano /etc/prometheus/prometheus.yml
   

3. Alerting:

   • Set up email notifications
   • Configure alert thresholds
   • Monitor disk space

Maintenance

1. Regular Tasks:

   • Update system packages
   • Rotate logs
   • Backup database
   • Clean old recordings

2. Backup Strategy:

   # Database backup
   mysqldump -u vbot_user -p vbot_calls > backup.sql
   
   # Configuration backup
   tar -czf config_backup.tar.gz /etc/asterisk/
   

3. Update Process:

   # Update webhook handler
   cd /var/www/html/vbot-webhook
   git pull
   
   # Update FreePBX
   sudo apt update
   sudo apt upgrade
   

Troubleshooting

1. Common Issues:

   • Webhook delivery failures
   • Database connection errors
   • Call recording problems
   • SSL certificate issues

2. Debug Tools:

   # Check webhook logs
   tail -f /var/log/apache2/vbot-error.log
   
   # Check FreePBX CLI
   sudo asterisk -rx "core show version"
   
   # Test database connection
   mysql -u vbot_user -p vbot_calls
   

3. Support:

   • Check documentation
   • Review logs
   • Contact support
   • Submit issues