Quickstart

In this tutorial, you run the all-in-one Routr image with Docker Compose, create a SIP Domain and two Agents with the rctl command-line tool, register two softphones, and call from one to the other.

What you’ll build

A single Routr server on your machine with:

A Domain named sip.local.
Two Agents, 1001 (John) and 1002 (Jane), each with its own Credentials.
Two softphones registered to Routr that can call each other.

It takes about ten minutes.

Prerequisites

Docker with Docker Compose.
Node.js and npm, to install rctl.
Two SIP softphones, for example Zoiper or Telephone. You can run them on the same computer or on two devices on the same network.
The IP address of the machine that runs Docker, as seen by your softphones (for example 192.168.1.3).

Steps

Start Routr

Create a directory named routr and add a file named compose.yaml with the following content. It runs fonoster/routr-one, the all-in-one image that bundles every Routr service and a PostgreSQL database in one container.

compose.yaml

services:
  routr:
    image: fonoster/routr-one:latest
    environment:
      EXTERNAL_ADDRS: ${DOCKER_HOST_ADDRESS}
    ports:
      - 51908:51908
      - 5060:5060/udp
      - 5060:5060/tcp
    volumes:
      - shared:/var/lib/postgresql/data

volumes:
  shared:

Here’s what each part does:

EXTERNAL_ADDRS tells the EdgePort which address to advertise in SIP messages. Use an address your softphones can reach.
Port 51908 is the API Server, which rctl talks to. Port 5060 is SIP signaling over UDP and TCP.
The shared volume keeps the database between restarts.

Start the server. Replace 192.168.1.3 with your own IP address.

DOCKER_HOST_ADDRESS=192.168.1.3 docker compose up -d

Then follow the logs until the services are up:

docker compose logs -f routr

Look for the following lines. Press Ctrl+C to stop following the logs; the server keeps running.

routr v2 // all in one distribution
...
starting edgeport ref = ...

Routr is running and listening for SIP on port 5060 and for API calls on port 51908.

Install rctl

Install the Routr command-line tool globally with npm:

npm install -g @routr/ctl

Check that it’s installed:

rctl --version

Every command in this tutorial uses --insecure because the all-in-one image serves the API without TLS. To secure it, see Secure the server.

Create a Domain

A Domain groups Agents that can call each other. Create one with the SIP URI sip.local:

rctl domains create --insecure

Answer the prompts as shown. Leave the access control list set to None.

This utility will help you create a new Domain.
Press ^C at any time to quit.
? Friendly Name Local Domain
? SIP URI sip.local
? IP Access Control List None
? Ready? Yes
Creating Domain Local Domain... a27e9fb2-a71a-4cf3-9b1d-dccf373f9777

Create Credentials for both Agents

Credentials hold the username and password a softphone uses to register. Create the first set:

rctl credentials create --insecure

Use 1001 as the username and 1234 as the password:

This utility will help you create a new set of Credentials.
Press ^C at any time to quit.
? Friendly Name John Doe Credentials
? Username 1001
? Password [hidden]
? Ready? Yes
Creating Credentials John Doe Credentials... 8814fc24-2328-43af-82d4-f5347fe4521b

Run the command again to create Jane Doe Credentials with username 1002 and password 1234.

Create two Agents

An Agent is a SIP endpoint, such as a softphone, that belongs to a Domain. Create John:

rctl agents create --insecure

Select the sip.local Domain and John’s Credentials. Leave Max Contacts empty for no limit, and keep the other defaults.

This utility will help you create a new Agent.
Press ^C at any time to quit.
? Friendly Name John Doe
? Select a Domain sip.local
? Username 1001
? Credentials Name John Doe Credentials
? Max Contacts
? Privacy None
? Enabled? Yes
? Ready? Yes
Creating Agent John Doe... 8dae9a7d-99b8-4279-88e1-4cf6ed67190a

Run the command again to create Jane Doe with username 1002 and Jane Doe Credentials.List the Agents to confirm both exist:

rctl agents get --insecure

The output looks similar to this:

Ref                                  Name     Username Domain    Max Contacts Privacy Enabled
8dae9a7d-99b8-4279-88e1-4cf6ed67190a John Doe 1001     sip.local -1           NONE    Yes
5c1e8f2a-3b4d-4e6f-9a7b-1c2d3e4f5a6b Jane Doe 1002     sip.local -1           NONE    Yes

You have a Domain and two Agents that can register and call each other.

Add an account for 1001 in the first softphone and for 1002 in the second. Use these settings:

Setting	Value
Domain	`sip.local`
Username	`1001` (or `1002`)
Password	`1234`
Proxy or registrar	Your Docker host IP, port `5060` (for example `192.168.1.3:5060`)
Transport	UDP

sip.local doesn’t resolve in DNS, so the softphone must send its requests to Routr through the proxy setting. In Telephone, the account looks like this:

Telephone account settings for 1001 with domain sip.local, username 1001, and a password

And the proxy settings point at the Docker host:

Telephone advanced settings with SIP address 1001@sip.local, registry server 192.168.1.2, and proxy 192.168.1.2 on port 5060

Both softphones show the account as registered (or online).

Make a call

From John’s softphone (1001), dial 1002. Jane’s softphone rings. Answer it and talk.To watch the SIP messages as the call happens, open sngrep, which is included in the image:

docker compose exec routr sngrep

You made an agent-to-agent call through Routr.

Clean up

Stop and remove the container when you’re done. Add -v to also delete the database volume.

docker compose down

Troubleshooting

The softphone doesn’t register. Check that DOCKER_HOST_ADDRESS is an address the softphone can reach, and that the softphone’s proxy setting points at it on port 5060.
Registration works, but calls drop or don’t ring after a while on UDP. NAT devices close idle UDP mappings quickly. Lower the softphone’s re-register interval, or use TCP. See EdgePort cooperation for why connection-oriented transports are recommended.
rctl can’t connect. Make sure port 51908 is published and that you pass --insecure.

Next steps

Set up a home or office

Add a Trunk and a Number so your Agents can call the PSTN.

Manage resources with rctl

Learn the commands for every Connect resource.

Architecture

See what happens inside Routr when a call arrives.

Deploy with Docker

Run Routr with Docker for a longer-lived setup.

Get started

Concepts

How-to guides

Tutorials

Community

What you’ll build

Prerequisites

Steps

Clean up

Troubleshooting

Next steps

Set up a home or office

Manage resources with rctl

Architecture

Deploy with Docker

​What you’ll build

​Prerequisites

​Steps

​Clean up

​Troubleshooting

​Next steps

Set up a home or office

Manage resources with rctl

Architecture

Deploy with Docker

What you’ll build

Prerequisites

Steps

Clean up

Troubleshooting

Next steps