1001, the app on your test phone is closed, and the phone rings anyway.
This is a test setup. pgw runs on your computer with a self-signed certificate, which only a debug build of your app accepts. When it works, install pgw on a server.
Before you begin
You need:- A computer on the same network as your test phone, with 64-bit Linux, macOS, or Windows.
- Your PBX, reachable from that computer, with a SIP account to test with. This page uses
1001. - Push credentials for your app. For iOS, an APNs key (
.p8file) with its key ID and your team ID. For Android, a Firebase service account file. If you don’t have them yet, see iOS apps or Android apps. - A debug build of your app that accepts a self-signed certificate. A build from the App Store or Google Play won’t connect in this setup.
com.example.phone, and a PBX at 192.0.2.10. Use your own values.
Step 1: Start pgw
1
Download pgw
Download the file for your system from the download page into a new folder, and rename it to macOS blocks files that a browser downloaded. Remove the block:
pgw (pgw.exe on Windows).On Linux and macOS, make it executable:2
Create the starter files
pgw init writes everything that pgw needs to start, with working defaults:3
Check the address
Open
config.yaml and look at hostname. Your phone and your PBX reach pgw at this address, and pgw init filled in your computer’s LAN address. If your computer has several addresses and this is the wrong one, correct it.4
Start the server
pgw ready with the ports that it listens on: 5061 for apps, 5060 for the PBX, and 8080 for commands, which only this computer can reach.5
Create your tenant
Leave the server running, and open a second terminal in the same folder. A tenant is your workspace in pgw, and it comes with an API key:You don’t need to copy the key. The other
pgw commands read it from .env.Step 2: Add your app and your PBX
pgw needs two records: an app, so that it can send pushes with your credentials, and an upstream, which is pgw’s name for a PBX. In this setup, both come fromtenant.yaml.
1
Add your app
Copy your credential file into the folder. In A debug build of an iOS app receives pushes only from Apple’s
tenant.yaml, under apps, uncomment the block for your platform and fill in your values:sandbox environment, so keep that value for this test.2
Add your PBX
Under If your PBX doesn’t support the Path header, also uncomment
upstreams, replace <pbx-host> with your PBX’s IP address:contact_strategy and set it to masquerade. You can’t change it later. The page for your PBX, linked in step 3, says whether the PBX needs masquerade.3
Apply the file
+ marks a record that it created:Step 3: Point your PBX and your app at pgw
1
Configure the PBX
The PBX must accept registrations that arrive through pgw, and send the calls for those devices back to pgw. The settings differ for each PBX, so follow its page, then return here:
2
Configure the app
In your debug build, turn off certificate checks, because pgw’s certificate is self-signed. Then add the SIP account. The account stays the same as before, except that the app now connects to pgw instead of the PBX:
Step 4: Check that it works
1
Check the registration
1001, with flow_alive set to true while the app is connected.2
Close the app
Swipe the app away. On Android, use Recents, not Force stop: Android delivers no pushes to an app that was force-stopped.
3
Call 1001
Call
1001 from another phone on your PBX. The test phone rings, and the call connects when you answer.If the phone doesn’t ring
Work through these checks in order.
To read the push log, ask the API for the latest push events:
call and the status code 200.
For other symptoms, see Troubleshooting.
Next steps
Install pgw on a server
Move from this test setup to a host that runs pgw under systemd.
Install a TLS certificate
Replace the self-signed certificate, so that store builds of your app connect.
Concepts
Understand the records that you created, and the choices behind them.