Installation
Install Astervis on your Asterisk or FreePBX server in minutes.
Astervis installs with a single command, right on the server that already runs your PBX. A guided wizard handles everything else — Docker, the database, TLS certificates, MySQL change-data-capture, and every service — so a first install typically takes a few minutes of mostly pressing Enter. Astervis is on-premise only: all of your call records and recordings stay on your own server.
You'll need a license key. It starts with AST- — e.g.
AST-XXXX-XXXX-XXXX-XXXX.... Copy the install command with your key already filled in from
your account dashboard, or pass the key on the command line below.
Before you start
The wizard checks all of this for you in Step 1 and stops if a hard requirement isn't met, but it helps to know the floor up front:
| Requirement | Minimum | Recommended |
|---|---|---|
| RAM | 2 GB | 4 GB |
| CPU | 1 core | 2 cores |
| Free disk | 15 GB (on the Docker data partition) | — |
| OS | Ubuntu, Debian, CentOS, RHEL, Sangoma Linux, FreeBSD | — |
| PBX | Asterisk / FreePBX / Sangoma / Issabel / VitalPBX / Elastix | — |
| Internet | Required (to pull images and reach the AI gateway) | — |
You must run the installer as root, and a working PBX must be present — the install
aborts with No PBX system detected if it can't find one. Docker is installed
automatically if it's missing. The disk check looks at the Docker data-root partition
(not /), which matters on Sangoma appliances that put /var on a small LVM volume.
Install in one line
The install runs in two stages: a small bootstrap script downloads the
astervis-installer binary, then the binary runs the interactive wizard. Run this
as root on your PBX server.
Downloads the installer and chains straight into the wizard:
curl -fsSL https://api.astervis.io/api/releases/install.sh | bash -s -- --license YOUR_LICENSE_KEYThe bootstrap needs curl or wget, detects your OS and architecture
(linux/freebsd, amd64/arm64), and drops the binary at
/usr/local/bin/astervis-installer. Anything else aborts with a clear error.
What the installer sets up for you
You don't have to prepare any of this in advance. The installer detects what's already present and configures only what's missing:
Docker & Compose
Installs the Docker engine and Compose v2 if they aren't there, and enables live-restore so your containers survive a daemon restart.
TimescaleDB + Redis
Brings up PostgreSQL 16 with TimescaleDB and pgvector as your analytics store, plus Redis for sessions and the job queue.
TLS certificates
Picks the best certificate path for your host — an existing host cert, a free *.web.astervis.io subdomain, or Let's Encrypt — and wires it into nginx.
MySQL change-data-capture
Configures the Asterisk MariaDB binlog, grants the CDC user, and starts litcdc to replicate every CDR into TimescaleDB in real time.
Services & autostart
Starts all containers, runs health checks, creates your admin user, and registers a systemd unit so Astervis starts on boot.
PBX integration
Detects FreePBX / Sangoma / Asterisk, configures the ARI interface, and imports your existing operators.
Change-data-capture is handled by litcdc, a single lightweight Rust binary (~10–25 MiB RSS). It reads the Asterisk MySQL binlog, takes a one-time consistent snapshot of your historical CDRs, then streams new calls into TimescaleDB. There's no Kafka, no message broker, and nothing extra for you to operate. (litcdc replaced the old Debezium + Redpanda pipeline, which is why the RAM minimum is now just 2 GB.)
Behind the scenes the installer also configures your MariaDB for CDC — it sets
server-id=1, binlog_format=ROW, binlog_row_image=FULL, expire_logs_days=3, and
bind-address=0.0.0.0, then grants the CDC user RELOAD, LOCK TABLES, SHOW DATABASES, REPLICATION CLIENT, REPLICATION SLAVE. LOCK TABLES is what lets the initial snapshot
take a consistent FLUSH TABLES WITH READ LOCK. The original MySQL config is backed up
before any change.
The 4-step wizard at a glance
Once the binary launches, the wizard walks you through four phases shown as "Step N/4". It pre-fills smart defaults from what it detected, so most prompts are a single keystroke.
System Check
Runs full detection — platform, RAM, CPU, free disk, PBX, MySQL, network, Docker, internet — and renders a pass/fail requirements table. If a hard requirement isn't met, the install stops here.
License Validation
Validates your AST- key against api.astervis.io using the server's detected
IPs, then shows your company, license type, and expiry. You're prompted for the key
here if you didn't pass --license.
Configuration
Collects your admin username and password, your domain and SSL choice, and — only if it couldn't auto-detect them — your MySQL CDR credentials.
Installation
Creates directories, generates config, pulls images, issues certificates, configures CDC, starts every service, runs health checks, and creates your admin user. Every step is checkpointed so it can be resumed.
Download manually or resume an interrupted install
The installer checkpoints its progress in /opt/astervis/.install-state.json, so an
interrupted run — a dropped connection, a reboot mid-pull — picks up where it left off
instead of starting over.
sudo astervis-installer install --resumeAfter the install
When the wizard finishes, it prints your access URL, your admin login, and the agent API key. Open the dashboard in a browser:
https://<your-server>:8443Port 8443 is the only port Astervis exposes to the outside world — every other
service binds to 127.0.0.1. If you chose the self-signed certificate, your browser
will warn you on first visit; accept it and sign in with the credentials shown at the
end of the install.
Command reference
Manage your installation with the same binary. Every command runs as root.
| Command | What it does |
|---|---|
sudo astervis-installer status | Shows each service with its container status and health. |
sudo astervis-installer logs | Streams logs from the running containers. |
sudo astervis-installer start / stop / restart | Controls the running stack (and the license agent alongside it). |
sudo astervis-installer upgrade | Self-updates the installer binary to the latest release. |
sudo astervis-installer uninstall | Tears the install down completely (see below). |
Last updated on