Install with apt (one command)

The monopbx Debian package is the quickest way to run MonoPbx on a fresh Ubuntu 24.04 LTS (amd64) server. It installs Docker from Ubuntu's own packages, the production Compose bundle and a monopbx command, and runs everything as the systemd service monopbx.service. Caddy in front gets a Let's Encrypt certificate, serves the console on HTTPS and carries the web softphone's SIP WebSocket on wss://<your domain>/sip.

:::note Preview The repository carries preview builds (0.1.0~edge…) until the first release is tagged. Other systems (Ubuntu 22.04, Debian 12, arm64) are refused with a clear message and nothing is changed. :::

One command

Point a DNS name at the server first (an A record), then:

curl -fsSL https://ilinaya.github.io/monopbx-apt/install.sh | sudo bash -s -- --domain pbx.example.com --email admin@example.com

The script checks the system, adds the MonoPbx APT repository and verifies its signing key (fingerprint 320D C78E FDC8 439C 04F5 FCA6 3E87 FE3D 4C71 5372), runs apt-get install monopbx, then monopbx setup with your options. Without --domain the server is named <public-ip>.sslip.io (a public DNS service that answers with the address written in the name), so a certificate works without your own domain. With --email you accept the Let's Encrypt Subscriber Agreement; the address receives expiry notices.

Or step by step with apt

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://ilinaya.github.io/monopbx-apt/key.gpg | sudo tee /etc/apt/keyrings/monopbx.gpg >/dev/null
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/monopbx.gpg] https://ilinaya.github.io/monopbx-apt stable main" | sudo tee /etc/apt/sources.list.d/monopbx.list
sudo apt-get update && sudo apt-get install -y monopbx
sudo monopbx setup --domain pbx.example.com --email admin@example.com

What setup does

Step	Detail
Preflight	Ubuntu 24.04, 2 CPUs, 4 GB RAM, 20 GiB free under /var/lib, ports 80 and 443 free, the public IP, DNS of the domain.
Secrets	mpbx init writes every secret into /opt/mpbx/compose/prod/.env (mode 0600, a copy in /etc/mpbx/secrets.env). The recovery key is shown once: on a terminal you re-type one group of it; without a terminal it is printed once, so capture the output safely.
Front	Caddy on 80/443: the certificate (Let's Encrypt, renewed by Caddy), the console, and wss://<domain>/sip to the SIP edge.
SIP	5060 UDP/TCP and SIP over TLS on 5061. The TLS certificate comes from the PBX certificate store, which orders its own Let's Encrypt certificate for the same name through Caddy and renews it automatically.
Firewall	When ufw is active, opens 80/tcp, 443/tcp, 5060, 5061/tcp and the RTP range. Open the same ports in your cloud firewall.
Service	monopbx.service (an alias of mpbx.service), started and enabled; then the self-test.
Summary	The console URL, the single-use setup link for the first administrator, and the recovery key.

Open the setup link (https://<domain>/setup#token=…) to create the first administrator: e-mail, password, then the TOTP second factor (scan the QR code with an authenticator app). Lost the link? sudo monopbx setup-url issues a new one.

Options

--domain FQDN       public name; its A record must point at this server (default: <public-ip>.sslip.io)
--email ADDRESS     Let's Encrypt contact; required unless --no-tls
--no-tls            no public certificate: Caddy uses its own internal CA (browsers warn). For tests and closed networks
--public-ip IP      skip the public-IP lookup (behind NAT, name the address phones reach)
--relay URL         the push relay for mobile apps (default: the MonoPbx relay)
--no-relay          do not enroll with a push relay (mobile apps ring only in the foreground)
--turn              run coturn for softphones behind strict NAT
--yes               do not ask "Continue?"

Any other install.sh option of the VM installer can follow --, for example -- --calls 500.

Day-to-day commands

monopbx status                  # version, service, containers
monopbx logs mpbx               # follow one service (mpbx, mpbx-sip, caddy, postgres, ...)
sudo monopbx selftest           # containers, HTTPS through Caddy, wss /sip, SIP TLS 5061, mpbx selftest
sudo monopbx backup             # pg_dump into /var/backups/monopbx (0600); --with-secrets also copies .env
sudo monopbx setup-url          # a new first-administrator link
sudo monopbx ctl rollback       # any mpbx-ctl command

Copy the backups and /opt/mpbx/compose/prod/.env off the server. For full encrypted backups see Backup and restore.

Upgrades

sudo apt-get update && sudo apt-get upgrade installs the next release: the package's post-install step takes a pg_dump, then runs mpbx-ctl upgrade (snapshot, checks, migrations, self-test, automatic rollback on failure). If the upgrade does not complete, MonoPbx keeps running the previous release and sudo monopbx upgrade retries it. Set MONOPBX_SKIP_UPGRADE=1 for apt-get to defer it.

Uninstall

sudo monopbx uninstall            # stops and removes the service and containers; keeps data and secrets
sudo monopbx uninstall --purge    # also deletes the data volumes and /opt/mpbx (you type the host name)
sudo apt-get remove monopbx       # removes the package; never stops MonoPbx or deletes data

Docker stays installed.