Skip to content
ankaios76Public

About

VstPBX: web interface for the Asterisk PBX. Extensions, SIP trunks, routing, voicemail, IVR and a live dashboard in one Docker stack.

Topics

Resources

Stars

19 stars

Watchers

0 watching

Forks

Repository files navigation

VstPBX

A web interface for the Asterisk PBX.
Extensions, SIP trunks, call routing, voicemail, IVR and live monitoring in one self-hosted Docker stack.

Live demo · Installation · Installationsanleitung (Deutsch) · Features · Screenshots · Changelog

MIT license


VstPBX (Vst is the German abbreviation for Vermittlungsstelle, "telephone exchange") turns Asterisk into something you can run without editing config files. You manage extensions, trunks, inbound numbers, ring groups and menus in the browser. VstPBX writes the PJSIP configuration and dialplan for you and reloads Asterisk.

Try it: vst-demo.frickelfabrik.de, log in as demo with the password vst-demo. The demo uses made-up data and resets every 30 minutes. Telephony is switched off there, so you can set everything up but not place calls.

It started as GonoPBX, was called VST for a few days, and is now VstPBX. The code base is the same project; see the changelog for the history. VstPBX has nothing to do with the VST audio plugin format by Steinberg.

VstPBX dashboard

Features

  • Extensions: SIP extensions with caller ID, codecs, call forwarding (always, busy, no answer), BLF hints and pickup groups
  • SIP trunks: registration or IP authentication, ready-made profiles for Plusnet IPfonie, dus.net, Telekom DeutschlandLAN, CompanyFlex and All-IP residential lines, Iliad (Italy), and a generic custom trunk
  • Inbound routing (DIDs): assign inbound numbers to extensions; ring groups and IVR menus get their own inbound numbers; number blocks per trunk
  • Outbound caller ID: choose the DID shown per extension; optional P-Asserted-Identity header
  • Ring groups, IVR menus (multi-level, prompt upload with conversion) and voicemail with PIN, e-mail delivery (HTML) and an in-browser player
  • Phonebook: global and per-extension, CSV import and export
  • Live dashboard over WebSocket: Asterisk status, registered phones, active calls, recent calls
  • Call detail records with filters and statistics
  • SIP debug: live SIP message viewer grouped by call, with the raw message
  • Security: IP allow-list for SIP registration, password-strength checks, audit log of every administrative action, Fail2Ban status, JWT login with admin and user roles
  • Home Assistant: API key, click-to-call and MQTT events (gonopbx/... topics, see Compatibility)
  • German and English interface, chosen at install time; dark mode
  • One-click update from the web interface, or ./install.sh again on the command line

Screenshots

Extensions Trunk and inbound numbers
Extensions Trunk
Call history Security settings
Call history Security
Dark mode Login
Dark mode Login

Quick start

You need a Linux machine with Docker Engine 24+ and the Compose plugin, a few GB of free disk space, and (for real calls) a SIP provider account.

git clone https://github.com/ankaios76/vstpbx.git
cd vstpbx
sudo ./install.sh

The installer asks a handful of questions (network mode, language, SIP port, admin password), generates all secrets, builds the images and starts the stack. Afterwards open http://<server-ip>:3000 and log in as admin.

The full walkthrough, including router and firewall settings, a first trunk and extension, backups and troubleshooting, is in docs/INSTALLATION.md (English) and docs/INSTALLATION.de.md (German).

How it fits together

 phones / softphones ──SIP/RTP──▶ ┌────────────┐      AMI      ┌────────────┐
 SIP provider ◀──────SIP/RTP───── │  Asterisk  │◀────────────▶│  Backend   │──▶ PostgreSQL
                                  │  (PJSIP)   │  config files │  (FastAPI) │
                                  └────────────┘◀──────────────└─────┬──────┘
                                                                      │ REST + WebSocket
                                                              ┌───────▼──────┐
                                              browser ───────▶│   Frontend   │
                                                              │ (React/nginx)│
                                                              └──────────────┘
Component Technology
PBX engine Asterisk 20 (PJSIP)
Backend FastAPI (Python), SQLAlchemy, Panoramisk/AMI
Frontend React, TypeScript, Vite, Tailwind CSS
Database PostgreSQL 15
Auth JWT, bcrypt
Deployment Docker Compose, four containers

The backend is the source of truth. It renders pjsip_peers.conf, the dialplan, voicemail and queue configuration from the database into asterisk/config/ and asks Asterisk to reload. Do not edit the generated files by hand; changes are overwritten.

Security notes

Read these before exposing VstPBX to the internet.

  • The web interface speaks plain HTTP on port 3000. Put it behind a TLS reverse proxy (Caddy, nginx, Traefik) or reach it only over a VPN, and choose "reverse proxy" in the installer so that ports 3000 and 8000 bind to localhost.
  • SIP on the open internet gets scanned constantly. Use strong extension passwords (the interface has a generator), the IP allow-list, and Fail2Ban on the host. Prefer a VPN for remote phones.
  • The backend container mounts the Docker socket. VstPBX needs it to reload Asterisk after every change (it runs asterisk -rx reload inside the Asterisk container) and for one-click updates. That is equivalent to root on the host for anyone who can run code in that container, so never expose port 8000 to untrusted networks and keep the web interface behind a VPN or a TLS proxy. Removing the mount makes the interface work but Asterisk no longer picks up changes automatically; you would have to restart the pbx_asterisk container yourself after each change.
  • There is no default password. The installer generates one (or asks for yours) and stores it in .env; keep that file private.

Compatibility notes

Some internal names keep the GonoPBX spelling so that existing installations and integrations keep working after the rename:

  • MQTT topics start with gonopbx/ and the Home Assistant call events use gonopbx_call:
  • internal e-mail placeholders end in @gonopbx.local
  • the update container is called gonopbx-updater

Updating

From the web interface: Settings → Server → Update. From the command line:

cd vstpbx
git pull
sudo ./install.sh      # choose [1] Update: keeps data and passwords

Database migrations run automatically when the backend starts.

Project layout

vstpbx/
├── asterisk/            Dockerfile, sound prompts, music on hold, config templates
├── backend/             FastAPI application, config generators, AMI client
├── frontend/            React application (Vite, Tailwind)
├── docs/                Installation guides and screenshots
├── releases/            Release notes per version
├── docker-compose.yml
├── install.sh           Interactive installer and updater
└── CHANGELOG.md

Contributing

Bug reports and ideas are welcome as issues. Pull requests too; please describe what you changed and how you tested it.

License

MIT, see LICENSE. Asterisk itself, the bundled sound prompts and the music on hold files have their own licences.

Credits

Written by Norbert Hengsteler in Bremen. VstPBX builds on Asterisk, a project of Sangoma Technologies. The bundled English prompts are the Asterisk core sounds, and the music on hold files keep their original licences (see asterisk/moh/).

About

VstPBX: web interface for the Asterisk PBX. Extensions, SIP trunks, routing, voicemail, IVR and a live dashboard in one Docker stack.

Topics

Resources

Stars

19 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages