Last updated: March 2026 | Reading time: ~14 minutes
Every VICIdial installation guide I've found makes the same mistake: it assumes you have an entire weekend to burn. You don't. You want a working dialer, you want it fast, and you want to know which installation path won't blow up at 2 a.m. on launch day.
This guide covers three methods — ranked by speed — with exact commands, realistic time estimates, and the post-install checklist that gets you from "blank server" to "first test call placed." Pick the one that matches your situation and skip everything else.
Before You Touch a Server: Hardware Requirements
VICIdial runs Asterisk under the hood, and Asterisk is picky about timing. That means bare metal or dedicated hardware. Running VICIdial on a $5/month VPS will produce choppy audio, MeetMe conference errors, and agents who can't hear anything. Don't do it.
Minimum specs (5–15 agents):
| Component | Minimum | Recommended |
|---|---|---|
| CPU | 4 cores, 2.4 GHz | 8 cores, 3.0 GHz |
| RAM | 8 GB | 16 GB |
| Storage | 200 GB SSD (mandatory) | 500 GB NVMe |
| Network | 100 Mbps | 1 Gbps |
| OS | ViciBox 12, AlmaLinux 9, Rocky 9 | ViciBox 12.0.2 |
Scaling rule of thumb: budget one server per 25 agents. Beyond that, you need a cluster — one database/web server plus dedicated Asterisk boxes. Our cluster configuration guide walks through the multi-server topology.
What about cloud? AWS, Hetzner, and OVH all work if you use dedicated instances (not shared VPS). AWS c5.xlarge or Hetzner's dedicated EX-series are solid starting points. Expect $100–$350/month for a single production server. Our cloud deployment guide covers provider-specific setup.
Method 1: ViciBox ISO (15 Minutes)
Best for: First-timers, single-server deployments, people who just want it to work.
ViciBox is the official turnkey distribution. It bundles OpenSUSE, Asterisk, MariaDB, Apache, and all the VICIdial application code into a single ISO. Download it, boot it, answer five questions, and you have a running dialer. It is the fastest path to a working system.
Step 1: Download the ISO
Grab ViciBox 12.0.2 (the current stable release) from the official download server:
https://download.vicidial.com/iso/vicibox/server/
Burn it to a USB drive with dd, Rufus (Windows), or balenaEtcher. For a VM test lab, just mount the ISO directly.
# Linux/Mac — write ISO to USB (replace /dev/sdX with your drive)
sudo dd if=vicibox-12.0.2-amd64.iso of=/dev/sdX bs=4M status=progress
sync
Step 2: Boot and Run Phase 1
Boot from the USB. Select Install ViciBox at the boot menu and press Enter.
The Phase 1 installer handles the base OS. You'll configure:
- Installation disk — Select the target drive (SSD required). If you have multiple disks, pick the one you want as root.
- Root password — Set something strong. You'll SSH in with this later.
- Network — Set a static IP. DHCP works for testing but you'll regret it in production when your IP changes and every SIP trunk breaks.
Phase 1 takes about 5–8 minutes depending on disk speed. When you see the vicibox12:~ # prompt, remove the USB and reboot:
reboot
Step 3: Run Phase 2 (VICIdial Installation)
After reboot, log in as root. The ViciBox post-install wizard starts automatically, or you can trigger it:
vicibox-install
This script installs all VICIdial components — Asterisk, MariaDB, the web admin panel, AGC scripts, DAHDI timing, sound files — everything. It asks for:
- MySQL root password — pick something and remember it
- Server IP — your static IP from Phase 1
- Timezone — get this right the first time (see the gotchas section below)
Phase 2 runs for about 5–7 minutes. When it finishes, your web admin panel is live.
Step 4: Access the Admin Panel
Open a browser and navigate to:
http://YOUR_SERVER_IP/vicidial/welcome.php
Default admin login: 6666 / 1234. Change this immediately.
Total time: ~15 minutes. That's not marketing; that's actual wall-clock time on a modern SSD-based server.
ViciBox Pros and Cons
| Pros | Cons |
|---|---|
| Fastest installation path | Locked to OpenSUSE base |
| Official support available | Less control over OS packages |
| All components pre-configured | Harder to customize Asterisk build flags |
| Regular security patches | Single-server only (cluster needs manual config) |
Method 2: Manual Install on AlmaLinux 9 / Rocky Linux 9 (~45–90 Minutes)
Best for: Production deployments, teams that want full OS control, anyone who needs custom Asterisk modules.
CentOS 7 reached end-of-life in June 2024. If you're following a guide that says yum install on CentOS 7 — stop. AlmaLinux 9 and Rocky Linux 9 are the current RHEL-compatible targets.
There are two sub-options here: the community auto-installer (faster) or a full manual scratch install (most control).
Option A: Community Auto-Installer (~45 Minutes)
The carpenox installer automates the entire process on AlmaLinux 9. It pulls all dependencies, compiles Asterisk, installs DAHDI, checks out VICIdial from SVN, and configures the database.
# Set timezone first — critical
timedatectl set-timezone America/New_York
# System updates
dnf check-update
dnf update -y
dnf -y install epel-release git
dnf install kernel* --exclude=kernel-debug* -y
# Disable SELinux (VICIdial doesn't play nice with it)
sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config
# Clone the installer
cd /usr/src
git clone https://github.com/carpenox/vicidial-install-scripts.git
cd vicidial-install-scripts
# Reboot to load new kernel (required for DAHDI)
reboot
After reboot:
cd /usr/src/vicidial-install-scripts
chmod +x main-installer.sh
./main-installer.sh
The installer is interactive — it will ask for your server IP, MySQL password, and timezone. Follow the prompts. The whole process takes 30–45 minutes depending on your internet speed and CPU.
When it finishes, hit the admin panel at http://YOUR_IP/vicidial/welcome.php with credentials 6666 / 1234.
Option B: Full Manual Scratch Install (~90 Minutes)
If you want to control every package version, compile flag, and config file, here's the manual path. This is the same process the auto-installer runs, just broken into individual steps so you can see what's happening.
1. Base system prep:
# Disable SELinux
sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config
# Install development tools and EPEL
dnf -y install epel-release
dnf update -y
dnf groupinstall "Development Tools" -y
# Enable PowerTools/CRB repo (needed for devel packages)
dnf config-manager --set-enabled crb
2. Install all dependencies in one shot:
dnf install -y php php-cli php-gd php-curl php-mysqlnd php-ldap php-zip \
php-fileinfo php-opcache php-mbstring php-xml php-xmlrpc php-imap \
wget unzip make patch gcc gcc-c++ subversion php-devel gd-devel \
readline-devel httpd libpcap libpcap-devel ncurses ncurses-devel \
screen mutt newt-devel sqlite-devel libuuid-devel sox sendmail \
lame lame-devel htop iftop mariadb-server mariadb-devel \
perl-CPAN perl-YAML perl-libwww-perl perl-DBI perl-DBD-MySQL perl-GD \
openssl-devel libxml2-devel libedit-devel libsrtp-devel \
elfutils-libelf-devel kernel-devel-$(uname -r) mod_ssl certbot
3. Start MariaDB and create the database:
systemctl enable --now mariadb
mysql -e "
SET GLOBAL connect_timeout=60;
CREATE DATABASE asterisk DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci;
CREATE USER 'cron'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT SELECT,INSERT,UPDATE,DELETE,LOCK TABLES ON asterisk.* TO 'cron'@'%' IDENTIFIED BY 'your_secure_password';
CREATE USER 'custom'@'localhost' IDENTIFIED BY 'your_custom_password';
GRANT SELECT,INSERT,UPDATE,DELETE,LOCK TABLES ON asterisk.* TO 'custom'@'%' IDENTIFIED BY 'your_custom_password';
GRANT RELOAD ON *.* TO 'cron'@'%';
FLUSH PRIVILEGES;
"
4. Install Perl modules:
cd /usr/bin/
curl -LOk http://xrl.us/cpanm
chmod +x cpanm
cpanm -n Digest::MD5 Digest::SHA1 DBI DBD::mysql Net::Telnet Time::HiRes \
Net::Server Mail::Sendmail Unicode::Map Spreadsheet::WriteExcel \
OLE::Storage_Lite Proc::ProcessTable IO::Scalar Spreadsheet::ParseExcel \
Curses Getopt::Long Net::Domain Term::ReadKey Term::ANSIColor \
Spreadsheet::XLSX Spreadsheet::Read LWP::UserAgent HTML::Entities \
HTML::Strip HTML::FormatText HTML::TreeBuilder Time::Local \
MIME::Decoder Mail::POP3Client Mail::IMAPClient IO::Socket::SSL \
MIME::Base64 MIME::QuotedPrint Crypt::Eksblowfish::Bcrypt Text::CSV
5. Compile DAHDI (timing source):
cd /usr/src/
wget https://downloads.asterisk.org/pub/telephony/dahdi-linux-complete/dahdi-linux-complete-current.tar.gz
tar xzf dahdi-linux-complete-current.tar.gz
cd dahdi-linux-complete-*/
make && make install && make install-config
modprobe dahdi
dahdi_genconf
6. Compile Asterisk:
cd /usr/src/
wget http://download.vicidial.com/required-apps/asterisk-13.29.2-vici.tar.gz
tar xzf asterisk-13.29.2-vici.tar.gz
cd asterisk-13.29.2/
# Configure with bundled pjproject (handles NAT traversal)
./configure --libdir=/usr/lib64 --with-pjproject-bundled --with-jansson-bundled
make menuselect # Enable app_meetme, res_speech, codec_g729 if licensed
make -j$(nproc)
make install
make samples
make config
7. Check out VICIdial from SVN and run the installer:
mkdir -p /usr/src/astguiclient
cd /usr/src/astguiclient
svn checkout svn://svn.eflo.net:3690/agc_2-X/trunk
cd trunk
perl install.pl
The install.pl script asks for paths and server configuration. Accept defaults for most options; set your webroot to /var/www/html.
8. Populate the database and start services:
mysql asterisk < /usr/src/astguiclient/trunk/extras/MySQL_AST_CREATE_tables.sql
mysql asterisk < /usr/src/astguiclient/trunk/extras/first_server_install.sql
# Update server IP in the database
/usr/share/astguiclient/ADMIN_update_server_ip.pl --old-server_ip=10.10.10.15
# Populate area codes
/usr/share/astguiclient/ADMIN_area_code_populate.pl
# Start everything
systemctl enable --now httpd
systemctl enable --now asterisk
9. Install sound files:
cd /var/lib/asterisk/sounds
wget -q http://downloads.digium.com/pub/telephony/sounds/asterisk-core-sounds-en-ulaw-current.tar.gz
wget -q http://downloads.digium.com/pub/telephony/sounds/asterisk-core-sounds-en-wav-current.tar.gz
wget -q http://downloads.digium.com/pub/telephony/sounds/asterisk-extra-sounds-en-ulaw-current.tar.gz
tar xzf asterisk-core-sounds-en-ulaw-current.tar.gz
tar xzf asterisk-core-sounds-en-wav-current.tar.gz
tar xzf asterisk-extra-sounds-en-ulaw-current.tar.gz
Admin panel: http://YOUR_IP/vicidial/welcome.php — login 6666 / 1234.
Manual Install Pros and Cons
| Pros | Cons |
|---|---|
| Full control over every component | Takes 45–90 minutes |
| Choose your own Asterisk version | More moving parts to break |
| Custom kernel and module support | You own every dependency update |
| Works on any RHEL 9 derivative | No official support for manual builds |
Method 3: Docker Containers (~20 Minutes)
Best for: Dev/test environments, CI pipelines, teams already running Kubernetes, people who want to tear down and rebuild without hosing their host OS.
Docker and VICIdial have a complicated history. Early attempts failed because of DAHDI timing issues — Asterisk's MeetMe conferencing module needs a kernel-level timing source. Modern Docker on Linux shares the host kernel clock, which means LXC containers can handle DAHDI just fine. The Perl scripts technically don't need to run on the same box as Asterisk, so splitting them into separate containers actually helps scalability.
There's no official VICIdial Docker image. Community-maintained images exist on Docker Hub, but they vary in quality. The most reliable approach is building your own from the ViciBox base or the AlmaLinux scratch install.
Docker Compose Stack
Here's a minimal docker-compose.yml that runs VICIdial with separate containers for web/app, Asterisk, and MariaDB:
version: '3.8'
services:
vicidial-db:
image: mariadb:10.11
container_name: vicidial-db
restart: unless-stopped
environment:
MYSQL_ROOT_PASSWORD: your_root_password
MYSQL_DATABASE: asterisk
MYSQL_USER: cron
MYSQL_PASSWORD: your_cron_password
volumes:
- vicidial-db-data:/var/lib/mysql
- ./sql/MySQL_AST_CREATE_tables.sql:/docker-entrypoint-initdb.d/01-schema.sql
- ./sql/first_server_install.sql:/docker-entrypoint-initdb.d/02-seed.sql
ports:
- "3306:3306"
vicidial-web:
build:
context: .
dockerfile: Dockerfile.vicidial
container_name: vicidial-web
restart: unless-stopped
depends_on:
- vicidial-db
ports:
- "80:80"
- "443:443"
environment:
VICIDIAL_DB_HOST: vicidial-db
VICIDIAL_DB_NAME: asterisk
VICIDIAL_DB_USER: cron
VICIDIAL_DB_PASS: your_cron_password
SERVER_IP: "YOUR_HOST_IP"
volumes:
- vicidial-recordings:/var/spool/asterisk/monitorDONE
vicidial-asterisk:
build:
context: .
dockerfile: Dockerfile.asterisk
container_name: vicidial-asterisk
restart: unless-stopped
privileged: true # Required for DAHDI timing
depends_on:
- vicidial-db
ports:
- "5060:5060/udp"
- "5060:5060/tcp"
- "10000-10500:10000-10500/udp" # RTP range
environment:
VICIDIAL_DB_HOST: vicidial-db
SERVER_IP: "YOUR_HOST_IP"
volumes:
vicidial-db-data:
vicidial-recordings:
Building the Asterisk Container
Your Dockerfile.asterisk needs DAHDI compiled against the host kernel headers. Mount them from the host or install them in the container:
FROM almalinux:9
RUN dnf -y install epel-release && dnf update -y && \
dnf groupinstall -y "Development Tools" && \
dnf install -y wget subversion kernel-devel \
libxml2-devel openssl-devel newt-devel \
sqlite-devel libuuid-devel sox lame lame-devel
# Build DAHDI, Asterisk, checkout VICIdial
# (Use the same compile steps from Method 2)
EXPOSE 5060/udp 5060/tcp
CMD ["asterisk", "-f"]
Important: the vicidial-asterisk container runs with privileged: true. That's the only way DAHDI can access kernel timing. If you're not comfortable with privileged containers in production, stick with ViciBox or bare metal.
Start the Stack
docker-compose up -d
# Watch logs
docker-compose logs -f vicidial-web
# Access admin panel
http://YOUR_HOST_IP/vicidial/welcome.php
Docker Pros and Cons
| Pros | Cons |
|---|---|
| Reproducible builds | Privileged container required |
| Easy teardown and rebuild | No official images |
| Scales with orchestration | DAHDI needs host kernel headers |
| Isolates components cleanly | More moving parts than ViciBox |
| Great for dev/test | Not battle-tested for 100+ agent production |
For the full Docker deep-dive including Kubernetes deployment and volume management, see our Docker deployment guide.
Post-Install Checklist: First Campaign in 10 Minutes
You've got a running VICIdial instance. Now you need to make it actually do something. Here's the fastest path to your first test call.
1. Change the Default Admin Password
Log in at /vicidial/welcome.php with 6666 / 1234. Go to Admin > Users > 6666 and change the password. Do this now, not later.
2. Set the Server Timezone
Navigate to Admin > Servers > Modify Server. Verify the timezone matches your system clock. If it doesn't match, your call logs will show wrong timestamps and Local Call Time enforcement will dial people at 3 a.m.
# Verify system timezone
timedatectl
# If wrong, fix it
timedatectl set-timezone America/Chicago
Then update the PHP timezone in your php.ini to match:
date.timezone = America/Chicago
Restart Apache:
systemctl restart httpd
3. Add a SIP Trunk (Carrier)
Go to Admin > Carriers > Add Carrier. You need a VoIP provider that gives you SIP credentials. Fill in:
- Carrier Name: Your provider's name
- Protocol: SIP
-
Registration String:
provider_username:provider_password@sip.provider.com -
Codec: Start with
ulaw(G.711). It's uncompressed, uses more bandwidth, but causes fewer audio issues than G.729.
Save. Asterisk will register with your provider within 30 seconds. Check the CLI to confirm:
asterisk -rx "sip show registry"
You should see your provider listed with a status of Registered.
4. Create Your First Campaign
Go to Admin > Campaigns > Add Campaign:
-
Campaign ID:
TEST01(2–8 uppercase characters) -
Campaign Name:
Test Campaign -
Dial Method:
RATIO(start here; switch toADAPT_AVERAGE_INTENSITYlater) -
Auto Dial Level:
1.0(one line per agent — safe for testing) -
Active:
Y - Local Call Time: Set to your region's allowed calling hours
5. Create a Lead List and Upload Leads
Go to Admin > Lists > Add List:
-
List ID:
10001 -
List Name:
Test Leads -
Campaign:
TEST01 -
Active:
Y
Upload a CSV with at minimum these columns: phone_code (1 for US), phone_number, first_name, last_name. Even three rows is enough for testing. Go to Admin > Lists > Load Leads and upload the file.
6. Create an Agent User
Go to Admin > Users > Add User:
-
User ID: Pick a number (e.g.,
100) - Password: Set something real
-
User Level:
1(agent) -
User Group:
AGENTS
7. Set Up an Agent Phone
Go to Admin > Phones > Add Phone:
-
Extension:
100 - Server IP: Your VICIdial server IP
-
Protocol:
SIP -
Login:
100 - Pass: Set a SIP password
Register a softphone (Zoiper, MicroSIP, or the built-in WebRTC phone) to your server using these credentials.
For WebRTC setup (no softphone needed), see our WebRTC agent guide.
8. Make Your First Test Call
- Open the agent interface:
http://YOUR_IP/agc/vicidial.php - Log in with your agent credentials
- Select the
TEST01campaign - Click Resume to go into active status
- The dialer should pull a lead and dial it
If audio works both ways, congratulations — you have a working dialer.
The Gotchas That Eat Your Weekend
Every VICIdial install hits at least one of these. Save yourself the troubleshooting by checking them upfront.
Timezone Mismatch (The #1 Issue)
VICIdial checks time consistency between three sources: the system clock, PHP, and MariaDB. If any of them disagree, you'll see "There is a time synchronization problem with your system" on every page.
Fix it in one pass:
# 1. Set system timezone
timedatectl set-timezone America/New_York
# 2. Set PHP timezone
sed -i 's/;date.timezone =/date.timezone = America\/New_York/' /etc/php.ini
# 3. Restart services
systemctl restart httpd mariadb
ViciBox 12.0.2 fixed a MariaDB TIMESTAMP field default that caused phantom time sync errors. If you're on an older ViciBox version, upgrade.
Firewall Blocking SIP/RTP
SIP runs on port 5060 (TCP and UDP). RTP audio runs on a configurable range, usually 10000–20000 UDP. If your firewall blocks any of these, calls will either fail to connect or connect with no audio.
# firewalld (AlmaLinux/Rocky)
firewall-cmd --permanent --add-port=5060/udp
firewall-cmd --permanent --add-port=5060/tcp
firewall-cmd --permanent --add-port=10000-20000/udp
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --reload
If calls connect but one or both sides hear silence, that's almost always a NAT/firewall issue with RTP. Check that your externip and localnet settings in Asterisk's SIP config are correct.
Codec Mismatches
If your SIP provider expects G.729 and you're sending G.711 (ulaw), calls will fail with a 488 Not Acceptable Here error. Match your Asterisk codec settings to whatever your carrier requires.
Check what codecs are loaded:
asterisk -rx "core show codecs"
Set the carrier's codec in Admin > Carriers > Modify Carrier under the dial prefix or trunk config. When in doubt, ulaw (G.711) works with 95% of providers and avoids transcoding overhead.
DAHDI Timing Not Loaded
If MeetMe conferencing won't start and agents can't hear anything, DAHDI probably isn't loaded. Verify:
lsmod | grep dahdi
If nothing comes back, load it:
modprobe dahdi
dahdi_genconf
Then add dahdi to /etc/modules-load.d/dahdi.conf so it loads on boot.
SELinux Blocking Apache or Asterisk
If the web panel returns a blank page or 403 errors and your Apache error log shows permission denials, SELinux is the culprit. VICIdial doesn't ship with SELinux policies.
# Check if SELinux is enforcing
getenforce
# Disable it (required for VICIdial)
sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config
reboot
Asterisk Not Starting After Reboot
Usually a missing DAHDI module or a bad extensions.conf. Check the logs:
tail -100 /var/log/asterisk/messages
asterisk -rvvv
Look for Unable to open pseudo channel (DAHDI timing) or pbx_config: Failed to load (broken dialplan).
Method Comparison: Which One Should You Pick?
| Factor | ViciBox ISO | Manual (AlmaLinux 9) | Docker |
|---|---|---|---|
| Install time | 15 min | 45–90 min | 20 min |
| Skill required | Basic Linux | Intermediate | Docker + Linux |
| OS control | Limited | Full | Full |
| Production ready | Yes | Yes | Dev/test only |
| Official support | Yes (VICIhost) | Community only | Community only |
| Max agents | 25 per server | 25 per server | Untested at scale |
| Upgrade path | zypper update |
svn update + recompile |
Rebuild image |
| Best for | First install, SMB | Enterprise, custom builds | Testing, CI/CD |
Our recommendation: Start with ViciBox for your first install. Get familiar with the admin panel, campaigns, and call flow. When you outgrow a single server or need custom Asterisk modules, do a manual install on AlmaLinux 9 for your production cluster. Keep Docker for your staging environment.
What to Do After Installation
A running dialer is just the starting point. Here's what to tackle in your first week:
Configure AMD (Answering Machine Detection) — Without it, agents waste 30%+ of their time listening to voicemail greetings. Our AMD configuration guide covers the settings that actually matter and the ones you should never touch.
Tune your dial level — Starting at 1.0 is safe but slow. Our auto-dial level tuning guide shows how to ramp up without spiking your abandonment rate.
Set up call recording — Required for QA and compliance. Enable it in the campaign settings and configure storage rotation before your disk fills up. See our call recording guide.
Harden security — Change all default passwords, set up firewall rules, restrict admin panel access by IP, and enable HTTPS. Our security hardening guide has the full checklist.
Set up monitoring — The Real-Time Report is your best friend. Learn it. Our real-time report guide explains every metric.
STIR/SHAKEN compliance — If you're dialing US numbers, your carrier needs STIR/SHAKEN attestation or your calls will show "Spam Likely." This isn't a VICIdial setting — it's a carrier requirement. Our STIR/SHAKEN guide explains what to ask your provider.
Need Help Getting Past the Install?
Installation is the easy part. The hard part is tuning VICIdial so your agents actually connect with live humans instead of burning through leads.
We've spent years tuning VICIdial deployments for outbound sales teams. AMD settings, dial level optimization, caller ID rotation, carrier selection — the stuff that turns a $0.03/minute dialer into a machine that books meetings.
Book a free 30-minute teardown — we'll look at your current setup and tell you exactly where you're leaving conversions on the table. If we can help, we'll quote it. If we can't, you still walk away with a list of fixes. No pitch, no pressure.
Top comments (0)