How to Install ViciDial on Debian: The Ultimate Scratch Installation Guide
ViciDial is an enterprise-class, open-source contact center suite used by thousands of organizations globally for inbound, outbound, and blended call handling. It features a robust predictive dialer, ACD capabilities, and support for email and website chat integration.
While many users opt for the official ViciBox ISO (based on OpenSuSE), a scratch installation on Debian is often preferred by administrators who require full control over their software environment, familiarity with Debian’s package management, or are installing on remote VPS/Cloud platforms where custom ISO booting is restricted.
This guide details every phase of the “long haul” required to build a production-ready ViciDial server from the ground up.
Hardware Recommendations and System Dimensioning
The success of a ViciDial installation is heavily dependent on the underlying hardware. Telephony applications are highly sensitive to timing and disk I/O.
Minimum Hardware Specifications
- CPU: Quad-Core 2.0+ GHz.
- RAM: 4+ GB.
- Hard Drive: 160+ GB RAID-1 setup.
Capacity Guidelines
A single “Express” server (combining Database, Web, and Telephony roles) can typically handle:
- Outbound: Up to 15–25 agents at a 4:1 dialing ratio with call recordings.
- Inbound: Up to 25–50 agents.
Crucial Note: The most frequent cause of server failure in new installations is the hard drive filling up with call recordings. A RAID-1 setup and diligent monitoring of the /var/spool/asterisk/monitorDONE directory are vital.
Phase 1: OS Preparation and Optimization
Begin with a minimal Debian installation (netinstall) to keep the system lean.
1. Initial Updates
Log in as the root user and perform a full distribution upgrade to ensure all security patches are applied:
apt-get update && apt-get dist-upgrade.
2. Kernel Optimization
For high-performance VoIP, it is recommended to install a 1000 Hz Realtime Kernel (linux-image-rt-amd64). This provides the necessary timing precision for Asterisk. After installation, update the bootloader and reboot:
apt-get install -y linux-image-rt-amd64 linux-headers-rt-amd64
update-grub
reboot.
Verify the kernel is loaded with uname -r; it should reflect the rt (real-time) status.
3. Security and Firewall (Xtables GeoIP)
To protect against unauthorized access and toll fraud, install a GeoIP Firewall. This allows you to restrict traffic to specific countries (e.g., US and Germany) while dropping everything else.
- Essential Ports: Ensure ports 80 (HTTP), 443 (HTTPS), and 5060 (SIP) are accessible to your trusted networks.
- White-listing: Always allow traffic from your local loopback (127.0.0.1) and your specific VoIP providers.
Phase 2: Installing Dependencies and CPAN Modules
ViciDial is a complex ecosystem requiring a LAMP stack (Apache, MySQL/MariaDB, PHP) and extensive Perl libraries.
1. Apt-Get Dependencies
Install the core development tools and utilities:
apt-get install apache2 build-essential libmysqlclient-dev libncurses5-dev libsox-fmt-all mpg123 mysql-server php5 php5-mysql screen sox subversion.
2. The Perl CPAN Marathon
ViciDial relies on nearly 50 Perl modules to handle background scripts and database communication. This process can take approximately 30 minutes and requires user interaction. Key modules include:
- DBI and DBD::mysql (Database connectivity).
- Net::Telnet (Asterisk Manager Interface communication).
- Spreadsheet::WriteExcel (Reporting exports).
3. Asterisk-Perl (The 0.08 Rule)
Critical Warning: You must use Asterisk-Perl version 0.08. Version 0.09 and newer are known to be incompatible with ViciDial and will cause the system to fail.
cd /usr/src
wget http://asterisk.gnuinter.net/files/asterisk-perl-0.08.tar.gz
tar -zxf asterisk-perl-0.08.tar.gz
cd asterisk-perl-0.08
perl Makefile.PL && make all && make install.
Phase 4: Telephony Subsystem (DAHDI and Asterisk)
1. DAHDI (Timing)
ViciDial requires a timing source for its predictive dialing engine. If you do not have physical telephony hardware, DAHDI can use kernel timers.
- As of DAHDI 2.3.0, the dahdi_dummy module is no longer required; the core automatically uses the system’s kernel timers.
- Compile DAHDI and LibPRI (for ISDN support) from source.
2. Compiling Patched Asterisk
ViciDial requires specific patched versions of Asterisk (typically 1.4, 1.8, or 13) to handle the high volume of calls and unique signaling required for predictive dialing.
cd /usr/src/asterisk/asterisk-1.8.23.0-vici
./configure && make clean && make && make install && make samples.
Enable Asterisk to start automatically on boot by copying the init script into /etc/init.d/.
3. Audio Files
Download and extract the required English sounds in GSM, uLaw, and Wav formats into /var/lib/asterisk/sounds. Use Sox to adjust the volume of Music-on-Hold (MOH) files to 0.25 to prevent audio distortion.
Phase 5: Database Setup and Application Installation
1. Database Configuration
ViciDial uses a central database to manage its operations. Set up the asterisk database and the cron user:
CREATE DATABASE `asterisk` DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci;
CREATE USER 'cron'@'localhost' IDENTIFIED BY '1234';
GRANT SELECT, INSERT, UPDATE, DELETE, LOCK TABLES on asterisk.* TO cron@'%' IDENTIFIED BY '1234';
flush privileges;.
Optimization: Edit /etc/mysql/my.cnf to set connect_timeout=60 and comment out bind-address = 127.0.0.1 to allow external connections if you plan to cluster your servers later.
2. ViciDial (astguiclient) SVN Checkout
Obtain the latest code from the SVN trunk, which ensures you have the most up-to-date features and patches.
mkdir /usr/src/astguiclient
cd /usr/src/astguiclient
svn checkout svn://svn.eflo.net:3690/agc_2-X/trunk
cd trunk
perl install.pl.
Optimization: Edit /etc/mysql/my.cnf to set connect_timeout=60 and comment out bind-address = 127.0.0.1 to allow external connections if you plan to cluster your servers later.
2. ViciDial (astguiclient) SVN Checkout
Obtain the latest code from the SVN trunk, which ensures you have the most up-to-date features and patches.
mkdir /usr/src/astguiclient
cd /usr/src/astguiclient
svn checkout svn://svn.eflo.net:3690/agc_2-X/trunk
cd trunk
perl install.pl.
During installation, you must define your server IP and the webroot path (usually /var/www or /var/www/html).
Phase 6: Post-Installation and Automation
1. IP and Area Codes
Run the following scripts to ensure the dialer recognizes local times correctly and that all database entries match your current server IP:
/usr/share/astguiclient/ADMIN_area_code_populate.pl.
/usr/share/astguiclient/ADMIN_update_server_ip.pl --old-server_ip=10.10.10.15.
2. Crontab: The Heartbeat of ViciDial
The crontab is essential for automating ViciDial’s background processes. You must add entries for:
- Audio Mixing: Moving and compressing call recordings.
- Keepalive: Ensuring Asterisk and other processes remain running.
- Hopper Update: Filling the agent lead hopper every minute.
- Log Cleaning: Removing logs older than 2 days to save disk space.
3. RC.Local Automation
Update your /etc/rc.local script to automatically launch MySQL, Apache, DAHDI, and Asterisk upon reboot to ensure system availability after a power failure.
Security and Administration.
1. Administrative Access
Once the server reboots, navigate your browser to http://yourserverip/vicidial/welcome.php.
- Default Username: 6666
- Default Password: 1234.
2. Password Security
It is highly recommended to change the root password and database passwords to something secure (12+ characters, alphanumeric with special symbols) to prevent toll fraud.
Frequently Asked Questions (FAQ)
Can I host ViciDial on a Cloud VPS like AWS or DigitalOcean?
Yes, ViciDial can run on these platforms as long as the network settings are accurate. However, for large call volumes, a dedicated server is preferred to avoid “noisy neighbor” issues that can affect telephony timing.
Do I need a fixed IP address?
A static IP is strongly recommended to maintain stable SIP registrations with your carriers.
When should I move to a Cluster setup?
You should move to a cluster (separate Database, Web, and Telephony servers) when you exceed 20 outbound agents or 30 inbound agents. Clustering roles horizontally allows the system to scale to support thousands of concurrent calls.
What happens if I use the wrong version of Asterisk-Perl?
If you use version 0.09 or higher, the system will appear to install, but critical scripts will fail to communicate with Asterisk, leading to a non-functional dialer.
Final Summary and Analogy
Building a ViciDial server from scratch on Debian is much like building a performance race car from individual parts rather than buying one from a dealership. While the official ViciBox ISO is the “pre-built car” ready to drive, the scratch installation requires you to manually torque every bolt (dependency) and tune the timing (DAHDI/Kernel).
This manual approach is a “long haul,” but it ensures that you—the administrator—understand exactly how every gear and wire functions. This knowledge is invaluable when troubleshooting high-volume traffic or scaling the system to support hundreds of agents.