astergui

An optional, removable web management layer for a vanilla Asterisk 22 installation. Asterisk stays the PBX; astergui only generates include files under /etc/asterisk/webgui/, reloads the affected subsystems safely, and reads live state over AMI. Stop or remove the GUI and the PBX keeps running with the last generated configuration.

License: AGPL-3.0-or-later. Status: Milestone 3 (parts 1-4) - phone features (voicemail listening, do-not-disturb, call forwarding, setup sheets), web phone (JsSIP softphone in the browser), network capture (pcap) for troubleshooting, call flow (time conditions, IVR menus, queues with music on hold, call recording, pickup), login with roles, dashboard, extensions (network ACL, SRTP), SIP trunks, inbound/outbound routes with failover, ring groups, voicemail overview, call history + CSV export, live calls (hang up, click-to-call), SIP over TLS, users and sessions, backups/restore, security overview, audit log, diagnostics; safe apply with rollback. See docs/operations.md.

Architecture in short

Browser -HTTPS-> nginx -unix socket-> FastAPI (user: astergui) --> PostgreSQL (peer auth)
                                          |  \--> Asterisk AMI (127.0.0.1, read-only style user)
                                          |
                                          \--> stages files --unix socket--> root helper --> /etc/asterisk/webgui/
                                                                                     \--> asterisk -rx "<x> reload"

• The web service never writes to /etc/asterisk. A tiny root-owned helper (packaging/helper/astergui-helper, stdlib only, socket-activated by systemd) validates, snapshots, atomically deploys, reloads, verifies and automatically rolls back if Asterisk rejects the config. The database change is committed only if the deploy succeeded.
• SIP passwords are stored only as PJSIP md5_cred digests; the plaintext is shown once.
• Voicemail PINs are encrypted at rest and never returned by the API.

See docs/ for details (architecture, Asterisk integration, security).

Install (Ubuntu, Asterisk already running)

cd frontend && npm ci && npm run build && cd ..   # build the UI once (no Node needed on the server)
sudo bash scripts/install.sh                      # app, database, services, nginx, TLS
sudo astergui asterisk install --dry-run          # show exactly what changes in /etc/asterisk
sudo astergui asterisk install                    # hook into Asterisk (backups are taken first)
sudo astergui admin create <username>             # first administrator (no default password)

Dev loop: scripts/deploy-dev.sh user@host copies the tree to a test VM and runs the installer.

Configuration ownership

Everything in /etc/asterisk/webgui/ is owned by astergui and overwritten on apply. Everything else in /etc/asterisk is yours. The installer only appends a clearly marked #include block to pjsip.conf, extensions.conf, voicemail.conf, manager.conf, cdr_pgsql.conf (and switches AMI on, bound to 127.0.0.1).

How it works with Asterisk

Asterisk stays the PBX. astergui adds three things around it:

1. Config generation. Everything you create in the UI (extensions, trunks, routes, IVRs, queues, ...) is stored in PostgreSQL and rendered into deterministic files in /etc/asterisk/webgui/. astergui asterisk install (run once) adds small marked #include blocks to the normal config files so Asterisk loads those files.
2. Safe applying. Every change is validated, the current state is backed up, files are replaced atomically, only the affected subsystem is reloaded (pjsip reload, dialplan reload, ... never a blind restart), and the expected objects are checked in Asterisk. On any failure the previous state is restored automatically. A small root helper does the privileged part, so the web service itself has no root access.
3. Live state and history. Registrations, calls and queue state come from Asterisk over AMI (localhost only). Call history comes from cdr_pgsql, which writes into the same database.

If astergui is stopped or removed, Asterisk keeps running from the files already on disk.

If you change Asterisk yourself

You change	What happens
Files in /etc/asterisk/ outside webgui/ (own trunks, contexts, dialplan, ...)	astergui neither reads nor overwrites them. They keep working next to the generated config but do not appear in the UI. There is no import of existing config: recreate it in astergui if you want it managed.
Files inside /etc/asterisk/webgui/	Don't. The database is the source of truth; the next apply regenerates the files and overwrites your edit.
Runtime changes via the Asterisk CLI (pjsip ..., dialplan ...)	Affect the running system only, are lost on reload/restart, and astergui does not record them. Live state (calls, registrations) is still visible through AMI.
Objects with the same name as astergui's (endpoint IDs of managed extensions, wg-* contexts)	Avoid: the result is undefined. All astergui dialplan contexts start with wg-.

What the astergui command-line tool is for

It covers what the web UI should not or cannot do: setup, recovery and operations. Run it on the server, usually with sudo.

Command	Purpose
admin create / list / reset-password	Create the first administrator and recover a lost password (there is no default login).
db upgrade	Run database migrations.
asterisk install / uninstall / status	Add or remove the include hooks in /etc/asterisk (dry-run and backups first).
config render / validate / diff / apply / rollback	The same render/apply/rollback as the UI, from a shell: inspect what would change, or recover when the UI is unreachable.
tls sip-cert / web-cert	Install SIP or web TLS certificates.
web http enable / disable / status	The optional plain-HTTP listener.
backup create / list / restore	Backups of the database and generated config.
upgrade, diagnostics	Post-upgrade steps; a health and config report for bug reports.

Uninstall the GUI without touching Asterisk's operation

sudo astergui asterisk uninstall --dry-run   # removes only the marker blocks (GUI-managed phones disappear)

Or simply stop the services (systemctl disable --now astergui.socket astergui-helper.socket): Asterisk keeps running with the last deployed configuration.

Useful commands

astergui config diff | render | validate | apply | rollback, astergui asterisk status, astergui diagnostics.