Your first connection.
Run MunaSIP on your Linux server, configure the essentials and connect your first extension.
Start with the right host
The supported production path is Docker on a Linux VM. The prebuilt image is published for linux/amd64; the bundled EMA speech dependencies are AMD64-specific. A macOS lab can be useful for exploring the panel, but it is not the recommended SIP/RTP deployment.
| Requirement | Guidance |
|---|---|
| Operating system | Debian 12/13 or Ubuntu 22.04+ on x86-64, with Docker Engine and Compose v2. |
| CPU and memory | Plan 2–4 vCPU and 4–8 GB RAM for a small office of roughly 20 extensions. Speech synthesis uses the PBX CPU. |
| Identity | A public IPv4 address and a hostname pointing to the server. |
| Storage | A real persistent volume at /data for the all-in-one image. Size recordings and backups for your retention policy. |
Option 1: the prebuilt Docker image
The all-in-one image contains the web panel, API, Asterisk, embedded PostgreSQL and speech engines. The command below pins release 1.6.0. Replace 203.0.113.10 and pbx.example.com with your actual public IP and hostname.
docker run -d --name munasip \
--restart unless-stopped \
-p 3000:3000 \
-p 10000-10100:10000-10100/udp \
-v munasip-data:/data \
-e EXTERNAL_IP=203.0.113.10 \
-e PUBLIC_HOST=pbx.example.com \
ghcr.io/munasip/munasip:1.6.0
Put the application port 3000 behind an HTTPS reverse proxy for your public hostname. Browser calling needs HTTPS, working WSS signalling and reachable media ports. The image can also use a managed PostgreSQL instance via DATABASE_URL.
Keep the /data volume and /data/.munasip-secrets backed up. They contain the database, generated configuration, recordings and keys needed to read encrypted secrets. With a public hostname, boot checks that the data directory is a real volume.
Option 2: build with Docker Compose
Compose runs the services with nginx and coturn. This is the documented route for controlling the complete edge and media stack. The certificate script below creates a lab certificate. For public operation, configure your hostname, strong secrets and a trusted HTTPS certificate.
git clone https://github.com/MunaSIP/MunaSIP.git
cd MunaSIP
git checkout v1.6.0
cp .env.example .env
chmod +x scripts/gen-certs.sh
./scripts/gen-certs.sh
docker compose up --build -d
The lab panel opens at https://localhost. For production, edit .env before starting the stack. Set EXTERNAL_IP, PUBLIC_HOST, PUBLIC_URL, SIP_DOMAIN, SIP_WSS_URL, database credentials, session/encryption keys and the admin password. Follow the upstream VPS guide for the complete configuration.
Get signalling and audio connected
A working web panel does not prove that calling audio works. SIP signalling, browser WSS and RTP media have different paths. Restrict SIP access to the office, VPN and provider addresses wherever possible.
| Port / path | Purpose | Deployment note |
|---|---|---|
| 3000/TCP | All-in-one application / API | Publish behind a trusted HTTPS proxy. Proxy /asterisk-ws for browser signalling. |
| 443/TCP | Public HTTPS and WSS | nginx handles this in Compose. Compose can multiplex TURNS on 443. |
| 80/TCP | ACME HTTP-01 / redirect | Must reach the server when using automatic Let’s Encrypt HTTP-01. |
| 10000–10100/UDP | Asterisk RTP audio | Publish and set EXTERNAL_IP correctly; scope firewall rules to the required media peers. |
| 5060/UDP or TCP | Desk-phone / provider SIP | Not published by the quick command; add it when required and restrict sources. |
| TURN / TURNS | Remote WebRTC media relay | Compose includes coturn. A platform HTTPS proxy alone does not replace a media relay. |
On a platform edge without the Compose ALPN mux, the install guide documents MUNASIP_RTP_PUBLISHED=1 when RTP is actually published, and MUNASIP_TURNS_ON_443=0 for a deliberate STUN-only deployment. Review your network before applying either option.
Set up the first conversation
- Sign in to the admin panel. Lab defaults are
admin@example.com/Admin123!; replace them before exposing the installation. - Set the hostname and configure trusted HTTPS. In the Compose deployment, Admin → Settings → Hostname & SSL offers automatic Let’s Encrypt certificates.
- Add your SIP provider, then configure inbound DIDs and outbound routes.
- Create or review extensions. Each extension uses one password for the portal and SIP. Rotate any seeded lab passwords.
- Sign in to the portal using an extension. Allow microphone access, confirm registration, and test both directions of audio.
- Call another extension, then test your actual provider route, queue, after-hours destination and recording policy.
This site documents setup; it does not run or test your PBX. Validate the carrier, NAT, audio, caller ID and recovery path with your actual infrastructure before a cutover.
Update without losing the state
Back up first. Pull the selected image tag and recreate the container with the same environment, ports and persistent volume. Pulling an image alone does not replace a running container.
docker pull ghcr.io/munasip/munasip:1.6.0\n# Recreate the service with the same /data volume and configuration.
For Compose, named volumes retain state across rebuilds. docker compose down keeps volumes; adding -v deletes them. Review the upstream install guide for migration and backup details.