Install & operate
You host the system, so you are its platform operator. This page takes you from an empty Ubuntu server to a running installation, then covers what you do afterwards: organizations, numbers and carriers, backups, upgrades, logs and troubleshooting.
- Operating system
- Ubuntu 24.04 LTS
- Installer
sudo ./install.sh- One config file
config.env- Nightly backup
- 02:30, kept 14 days
Before you start
Server
- Ubuntu 24.04. The preflight step warns on any other release; every package comes from the stock Ubuntu archive (Kamailio 5.7, Asterisk 20, rtpengine 11.5).
- 2 vCPU and 4 GB RAM to start. That size carried 60 concurrent calls in our load test; see Scaling & capacity for larger sites.
- A public IPv4 address that does not change. On AWS use an Elastic IP; a normal public address changes when the instance stops.
- Root access (the installer refuses to run without it) and outbound internet for packages, Node.js 22 and certificates.
- Disk for recordings: plan for it from day one (see Recordings and storage).
DNS name
Create an A record for your domain pointing at the public IP before you install. Let's Encrypt and the browser phone both need it, and browsers only allow the microphone on HTTPS. Wait until the name resolves:
dig +short voice.example.com # must print your PUBLIC_IPCarrier
You need at least one SIP carrier for real phone numbers. The installer sets up a Telnyx trunk from config.env; organizations can add more carriers of their own later in the dashboard. Without a carrier, internal calls, the browser phone, voicemail and the AI agent all still work.
Network and firewall
Only Kamailio, nginx and rtpengine face the internet. Asterisk, the AI agent, MariaDB and the dashboard process listen on loopback only, and the health check fails if any of them is ever exposed on all interfaces.
| Port | Protocol | Open to | Purpose |
|---|---|---|---|
22 | TCP | Your admin IPs | SSH. ufw rate-limits it; change it with SSH_PORT. |
80, 443 | TCP | Everyone | The dashboard, the browser phone (its SIP socket runs at /sip-ws on 443, which gets through most VPNs and proxies) and Let's Encrypt. |
5060 | UDP + TCP | Phones, carriers | SIP signalling. |
5061 | TCP | Phones, carriers | SIP over TLS. |
4443 | TCP | Softphones | WebRTC secure WebSocket directly on Kamailio. |
30000–40000 | UDP | Everyone | Audio (RTP / SRTP) through rtpengine. Set with RTP_PORT_MIN / RTP_PORT_MAX. |
Configure config.env
Every setting for the installation lives in one file. Copy the example and edit it; you can re-run the installer after any change. Secrets you leave empty (database passwords) are generated during install and saved in /etc/voip-stack/secrets.env.
1# ---------- Server identity2DOMAIN="voice.example.com"3PUBLIC_IP="198.51.100.20"4PRIVATE_IP="auto" # the NIC address; "auto" on cloud servers5 6# ---------- TLS7TLS_MODE="letsencrypt" # or "selfsigned" for a test server8LETSENCRYPT_EMAIL="it-ops@example.com"9TELNYX_CALLER_ID="+15551234567" # a number you own at your carrier10 11# ---------- First organization and Asterisk pool12ORG_NAME="Main"13ORG_SLUG="main" # SIP user names become main-1001, main-1002, ...14ASTERISK_INSTANCES=2 # 1 to 4 on this serverMost-used settings
DOMAINstringrequired- The name phones, browsers and certificates use. Must resolve to PUBLIC_IP.
PUBLIC_IPIPv4required- The address clients and carriers reach. The preflight stops while it is still the example value.
PRIVATE_IPIPv4 | autorequired- The address on the network card. Same as PUBLIC_IP on bare metal;
autodetects it. Preflight checks that it really exists on the server. TLS_MODEselfsigned | letsencrypt- letsencrypt for production (needs DNS and port 80). selfsigned creates a private CA for testing.
TELNYX_AUTHip | credentials- How the installation-level Telnyx trunk authenticates. See Numbers and carriers below.
TELNYX_CALLER_IDE.164required- Default outbound caller ID, a number you own.
DEFAULT_COUNTRY_CODEdigits- A number dialled with a single leading 0 gets this country code.Example:
92 PSTN_BLOCK_REGEXregex- Outbound numbers matching it are refused with 403 (premium and satellite ranges by default).
OUTBOUND_MAX_PER_MINnumber- Outbound call attempts per minute per extension before Kamailio answers 503. Default 20.
ASTERISK_INSTANCES1–4- How many Asterisk instances run on this server. See Scaling.
DASHBOARD_ADMIN_EMAILemail- Set it to skip the browser setup wizard; the operator login is then created by the installer.
RECORD_CALLSyes | no- Record extension, phone-network and AI-agent calls, each side separately.
RECORDING_DAYSdays- A daily clean-up deletes recording files older than this. Default 30.
ENABLE_KERNEL_RTPyes | no- Install rtpengine's kernel module for high call volume.
TIMEZONEtz name- The server clock's time zone.Example:
Asia/Karachi
Run the installer
Unpack the release on the server, fill in config.env, and run the installer as root. It runs numbered steps in order, prints a banner for each, and stops at the first error. Every step is idempotent, so you can run it again safely.
1tar xzf voip-stack.tar.gz && cd voip-stack2cp config.env.example config.env && nano config.env3sudo ./install.sh # all steps4sudo ./install.sh --list # show the steps| Step | What it does |
|---|---|
00 | Preflight: Ubuntu release, required config values, PUBLIC_IP no longer the example, PRIVATE_IP present on an interface, SIP ports free, Telnyx credentials when that mode is chosen. |
10 | System tuning: time zone, hostname, chrony, kernel network settings for many UDP flows, file limits, Kamailio and AI-agent log folders and log rotation. |
20 | Packages: Kamailio, Asterisk, rtpengine, MariaDB, nginx, certbot; the rtpengine kernel module when ENABLE_KERNEL_RTP=yes. |
30 | TLS certificates: a private CA and server certificate, or Let's Encrypt. |
40 | Database: the kamailio and asterisk databases, schemas, the Asterisk pool table, carrier addresses, the first organization and seed users. |
50 | Render configs: writes every template into /etc and validates it (kamailio -c, nginx -t) before anything starts. |
60 | AI agent: installs it into /opt/avr with its own Python environment. |
70 | Firewall: ufw (deny incoming, SSH first and rate-limited, then the ports above) and the fail2ban jail for Kamailio. |
80 | Start services in dependency order and wait for each port: MariaDB, rtpengine, every Asterisk instance, the AI agent, nginx, Kamailio. |
85 | Dashboard: Node.js 22, builds the Next.js app, installs dashboard.service, the backup, trunk-sync and trunk-status units, and the recordings and prompts folders. |
90 | Health check: services, listeners, SIP answer, dispatcher, databases, TLS expiry. |
Running part of it again
1sudo ./install.sh --from 50 # from step 50 onwards (re-render configs after editing config.env)2sudo ./install.sh --from 40 # after changing ASTERISK_INSTANCES or carrier settings3sudo ./install.sh --only 50,80 # just these steps4sudo ./install.sh --only 85 # rebuild the dashboard onlyTLS certificates
| Mode | Use it for | Notes |
|---|---|---|
letsencrypt | Production | certbot in standalone mode. DNS must point at PUBLIC_IP and port 80 must be reachable. A renewal hook reloads Kamailio and nginx. |
selfsigned | Test servers | A private CA and server certificate (valid for TLS_DAYS, default 825). Browsers reject the WebSocket until you import /etc/voip-stack/tls/ca.crt into the client's trust store. |
Kamailio reads its certificate from /etc/kamailio/tls/. The health check fails once the certificate has 14 days or less left, so a broken renewal shows up in time.
First run in the browser
After the installer finishes, open https://your-domain/setup. The page exists only while the installation has no operator account, and works once.
Operator account
Your name, email and password. This account manages every organization and the platform settings. Turn on two-factor sign-in right after, under My settings.The product
The name everyone sees, the default time zone, and who uses the installation: the public website with open sign-up (several customer organizations) or only the sign-in page (one company).First organization
Your own company, or your first customer. You become its Admin on extension 1001.Email (optional)
SMTP host, port, user name, password and from address for password resets and invitations. You can add them later under Platform settings.
Unattended installs
Set DASHBOARD_ADMIN_EMAIL (and DASHBOARD_ADMINS, the extension to link, default 1001) in config.env before running the installer. It skips the wizard, creates the operator login with a random password, and writes the details to a root-only file:
sudo cat /etc/voip-stack/dashboard-admin.txtPlatform settings
Everything below is in the dashboard under Platform settings; nothing here needs a terminal.
Product
Product name and logo (PNG or JPEG, up to 1 MB), support email and help link, the default accent colour and time zone, the public website switch and open sign-up. New organizations inherit the time zone; each Admin can change their own under Organization settings.
Outgoing email (SMTP)
Any SMTP server works: your mail provider, Microsoft 365, Google Workspace, Amazon SES or a relay in your data centre. Port 587 with STARTTLS is the usual choice; use 465 with “Implicit TLS” on. Send test email delivers a message to your own address and records the result. Until email works, password resets fall back to Admins setting passwords by hand, and invitations give the Admin a link to copy.
Sign-in rules
How long a signed-in session lasts, the minimum password length (checked wherever a password is set), and whether two-factor sign-in is required for every person on the installation or left to each organization's Admin.
Data retention
Days to keep call recordings, transcripts and AI summaries, voicemail messages and call history. The dashboard's background worker applies the limits to every organization each night after 03:00 and writes one line per run to the audit trail (platform.retention_run). Pick the longest period any of your organizations must keep.
RETENTION_DRY_RUN=1With this line set (then systemctl restart dashboard), the nightly run only counts what it would remove. Use it once before you shorten a period.
This installation
The version, the server, how many phone servers run, and the licence holder. System health is one link away.
Password resets and invitations
Forgot password on the sign-in page sends a one-time link that works for an hour. Invite on an organization's Team page creates the person without a password and sends a link that works for 7 days; they choose their name and password and are signed in straight away. Both links are stored only as hashes, are limited per address, and every request is in the audit trail.
1Subject: You're invited to Sunrise Microfinance Bank on <Product>23Ayesha Khan added you to Sunrise Microfinance Bank's phone system as extension 1004.4Set your password with the button below to start taking calls in the browser.5The link is valid for 7 days.67[ Set up my account ] https://your-domain/invite?token=…Organizations
All organizations lists every tenant with its Admin, numbers, IVRs, queues and call volume. With open sign-up, customers create their own organization at /signup. With sign-up closed, you create the organization's first Admin and invite them. Every organization only ever sees its own people, numbers, calls and settings.
Phones sign in with <organization slug>-<extension> as the SIP user name, for example main-1001. The first organization's slug is ORG_SLUG from config.env.
Numbers and carriers
There are two places a carrier can be connected. Both end up in Kamailio, which is the only part that talks to carriers.
| Where | Who | What it is for |
|---|---|---|
config.env (TELNYX_*) | Platform operator, at install | The installation's own Telnyx trunk, with its numbers in TELNYX_DIDS and DEFAULT_DID_TARGET for numbers you have not mapped. |
| Numbers → Telnyx account | Platform operator, in the dashboard | The shared Telnyx account behind the platform, and which organization each of its numbers belongs to. |
| Numbers → Carriers | Each organization's Admin | The organization's own SIP trunks (Telnyx, any SIP provider, GSM gateway), in register or IP mode. Outgoing calls try them in order. |
Telnyx: IP or credentials
| IP mode (recommended) | Credentials mode | |
|---|---|---|
| config.env | TELNYX_AUTH="ip" | TELNYX_AUTH="credentials" plus TELNYX_USERNAME, TELNYX_PASSWORD |
| Telnyx portal | An IP/FQDN connection with your PUBLIC_IP as inbound and outbound IP | A Credentials connection |
| How it works | Telnyx trusts your IP; Kamailio trusts Telnyx's signalling IPs (TELNYX_SIGNALING_IPS). No password. | Kamailio registers to Telnyx and answers its digest challenge on outbound calls. |
| Both | Codecs PCMU / PCMA, DTMF RFC 2833; assign your numbers to the connection. | Same |
Map a number from the command line
The dashboard is the normal place to route numbers. For the installation-level trunk you can also map one live, without a restart:
1sudo scripts/add-did.sh +15559990000 user:1001 # ring extension 1001, voicemail if no answer2sudo scripts/add-did.sh +15559990001 ivr # the IVR menu3sudo scripts/add-did.sh +15559990002 avr # the AI voice agent4sudo scripts/add-did.sh +15559990003 app:8004 # any 8xxx application (here: conference)Backups
A nightly backup runs at 02:30 (voip-backup.timer, with up to 10 minutes of random delay; a run missed while the server was off happens at the next boot). It writes a dated folder under /var/backups/voip-stack/:
| File | What it holds |
|---|---|
asterisk.sql.gz | The main database: call history, voicemail messages, users, organizations, settings, IVRs, queues. |
kamailio.sql.gz | The SIP proxy database: organization trunks and their registrations. |
recordings.tgz | Call recordings (/var/spool/voip-recordings). |
sounds.tgz | Sound libraries, uploaded hold music and generated IVR prompts (/var/spool/voip-ivr). |
config.tgz | /etc/voip-stack (secrets and config), Asterisk, Kamailio, nginx and rtpengine config, TLS certificates. |
latest.json next to the folders is what the dashboard's System health page shows (time, size, file count, success). Settings live in /etc/voip-stack/backup.env.
1sudo voip-backup # run one now2systemctl list-timers voip-backup.timer # when the next one runs3cat /var/backups/voip-stack/latest.json # result of the last run4sudo rsync -a /var/backups/voip-stack/ backup-host:/srv/voip/ # copy off the serverBACKUP_DIR=/var/backups/voip-stackKEEP_DAYS=14Restore
Restore onto a fresh server with the same Ubuntu release.
Install normally
Runsudo ./install.shwith the sameconfig.env. This creates the services, databases and database users.Stop the services
Shell sudo systemctl stop dashboard asterisk 'voip-asterisk@*' kamailio avrRestore configuration
This brings back the secrets, so the restored databases decrypt.Shell sudo tar -xzf config.tgz -C /Restore the databases
Database names are the ones inconfig.env.Shell zcat asterisk.sql.gz | sudo mysql --defaults-extra-file=/etc/voip-stack/mysql-asterisk.cnf asteriskzcat kamailio.sql.gz | sudo mysql --defaults-extra-file=/etc/voip-stack/mysql-client.cnf kamailioRestore files
Shell 1sudo tar -xzf recordings.tgz -C /2sudo tar -xzf sounds.tgz -C /3sudo chown -R asterisk:asterisk /var/spool/voip-recordings4sudo chown -R dashboard:asterisk /var/spool/voip-ivrStart everything
Shell sudo systemctl start mariadb kamailio asterisk 'voip-asterisk@*' avr dashboard nginxCheck
Open System health, place a test call and play an old recording. Point the DNS name at the new server last, so phones re-register only once.
Upgrades
Copy the new release over the installation folder, keep your config.env, then:
1sudo ./install.sh --only 50 # re-render the phone-server configs2sudo ./install.sh --only 85 # rebuild and restart the dashboard3sudo mysql asterisk < templates/sql/asterisk.sql # database changes; every statement is safe to repeat4sudo bash scripts/migrate-tenants.sh # safe to re-run; only touches rows in the old format5 6# reload every Asterisk instance without dropping calls7sudo bash -c 'source scripts/lib.sh && load_config && ast_each_cli "core reload"'Services and logs
| Unit | Role | Logs |
|---|---|---|
asterisk, voip-asterisk@2 … | Phone servers, one unit per instance | /var/log/asterisk*/messages.log |
kamailio | SIP proxy: phones register here, browser phone over WSS | /var/log/kamailio/kamailio.log |
rtpengine-daemon | Media relay (SRTP for browsers) | journalctl -u rtpengine-daemon |
avr | AI voice agent | /var/log/avr/avr.log |
dashboard | The web dashboard and its background worker | journalctl -u dashboard |
nginx | TLS, the dashboard and the browser phone socket | /var/log/nginx/ |
mariadb | Database | journalctl -u mariadb |
voip-backup.timer | Nightly backup | journalctl -u voip-backup |
voip-trunk-status.timer | Refreshes trunk registration state for the dashboard every 30 seconds | journalctl -u voip-trunk-status |
voip-sync.path | Reloads organization trunks into Kamailio when an Admin changes them | journalctl -u voip-sync |
1systemctl status kamailio asterisk rtpengine-daemon avr dashboard mariadb nginx --no-pager2journalctl -u dashboard -n 200 --no-pager # last 200 lines of a service3journalctl -u kamailio -f # follow live4sudo asterisk -rx "pjsip show contacts" # who is signed in (shared by all instances)5sudo asterisk -rvvv # Asterisk console6sudo kamcmd dispatcher.list # the Asterisk pool and its state7sudo kamcmd htable.dump ipban # addresses Kamailio has bannedHealth checks
System health in the dashboard shows services, phones, calls, disk and backups and refreshes every 30 seconds. On the server, the health check script tests the whole stack and exits with 0 when everything passes, so it is safe to run from cron or your monitoring system.
sudo scripts/healthcheck.sh # PASS / FAIL per checksudo scripts/healthcheck.sh -v # with details on failures- services: MariaDB, rtpengine, every Asterisk instance, Kamailio, the AI agent.
- listeners: SIP UDP/TCP/TLS, WSS, each Asterisk port, rtpengine control, the AI agent; and that no internal port is open on all interfaces.
- signalling: Kamailio answers a SIP OPTIONS; the dispatcher has every local Asterisk instance active.
- asterisk: endpoints loaded from the database, ODBC connected, AudioSocket module loaded, number of registered contacts.
- media, database, TLS, carrier: rtpengine answers a ping, both databases answer, the certificate has more than 14 days left, the Telnyx registration in credentials mode.
Test calls from the command line
1python3 scripts/selftest.py echo --host DOMAIN --ext 1001 --pw PASS # register + echo2python3 scripts/selftest.py avr --host DOMAIN --ext 1001 --pw PASS # AI agent3python3 scripts/selftest.py ext2ext --host DOMAIN --ext 1001 --pw P1 --ext2 1002 --pw2 P24python3 scripts/selftest.py call --host DOMAIN --ext 1001 --pw PASS --to +155512300005python3 scripts/wss_test.py --url wss://DOMAIN:4443 --domain DOMAIN --ext 1001 --pw PASS --ca /etc/voip-stack/tls/ca.crtTroubleshooting
| Symptom | Check |
|---|---|
| Browser registers but the call has no audio | UDP 30000–40000 open in the cloud firewall? PUBLIC_IP and PRIVATE_IP right? DTLS errors in the rtpengine log? |
| WebSocket fails in the browser | Self-signed CA not trusted, or the DNS name does not match the certificate. Test with scripts/wss_test.py. |
| Outbound call refused with 403 | The number matches PSTN_BLOCK_REGEX. |
| Outbound call refused with 503 Too Many Calls | The extension hit OUTBOUND_MAX_PER_MIN. |
| Inbound carrier calls ignored | Source IP not in TELNYX_SIGNALING_IPS, the number is not mapped (unmapped numbers use DEFAULT_DID_TARGET), or your IP is not whitelisted at the carrier. |
| Every call or registration gets 401 again and again | An authenticated request reached a different Asterisk instance than the one that issued the challenge. Keep the default dispatcher algorithms. |
| Dispatcher shows an instance inactive | The instance is down, or its SIP port differs from the dispatcher row. A 401 reply to the probe counts as alive. |
| Registered, but calls to the phone never arrive | The phone must register through Kamailio's address, not directly to Asterisk, so the stored contact has its Path. |
| One-way audio from a phone behind NAT | Turn off SIP ALG on the phone's router. |
| AI agent silent | journalctl -u avr; with no API keys it plays test tones instead of speaking. |
| A phone or office suddenly cannot reach the server | Kamailio may have banned its address after failed passwords or a flood: kamcmd htable.dump ipban. |
Command-line helpers
The dashboard covers daily work, but these scripts in scripts/ are useful for automation and recovery. Run them as root from the installation folder.
| Script | Does |
|---|---|
add-user.sh [--org slug] ext password [pin] | Add or update an extension (3–6 digits, first digit 1–7). Live on every Asterisk instance at once; no reload. |
del-user.sh [--org slug] ext | Remove an extension: endpoint, auth, contacts, mailbox and dashboard login. |
add-login.sh [--org slug] [--platform] email ext [role] [password] | Create or update a dashboard login linked to an extension. Role admin, supervisor or user; without a password one is generated and printed. |
add-did.sh number target | Map an inbound number on the installation trunk to avr, ivr, user:EXT or app:8xxx. |
healthcheck.sh [-v] | The health check above. |
backup.sh | The nightly backup, installed as /usr/local/sbin/voip-backup. |
migrate-tenants.sh | One-time upgrade of a single-company install to organizations. |
channel-test.sh url [from] [text] | Send a test message into a generic messaging channel. |
selftest.py · wss_test.py · webrtc_call.py | Call tests over SIP, WebSocket and WebRTC. |
sudo scripts/add-user.sh --org main 1010 'a-long-sip-password' 4321sudo scripts/add-login.sh --org main sara@example.com 1010 supervisor