Installation Wizard
A walkthrough of the four installer steps, from system check to the completion screen.
The Astervis installer is interactive. Once you run it, it walks you through four numbered steps — System Check → License → Configuration → Installation — and does the heavy lifting in the last one. Most of the work is automatic; you only answer a handful of questions about your admin account, your domain, and (rarely) your MySQL credentials.
This page walks through each step so you know exactly what to expect, what the installer is checking, and what the choices mean.
Run the installer as root, on the PBX server itself. Astervis is on-premise only — everything installs locally next to your Asterisk/FreePBX, and all call data stays on this machine. If you haven't downloaded the binary yet, see Installation.
You can start the wizard cold and let it prompt for the license:
sudo astervis-installer installOr pass the key up front to skip the second step's prompt:
sudo astervis-installer install --license YOUR_LICENSE_KEYIf an install is ever interrupted, every step is checkpointed in
/opt/astervis/.install-state.json, so you can pick up where you left off:
sudo astervis-installer install --resumeStep 1/4 — System Check
The first step is read-only: the installer inspects your server and decides whether it can proceed. It detects your OS and CPU architecture, measures RAM, CPU cores and free disk, looks for a PBX, finds your MySQL/MariaDB CDR database, reads your network configuration and timezone, and checks for Docker and internet access.
Results are printed as a requirements table with a ✓ or ✗ next to each line. If any hard requirement fails, the install aborts here — nothing is changed on your system. "Recommended" values that aren't met surface as non-blocking warnings.
[1/4] System Check
═══════════════════════════════════════════════════════
OS Ubuntu 22.04 LTS ✓
Arch amd64 ✓
CPU 4 cores ✓
RAM 7.6 GB ✓
Disk (docker) 41 GB free ✓
PBX FreePBX (Asterisk 18) ✓
MySQL CDR asteriskcdrdb @ localhost:3306 ✓
Docker 28.1.1 ✓
Internet reachable ✓
All requirements met. Continuing…What must pass
| Requirement | Minimum (hard) | Recommended | Notes |
|---|---|---|---|
| RAM | 2 GB | 4 GB | The whole stack runs at roughly 0.6 GB RSS at rest thanks to litcdc. |
| CPU | 1 core | 2 cores | On a single core the historical CDR backfill is slower. |
| Free disk | 15 GB | — | Checked on the Docker data-root partition, not /. Images are ~8 GB plus runtime headroom. |
| OS | Ubuntu / Debian / CentOS / RHEL / Sangoma / FreeBSD | — | Anything else aborts. |
| PBX | Asterisk / FreePBX / Sangoma / Issabel / VitalPBX / Elastix | — | Required — install errors out with "No PBX system detected" if none is found. |
| Internet | Required | — | Needed to pull images and reach the AI gateway. |
| Docker | Required | — | Installed automatically in Step 4 if missing. |
The disk check looks at the partition Docker actually writes to (from
docker info → DockerRootDir, else /var/lib/docker), not /. On
Sangoma appliances the LVM preset often puts /var on a small separate volume,
so a box that looks roomy on / can still fail this check.
Most detection is silent and correct. Two things worth knowing:
- MySQL credentials are auto-detected from your PBX config (e.g.
/etc/freepbx.conf). If they can't be found, the wizard simply asks for them in Step 3 — it never blocks here. - Docker isn't required to be present yet. If it's missing, the installer notes it and installs it for you during Step 4.
Step 2/4 — License Validation
Next the installer needs your license key. If you passed --license, this step is
already done and just confirms; otherwise you'll be prompted to paste it.
A valid Astervis license key starts with AST- — for
example AST-XXXX-XXXX-XXXX-XXXX…. The installer validates the format locally first, then
checks it against https://api.astervis.io, sending your server's detected IP
addresses so the license can be bound to this machine.
[2/4] License
═══════════════════════════════════════════════════════
Enter license key: ast-7f3a9c2e:b81d04...
Validating against api.astervis.io… ✓
Company Acme Call Center LLC
License Type Professional
Valid Until 2027-06-13
License valid. Continuing…On success the installer shows your Company, License Type, and Valid Until date, then moves on.
License validation needs outbound internet to api.astervis.io. If the key is
rejected, the most common causes are a typo (every character matters, don't drop it) or a firewall blocking outbound HTTPS. Legacy keys beginning with asp-
are still accepted, but new keys use the AST- prefix.
Step 3/4 — Configuration
Now the installer collects the few settings it can't infer. Each prompt comes with a smart default drawn from Step 1's detection, so for a typical FreePBX box you can press Enter through most of it.
Admin credentials
Choose the username and password for your first Astervis admin account. The username
defaults to admin. The password must be at least 8 characters and contain an
uppercase letter, a lowercase letter, and a number. The installer generates a
strong 12-character password and offers it as the placeholder — press Enter to accept
it, and it'll be shown again on the completion screen.
Admin username [admin]:
Admin password [Xk9!mPq2vR7t]:Domain & SSL
This is the one choice worth thinking about, because it determines how you'll reach the dashboard and what certificate secures it. The installer presents a menu. If it detected a domain already bound on this host with a valid certificate, that appears first.
If your server already serves a domain over HTTPS — via certbot, an Apache/httpd
vhost, or FreePBX's certificate manager — the wizard offers to reuse it. It
copies the existing certificate and key into Astervis and sets up a daily
astervis-cert-sync.timer so that whenever your own renewal runs, Astervis picks up
the fresh cert automatically. This is the smoothest path when it's available: no new
DNS, no new certificate, an already-trusted domain.
How should Astervis be reached?
> Use detected domain pbx.acme.com — existing SSL until 2026-09-01 (DNS ✓)
Free *.web.astervis.io subdomain
Custom domain
IP onlyWhichever path you choose, if certificate issuance can't complete the installer falls back to a self-signed certificate so the install still succeeds. You can switch to a real certificate later. See SSL configuration for the full decision tree.
MySQL credentials
You'll only see these prompts if Step 1 couldn't auto-detect your CDR database. When it can (the usual case on FreePBX/Sangoma), the installer fills them in silently. The defaults match a standard FreePBX layout:
MySQL host [localhost]:
MySQL port [3306]:
MySQL database [asteriskcdrdb]:
MySQL user [freepbxuser]:
MySQL password [********]:These credentials are used by the CDC pipeline to read your call records — the installer configures the database access it needs in Step 4.
Step 4/4 — Installation
With every answer in hand, the installer does the actual work. This step runs a
fixed, checkpointed sequence — each item is recorded in
.install-state.json, which is what makes --resume possible after an interruption.
On a typical server it takes a few minutes, dominated by pulling images and the
initial CDR snapshot.
The steps run in this order:
Create directories
Lays out /opt/astervis/... — data directories, SSL folder, uploads, and backups.
Generate configuration
Renders .env, docker-compose.yml, and nginx.conf from templates, with secrets
generated fresh for this server.
Install Docker
Installs Docker if it wasn't already present, and makes sure the daemon is running.
Verify Docker Compose
Confirms a usable Compose is available — the v2 plugin (docker compose) is
preferred, legacy v1 (docker-compose) is also accepted.
Pull Docker images
Downloads the Astervis service images. This is usually the longest step.
Generate SSL certificates
Issues or copies the certificate based on your Step 3 choice and writes it to
/opt/astervis/nginx/ssl/.
Configure MySQL for CDC
Enables binary logging (server-id, log_bin, binlog_format=ROW,
binlog_row_image=FULL), sets bind-address=0.0.0.0, grants the CDC user the
permissions it needs, and opens the firewall so containers can reach MySQL.
Configure ARI
Sets up the Asterisk REST Interface credentials Astervis uses for live call control.
Install the Astervis Agent
Installs the local management agent before the backend starts, so the agent's API key matches what the backend expects.
Start services
Brings the stack up with docker compose up. If startup hits a known on-prem
networking snag, the installer auto-remediates and retries.
Run health checks
Waits for TimescaleDB, Redis, the backend, and the rest of the stack to report healthy.
Create the admin user
Creates the admin account from Step 3 and caches the RBAC roles in Redis.
Install the systemd service
Registers astervis.service so the stack starts automatically on boot.
Enable Docker live-restore
Turns on Docker live-restore on all platforms (and installs a firewall watchdog on Sangoma) so containers survive a daemon restart.
Import operators
Imports your operators from the Asterisk MySQL database.
Start CDC (litcdc)
Waits for the litcdc container to come up. litcdc is the lightweight Rust CDC
service that takes a consistent snapshot of your cdr table and then streams new
records in realtime into TimescaleDB.
A successful run looks roughly like this:
[4/4] Installation
═══════════════════════════════════════════════════════
Creating directories… ✓
Generating configuration… ✓
Verifying Docker… ✓
Pulling images… ✓
Generating SSL certificate… ✓
Configuring MySQL for CDC… ✓
Configuring ARI… ✓
Installing Astervis Agent… ✓
Starting services… ✓
Running health checks… ✓
Creating admin user… ✓
Installing systemd service… ✓
Importing operators… 42 imported ✓
Starting CDC (litcdc)… ✓
Logs: /opt/astervis/logs/install-20260613-141902.loglitcdc replaced the older Debezium + Redpanda pipeline, which is why the whole
stack now fits comfortably in 2 GB of RAM. Its durable on-disk buffer lives under
/opt/astervis/litcdc_data, so it never re-snapshots after a restart. See
CDC & data sync for details.
Files written
After Step 4, your install directory looks like this:
Completion
When the last step finishes, the installer prints a summary with everything you need to log in. Save it somewhere safe — the admin password is shown here.
═══════════════════════════════════════════════════════
Astervis is installed and running.
═══════════════════════════════════════════════════════
Dashboard https://acme.web.astervis.io:8443
Admin login admin
Password Xk9!mPq2vR7t
Agent API http://127.0.0.1:9876
API key astv_••••••••••••••••••••••••3f1c
Next: open the dashboard and sign in.The dashboard URL always uses port 8443 — that's the single externally
exposed port; every other service binds to 127.0.0.1. Open it in a browser, sign in
with your admin credentials, and you're in.
The Agent API is the local management endpoint (the installer's serve mode) used
for license polling and in-product updates. The masked key is shown for reference; the
full key lives in /opt/astervis/.env.
That's it. From here, head to Post-installation to verify the services and finish setup, or jump straight into AI Call Analytics to start transcribing and scoring calls.
Common questions
Next steps
Last updated on