VICIdial Installation on Ubuntu 22.04: Step-by-Step for Beginners
Step-by-Step for Beginners
This practical guide explains how to perform a VICIdial installation on Ubuntu 22.04: step-by-step for beginners. You’ll learn prerequisites, system preparation, installing Asterisk and database dependencies, compiling VICIdial, configuring services, and testing call flows. Read carefully and follow each command in order.
Overview & prerequisites
Before you begin the VICIdial installation on Ubuntu 22.04, prepare the environment and confirm hardware and network requirements.
Hardware recommendations
- CPU: 4+ cores for small deployments; 8+ cores for medium.
- RAM: Minimum 8GB; 16GB recommended for production.
- Storage: 100GB SSD for system and recordings; expand as needed for call recording retention.
- Network: Static public IP or properly routed NAT; low-latency dedicated network for voice.
Software & accounts
- Ubuntu Server 22.04 LTS (fresh install, up-to-date).
- Root or sudo-enabled account.
- A registered domain and DNS records if you plan to use FQDNs.
- SIP trunk credentials (SIP provider) for outbound/inbound calls.
Security & backup planning
- Plan for firewall rules, SSH hardening, and fail2ban.
- Backup strategy (database dumps, recordings, config backups) before major changes.
Step 1 — Prepare Ubuntu 22.04 and system settings
Start by updating the OS and setting essential kernel parameters.
Update and install core packages
Run as root or via sudo:
sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential git wget curl vim ufw software-properties-common
Set time zone and sync NTP
Accurate time helps logs and certificates:
sudo timedatectl set-timezone UTC
sudo apt install -y chrony
sudo systemctl enable --now chrony
Add swap (if low RAM)
If RAM is low, add a swap file:
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
Configure firewall basics (UFW)
Open only necessary ports (SSH, HTTP, HTTPS, SIP, RTP range — adjust per deployment):
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
# SIP & RTP example (adjust to your trunk settings)
sudo ufw allow 5060/tcp
sudo ufw allow 5060/udp
sudo ufw allow 10000:20000/udp
sudo ufw enable
Step 2 — Install and configure MariaDB (MySQL) and PHP
VICIdial uses MySQL (MariaDB) and PHP for the web interface and AGI scripts.
Install MariaDB
sudo apt install -y mariadb-server mariadb-client
sudo systemctl enable --now mariadb
sudo mysql_secure_installation
Create databases and users for VICIdial later during VICIdial setup. For now, ensure server is working:
sudo mysql -u root -p -e "SHOW DATABASES;"
Install PHP and modules
VICIdial web and AGI scripts require PHP 7.4+ (22.04 ships with PHP 8; verify compatibility):
sudo apt install -y php php-mysql php-pear php-cli php-curl php-gd php-mbstring php-xml php-zip
Adjust php.ini for max execution and memory limits if needed.
Step 3 — Install and configure Asterisk on Ubuntu 22.04
Asterisk is the PBX foundation for VICIdial. Compile a compatible version.
Install build dependencies
sudo apt install -y libxml2-dev libncurses5-dev libsqlite3-dev uuid-dev libjansson-dev libssl-dev
Download Asterisk source (recommended stable version)
cd /usr/src
sudo wget http://downloads.asterisk.org/pub/telephony/asterisk/asterisk-19-current.tar.gz
sudo tar xvf asterisk-19-current.tar.gz
cd asterisk-19.*/
sudo contrib/scripts/install_prereq install
sudo ./configure
sudo make menuselect
# In menuselect, choose required modules, codecs (ulaw/alaw/g722/g729 if licensed)
sudo make -j$(nproc)
sudo make install
sudo make samples
sudo make config
sudo ldconfig
Start Asterisk:
sudo systemctl enable --now asterisk
sudo asterisk -rvv
Verify basic operation in Asterisk CLI.
Step 4 — Install dependencies specific to VICIdial
VICIdial requires many utilities and libraries: Perl modules, sox, lame, ffmpeg, apache, etc.
Install common dependencies
sudo apt install -y apache2 libapache2-mod-php sox lame sox libsox-fmt-mp3 ffmpeg git
sudo systemctl enable --now apache2
Install Perl modules (CPAN) and utilities used by VICIdial AGI scripts.
Step 5 — Download and install VICIdial
Now get the VICIdial codebase and run the installer. Use official sources or trusted repositories.
Clone VICIdial and run install script
cd /usr/src
sudo git clone https://github.com/VICIdial/vicidial.git /usr/src/vicidial
cd /usr/src/vicidial
sudo ./install.pl
The VICIdial installer prompts for database credentials, Apache settings, admin credentials and more. Provide accurate inputs. If there’s a packaged installer for Ubuntu 22.04, follow that specific guide.
Database creation
During the install, the script will create the vicidial database and import tables. If manually configuring:
sudo mysql -u root -p
CREATE DATABASE asterisk;
CREATE DATABASE vicidial;
CREATE USER 'vicidialuser'@'localhost' IDENTIFIED BY 'securepassword';
GRANT ALL PRIVILEGES ON vicidial.* TO 'vicidialuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;
# Import schema if provided
mysql -u vicidialuser -p vicidial < /usr/src/vicidial/extras/vicidial-schema.sql
Step 6 — Configure Asterisk for VICIdial
VICIdial requires dialplan adjustments, SIP peers, and AGI script linking.
SIP and extensions
- Configure pjsip.conf or sip.conf (depending on Asterisk version) with internal endpoints, trunks, and NAT settings.
- Configure RTP range consistent with UFW rules.
- Place VICIdial context definitions into extensions.conf or use included Asterisk files provided by VICIdial.
AGI & scripts
- Ensure AGI scripts are executable and located in the Asterisk AGI folder (e.g., /var/lib/asterisk/agi-bin/).
- Check AGI owner and permissions: chown asterisk:asterisk /var/lib/asterisk/agi-bin/* && chmod 755 /var/lib/asterisk/agi-bin/*.
Restart Asterisk after changes:
sudo systemctl restart asterisk
Step 7 — Web server and VICIdial GUI configuration
VICIdial uses Apache. Configure virtual hosts, SSL, and PHP settings.
Apache vhost example
Create /etc/apache2/sites-available/vicidial.conf:
<VirtualHost *:80>
ServerName vicidial.yourdomain.com
DocumentRoot /var/www/vicidial
<Directory /var/www/vicidial>
AllowOverride All
Require all granted
</Directory>
ErrorLog ${APACHE_LOG_DIR}/vicidial_error.log
CustomLog ${APACHE_LOG_DIR}/vicidial_access.log combined
</VirtualHost>
Enable site and restart Apache:
sudo a2ensite vicidial.conf
sudo systemctl reload apache2
SSL (recommended)
Use Let’s Encrypt Certbot:
sudo apt install -y certbot python3-certbot-apache
sudo certbot --apache -d vicidial.yourdomain.com
Step 8 — Initial VICIdial admin setup and configuration
Log into the VICIdial web GUI using the admin credentials created during install.
Basic checks and setup
- Verify database connectivity and that cron jobs (mailer, hopper fills) are running.
- Create inbound and outbound campaigns for testing.
- Configure carriers/trunks under Admin → Carriers. Use correct dial prefixes and number formatting.
- Add agents and phones; set up agent login and campaign routing.
Test calls
- Place test outbound calls through your SIP trunk to confirm dial plan and audio.
- Test inbound routing and call distribution for inbound campaigns.
Step 9 — Common troubleshooting and debugging
You will meet common issues: SIP registration, no audio, DB connection errors, AGI failures.
SIP registration fails
- Check credentials and provider IP/port.
- Inspect Asterisk CLI: asterisk -rvvv then pjsip show registrations or sip show peers.
- Use sngrep or tcpdump to capture SIP packets.
One-way or no audio
- Verify RTP ports are open and forwarded.
- Check NAT settings: externaddr and localnet or Asterisk PJSIP NAT settings.
- Ensure codecs match between endpoints and carriers.
Database errors
- Check mysqld status and vicidial user permissions.
- Review logs: /var/log/mysql/error.log and /var/log/asterisk/full.
AGI script errors
- Ensure AGI scripts have correct shebang (#!/usr/bin/perl) and proper execute permissions.
- Examine AGI debug logs and Asterisk CLI for AGI errors.
Step 10 — Performance tuning and scaling
After installation, tune for production.
MySQL tuning
- Increase innodb_buffer_pool_size based on RAM.
- Monitor slow queries and add indexes if necessary.
Asterisk tuning
- Tune ulaw vs compressed codecs to balance CPU and bandwidth.
- Use multiple dialer nodes for high call volume; use central database and replicated reporting servers.
Load balancing and HA
- Use multiple VICIdial dialer nodes behind a load balancer for concurrent calling.
- Use database replication with read replicas for reporting.
Security best practices
Make your VICIdial server secure.
SSH hardening
- Disable root login, use key-based auth, change default SSH port, enable fail2ban.
Firewall and IP restrictions
- Limit admin GUI access to office IPs or use VPN.
- Use application-level authentication and HTTPS.
Patching and monitoring
- Keep Ubuntu and packages updated.
- Implement monitoring (Prometheus/Grafana, Zabbix) and log aggregation (ELK).
Backups and disaster recovery
Backup database, configs, and recordings.
Daily DB backups
- Use mysqldump or Percona XtraBackup for hot backups.
- Rotate backups and store offsite or in cloud storage.
Config and recordings
- Backup /etc/asterisk, /var/lib/asterisk, /var/www/vicidial, and recordings directory.
- Script restores and periodically test restores.
Useful commands and troubleshooting cheat sheet
- Asterisk CLI: sudo asterisk -rvvv
- Check Asterisk logs: /var/log/asterisk/full
- Restart services: sudo systemctl restart asterisk mariadb apache2
- Check SIP peers: sip show peers or pjsip show endpoints
- Check MySQL status: sudo systemctl status mariadb
- View listening ports: ss -tulnp | grep -E “:(5060|10000)”
Final checklist before going live
- Confirm SIP trunk registration and successful test calls.
- Verify agent login flow and campaign dialer behaviour.
- Ensure SSL and firewall rules are in place.
- Confirm daily backup and monitoring are enabled.
- Document system credentials, architecture, and emergency procedures.
Where to learn more and community support
- VICIdial community forums and documentation (official repo).
- Asterisk Project documentation and wiki.
- VoIP and Linux system administration communities for specific errors.
FAQs
Is Ubuntu 22.04 the best operating system for VICIdial?
Yes, Ubuntu 22.04 LTS is a stable and secure operating system commonly used for VICIdial deployments. Many production call centers use Ubuntu LTS releases because they offer long-term updates, better security, and improved package compatibility.
How much hardware do I need to run VICIdial smoothly?
For small setups with up to 15–20 agents, a minimum of 4 CPU cores, 8GB RAM, and a 100GB SSD is recommended. For medium to large deployments, scale up to 8+ CPU cores and 16GB+ RAM. Hardware needs grow based on call recordings, campaigns, and dialing volume.
Can I integrate VICIdial with CRM platforms?
Yes. VICIdial supports CRM integration using APIs, webhooks, and iframe pop-ups. Popular CRMs like Zoho, HubSpot, Salesforce, and custom CRM systems can be integrated to show customer information to agents in real time.
Do I need a public IP address to use VICIdial?
A public static IP is strongly recommended, especially for remote agents and SIP trunk connectivity. You can use NAT with proper configuration, but direct public routing ensures better audio quality and fewer connection problems.
Is VICIdial suitable for both inbound and outbound call centers?
Absolutely. VICIdial is designed as an all-in-one contact center solution. It supports inbound queues, predictive dialing, auto-dialing, manual dialer, blended campaigns, call recording, IVR, and reporting dashboards for supervisors and administrators.
Conclusion
Installing VICIdial on Ubuntu 22.04 may seem complex for beginners, but by following a structured step-by-step process—preparing the server, installing Asterisk, setting up dependencies, configuring Apache and the database, and running initial call tests—you can deploy a fully functional open-source call center dialer. Once installed, focus on performance optimization, security hardening, trunk configuration, backups, and real-world dialing tests.VICIdial is powerful, scalable, and completely free, making it the preferred choice for call-center administrators, VoIP engineers, and businesses looking to build an advanced outbound or inbound dialing solution without high licensing costs. With careful setup and proper tuning, you can support hundreds of agents and deliver high-quality call experiences.Continue learning, document every change, take regular backups, and don’t hesitate to engage the VICIdial community for support.
Your professional call center infrastructure starts here—fully open-source and future-ready.