Installing VICIdial: The Complete Guide

Installing VICIdial is not one task. It is a stack of decisions and steps that have to line up: an operating system, a telephony engine, a web application, a database, a firewall, and a handful of background scripts that keep everything in sync. Done by hand, a first install is a multi-hour job, and a first attempt often runs longer because of small mismatches you only discover when something does not dial. This guide walks the whole picture so you know what you are signing up for before you start, and so you can decide whether the do-it-yourself route or a managed box is the right call for you.

We will cover what you are actually installing, the two main routes to get there, the operating system and hardware you need, the difference between a single server and a cluster, how to register the server inside Admin, what the conf files are, the database underneath it all, the post-install steps that make it safe to put online, and your first login. Each section links to a deeper walkthrough so you can drill in wherever you need detail.

What you are actually installing

VICIdial is not a single program. It is a web and reporting layer that sits on top of Asterisk, the open-source telephony engine that places and receives the actual calls. When people say they are installing VICIdial, they really mean installing three things that have to work together: the Asterisk PBX, the VICIdial web application (the Admin pages, the agent screen, and the reports), and a database that stores leads, campaigns, dispositions, recordings metadata, and configuration.

Calls travel over SIP (Session Initiation Protocol), the signalling protocol most carriers speak today, while some internal links between dialers still use IAX2, a lighter Asterisk-native protocol. The agent screen joins a customer and an agent into a single conference room so they can talk, and audio quality depends heavily on which Codec you negotiate with your carrier. Behind the curtain, a set of Keepalive scripts run from cron every minute to launch dialer processes, rebuild config, and recover anything that crashed. None of this is optional plumbing you can skip; it is the system. For a fuller breakdown of each moving part, read what installing VICIdial actually involves.

The two install routes

There are two realistic ways to get a working dialer. The first is the ViciBox ISO: a prebuilt openSUSE-based image with Asterisk, VICIdial, and the database already compiled and wired together. You boot the ISO, run the installer, and answer a few prompts. It is the closest thing to a packaged experience, and it is what most people who are new to the platform should start with. The full walkthrough lives in installing VICIdial from the ViciBox ISO.

The second route is a scratch install on a stock Linux you already run. Here you start from a clean operating system, install the dependencies by hand, compile Asterisk, pull the VICIdial source, and run its install script. This gives you control over the exact versions and the underlying distribution, at the cost of time and the chance to get a dependency wrong. The scratch path differs a little by distribution, so we have separate guides for installing from scratch on Ubuntu and installing from scratch on Debian. Either distribution works; the differences are mostly package names and a few system quirks.

Both routes end at the same place: a Perl install script that creates the database schema, lays down the web files, and writes the initial config. Knowing what that script does, and what each prompt means, saves you a great deal of guesswork. We step through it line by line in the VICIdial install.pl script, step by step.

flowchart TD
  A[Decide to run VICIdial] --> B{Want a prebuilt image}
  B -- Yes --> C[Boot the ViciBox ISO]
  B -- No --> D{Pick a Linux distro}
  D -- Ubuntu --> E[Scratch install on Ubuntu]
  D -- Debian --> F[Scratch install on Debian]
  C --> G[Run install.pl]
  E --> G
  F --> G
  G --> H[Register server in Admin]
  H --> I[Generate and rebuild conf files]
  I --> J[Open firewall and add HTTPS]
  J --> K[First login and test call]

Operating system and hardware requirements

VICIdial is picky about its environment because Asterisk is timing-sensitive. You want a 64-bit Linux, a real or well-provisioned CPU with steady clock behaviour, enough RAM to hold the database working set, and disk that is fast enough to write call recordings without stalling. The exact numbers depend on how many agents you run and whether you record every call. A small ten-agent campaign is comfortable on a modest box; a hundred concurrent agents with recordings is a different machine entirely. The detailed targets are in operating system and hardware requirements for VICIdial, and if you want help mapping agent count to specs, see sizing a VICIdial server for your agent count.

Many people run VICIdial on a VPS from a cloud provider rather than a physical server, which is fine as long as the host gives you consistent CPU and does not throttle network or disk. There are a few extra cautions on virtual hardware, covered in installing VICIdial on a VPS. One caution worth repeating early: oversubscribed shared hosting will cause audio jitter that no amount of dialer tuning fixes, so choose your host carefully.

Single server or a cluster

For most teams, a single server is the right answer. One box runs Asterisk, the web app, and the database together, and it will comfortably carry dozens of agents. You only need a cluster when you outgrow a single machine, when you want to separate the web and reporting load from the telephony load, or when you need redundancy. A clustered build splits roles across machines and introduces extra settings for balance dialing between dialers. We compare the two designs in single-server vs clustered VICIdial install, and dig into the role split in web server vs telephony server roles.

The honest advice is to start with one server. Clustering adds real operational weight: more boxes to patch, conf files that have to agree across machines, and a database that may need to live on its own host as you scale. Reach for it when you have a measured reason, not before.

A faster path than the multi-hour install

Before we get into Admin and conf files, a fair point: everything above is real work, and a first install often eats an afternoon or more once you count the dependency hunting and the inevitable retry. If your goal is a working dialer rather than a Linux project, VICIfast provisions a managed, secured VICIdial box for you in under 40 seconds, on its own Branded subdomain with HTTPS already in place. You skip the operating system, the compile, the firewall, and the conf-file dance entirely. See VICIfast pricing if you would rather start dialing today. If you want to keep building it yourself, read on; the rest of the install is below.

Registering the server in Admin

Once the software is on disk, VICIdial still needs to know about the machine it is running on. Every server has a record in the Admin Servers list, and the dialer uses that record to decide how to behave. You create it from the Add a New Server link in the left menu. The add form is deliberately short and asks for five required fields: a server ID, a server name, the server IP address, and the Asterisk version. The server ID is just a nickname to identify the box to Admin users, and it must contain only letters or numbers with no spaces or punctuation. The full walkthrough is in adding a server in VICIdial Admin.

After the record is created, click Modify to open the full settings page, where the box really gets tuned. A few of the settings that matter most on day one:

• Max Trunks caps how many lines the auto-dialer will try to use on this server. The default is 96, and you lower it to match what your carrier actually allows.
• Max Calls per Second limits how fast outbound calls are placed. The default is 5, but many SIP carriers want 4 or lower, and a few cannot handle more than 1, so this is a setting you confirm with your provider.
• Asterisk Version must match what you installed. VICIdial changes how it handles certain channels depending on the version string, so getting this wrong causes odd call behaviour.
• Local GMT offset sets the server's GMT offset (lead) from UTC and drives call-time logic, so it has to be right for your dialing hours to behave.
• Conferencing Engine chooses how agent sessions are mixed. The default is MeetMe conference; ConfBridge is the newer engine and only works on patched Asterisk 16 and higher.

At the bottom of that page sit the Generate conf files and Rebuild conf files switches. When you set Generate conf files to Y, VICIdial auto-writes the Asterisk config from your phones, carriers, and load-balancing entries. Setting Rebuild conf files to Y forces a fresh rebuild on the next pass, after which the system flips it back to N on its own. Every settings field, including the manager connection, the Server trunk reservations, and the AGI (Asterisk Gateway Interface) output options, is covered in modifying server settings in VICIdial Admin. The conf-rebuild loop itself is worth understanding on its own; see rebuilding VICIdial conf files after changes.

flowchart LR
  A[Edit phones and carriers] --> B[Set Rebuild conf files to Y]
  B --> C[Keepalive runs every minute]
  C --> D[Asterisk conf files regenerated]
  D --> E[Asterisk reloads]
  E --> F[Rebuild flag flips back to N]

Conf file templates

The auto-generated Asterisk Conf file is built from your VICIdial records, but you rarely want to repeat the same block of parameters on every phone and every carrier. That is what conf file templates are for. A template holds a shared set of parameters, for example allowing a particular Codec, and any phone or carrier entry that points at the template inherits those lines. A few fields never belong in a template, such as secrets and account names, because those are per-entry. Templates keep your config consistent and make changes a one-place edit. The full explanation, with examples, is in server conf file templates explained.

Templates also tie into how carriers are defined. Each carrier, or Server trunk, can use a template or carry its own account entry, a Registration string for providers that require registration, and a protocol of SIP, PJSIP, or IAX. Getting the registration right is where most first calls fail, so test one carrier in isolation before you load campaigns.

The database underneath

VICIdial stores everything in MySQL or its drop-in cousin MariaDB. The install script creates the schema, the user, and the initial seed data, but you still need to understand a few things: where the database lives, how it is tuned, and how it grows as you dial. On a single server the database runs locally; on larger builds it often moves to its own machine. Setup, users, and tuning are in setting up MySQL/MariaDB for VICIdial, and the case for a dedicated database host is in running the VICIdial database on its own server. Schema changes also land between versions, so when you upgrade you may need to run a database schema upgrade.

One operational note: the dialer writes to the database constantly, and a slow or full disk on the database side will quietly degrade everything. Plan a backup strategy from the start rather than after your first scare; a backup strategy for a VICIdial server lays out a sane approach.

Post-install: firewall ports and HTTPS

A fresh install is not yet a safe install. Out of the box, the firewall and TLS are your responsibility, and a VICIdial box exposed to the open internet with default ports and weak secrets gets probed within hours. You need to open exactly the ports VICIdial uses, no more, and you need to lock the rest down. Which ports, and why, is in which ports to open for VICIdial. The web interface and the agent screen should never run over plain HTTP, so putting the box behind a certificate is mandatory before you let agents log in; the steps are in putting VICIdial behind HTTPS.

There is a short list of other things to verify before you trust the box: time and NTP, the keepalive crontab, audio codecs for your carrier, and a quick personalize pass. Rather than miss one, run through the VICIdial post-install checklist. The checklist is the difference between a box that works in a demo and a box that survives a real shift.

First login to Admin

With the server registered, conf files generated, the firewall closed down, and HTTPS in place, you finally log in. The first login is where you change the default credentials, create your real admin user, and confirm the dashboard sees the server you added. From there you load a carrier, add a phone, create a test campaign, and place a single call to confirm audio flows both ways. The first-login walkthrough is in first login to VICIdial Admin after install. If something is off, common VICIdial install errors and fixes covers the usual suspects.

DIY or managed: the honest comparison

Installing VICIdial yourself is entirely doable, and for some teams it is the right choice: you want full control of the box, you have a sysadmin who enjoys the work, or you have compliance reasons to own every layer. If that is you, the spokes above will carry you the whole way, and how long a VICIdial install really takes will set honest expectations on the clock.

But be clear-eyed about the trade. A self-install means you own the operating system patching, the Asterisk compile, the firewall, the certificate renewals, the database backups, and every conf-file rebuild for the life of the system. Those costs do not show up on day one; they show up at 2am on a Saturday. We lay them out plainly in why installing VICIdial yourself is harder than it looks and in the side-by-side at self-installing VICIdial vs managed hosting.

The alternative is Managed hosting: someone else runs the install, the security hardening, and the upkeep, and you get a Single tenant box that is yours alone. VICIfast handles the entire stack above and finishes Provisioning a secured, HTTPS-ready VICIdial server in under 40 seconds, so you go from sign-up to a working dialer the same minute rather than the same afternoon. If you have read this far and decided the install is more project than you want, see VICIfast pricing and let us run it for you. Either way, you now know exactly what installing VICIdial involves end to end, and that knowledge serves you whichever route you take.