DEV Community: Pedro Sanders

Building a VoIP Network with Routr on DigitalOcean Kubernetes: Part I

Pedro Sanders — Mon, 04 Mar 2024 12:43:15 +0000

Building a VoIP Network with Routr on DigitalOcean Kubernetes: Part I

Routr v2 takes a radical design approach by being container-first and taking full advantage of environments like Kubernetes. In this three-part tutorial, you will learn how to:

Create a load balancer on DOKS and deploy Routr
Secure the admin and signaling ports with Let's Encrypt
Prepare the network for production

Before you continue, be sure to star Routr on GitHub 👇

fonoster / routr

⚡ The future of programmable SIP servers.

Requirements

Before you start this tutorial, you will need the following:

An account in DigitalOcean and a DOKS cluster
NodeJS >= 18 (Use nvm if possible)
Routr command-line tool (Install it with npm install -g @routr/ctl)
Kubectl with access to your DOKS cluster
Helm (Get from here https://helm.sh/)

Check the DOKS cluster and other dependencies

This tutorial assumes you have a running DOKS cluster. If you need help creating a DOKS creating, please visit the following link: https://docs.digitalocean.com/products/kubernetes/how-to/create-clusters/

With that, ensure you can connect to your cluster using Kubectl before continuing with the next steps.

Creating a new Load Balancer in Digital Ocean

To create a new load balancer, go to the networking section within the DigitalOcean panel, find the "Load Balancers" tab, and click "Create Load Balancer."

Your page will look like this:

Follow the creation steps using all the default values and note the load balancer's name.

Installing Routr using Helm

Once your load balancer is up and running, follow the next instructions to install Routr with Helm.

First, add Routr to the Helm repository with:



helm repo add routr https://routr.io/charts
helm repo update

You can get details about the new repo with the following:



helm repo list

Then, create a namespace for Routr using the create namespace subcommand:



kubectl create namespace routr

Next, create a values.yaml with the following content find, and remember to replace the externalAddrs property and serviceAnnotationsTCP with your values.

Filename: values.yaml



edgeport:
  externalAddrs: ["159.203.158.25"]
  serviceTypeTCP: LoadBalancer
  serviceAnnotationsTCP:
    service.beta.kubernetes.io/do-loadbalancer-name: "nyc1-load-balancer-01"
  transport:
    tcp:
      enabled: true

Alternatively, you could use the annotation kubernetes.digitalocean.com/load-balancer-id to use the load balancer's ID instead of the name.

Finally, create the SIP network with:



helm install sipnet routr/routr-connect --namespace routr -f values.yaml

Within a few minutes, you will see the following message:

You can check the status of the Pods with the "get pods" subcommand, like here:



kubectl get pods -n routr

You should see a list of pods and their status. If the status of all services is "Running," you are ready to go.

Please see the Official Chart for many more options for your deployment.

Configuring a Domain, Credentials, and Agents in Routr

With Routr deployed, the next step will be to create the following resources:

The "sip.local" domain
Two sets of credentials (e.g., 1001 and 1002)
Two SIP agents (e.g., John and Jane)

To send admin commands to Routr, you must expose the admin port.

Here, for simplicity, we will use port-forward to expose the admin port. However, you might use a different method in production, like creating a separate load balancer.

To open the admin port, first list the services of your deployment and find the one for your admin port with the following:



kubectl get services -n routr

Then, open the admin using the port-forward subcommand:



kubectl port-forward svc/sipnet-routr-apiserver 51907 -n routr

Once the port is open, on a separate screen, begin creating a Domain with:



rctl domains create --insecure --endpoint=localhost:51907

Your output will look as follows:



Press ^C at any time to quit.
 ›   Warning: Egress rules unavailable due to 0 configured numbers.
? Friendly Name Local Domain
? SIP URI sip.local
? IP Access Control List None
? Ready? Yes
Creating Domain Local Domain... 3b20410a-3c80-4f66-b7b3-58f65ff65352

In the next part of the series, I will go over securing the connection with a self-signed certificate or using certificates from Let's Encrypt.

Continue by creating two sets of credentials with the following command:



rctl credentials create --insecure --endpoint=localhost:51907

Follow the prompt and repeat to create two sets (e.g., 1001 and 1002). Your output for the first credential will look like this:



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... 5fbc7367-a59d-4555-9fc4-a15ff29c24c8

Finally, create two sets of Agents:



rctl agents create --insecure --endpoint=localhost:51907

The output for your first Agent will look like this:



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... 662a379d-66f1-4e6e-9df5-5126f1dcb930

Please repeat the process for Jane.

Registering and Calling using Blink

Using Blink or your preferred softphone, create a new agent using the parameters in the abovementioned steps.

The result should show a green indicator like in the screenshot below.

Repeat the process from another instance of Blink, and make a call going to the main screen and typing the extension.

You should be able to send and receive calls from both devices.

What's next

Thank you for making it this far. In the upcoming days, I will publish Part II of this series, which will go over securing the signaling path and the admin port. In the meantime, feel free to enjoy the following tutorials:

Simplify SIP.js security with short-lived tokens

Pedro Sanders — Mon, 26 Feb 2024 21:24:19 +0000

Routr v2 has introduced Ephemeral Agents, eliminating the need to store sensitive credentials for WebRTC clients like SIP.js and using short-lived JWT tokens instead.

This tutorial will guide you through creating private and public keys and JWT tokens and configuring Routr to validate the tokens using the public key.

fonoster / routr

⚡ The future of programmable SIP servers.

Requirements

Before you start this tutorial, you will need the following:

Docker Engine installed on your computer or the cloud
NodeJS 18+ (Use nvm if possible)
Routr command-line tool (Install it with npm install -g @routr/ctl)

Creating a private and public key

To create a JWT token, you must first create a set of private and public keys. The private key is needed to sign the JWT token, and the public key is to verify the JWT token's signature.

You can create a private key using the following command:

mkdir -p voipnet/work
cd voipnet/work
openssl genpkey -algorithm RSA -out private.key -pkeyopt rsa_keygen_bits:4096

This command will create a new key named private.key. Keep this key safe, as it will be used to sign new JWT tokens.

With the private key in place, you can now create the public key with:

openssl rsa -in private.key -pubout -out public.key

The previous command resulted in a new key named public.key, which is necessary to verify the claims in the JWT token.

Creating a JWT token

In this section, you will create a small NodeJS script using the private key to sign a JWT token.

Now that you have a pair of private and public keys, you can create a JWT token. To create a JWT token, first, initialize a new Node project with:

npm init -y

Then, install the jsonwebtoken package as follows:

npm install jsonwebtoken

Next, create a file named create-jwt.js with the following content:

Filename: voipnet/work/create-jwt.js

const fs = require("fs");
const jwt = require("jsonwebtoken");

const privateKey = fs.readFileSync("private.key");

const fs = require("fs");
const jwt = require("jsonwebtoken");

const privateKey = fs.readFileSync("private.key");

// Epheperal Agent's claims
const payload = {
  ref: "agent-01",
  domainRef: "domain-01",
  aor: "sip:[email protected]",
  aorLink: "sip:[email protected]",
  domain: "sip.local",
  privacy: "NONE",
  allowedMethods: ["INVITE", "REGISTER"]
};

const signOptions = { expiresIn:  "1h", algorithm:  "RS256" };
const token = jwt.sign(payload, privateKey, signOptions);

console.log("Token: " + token);

As you can see in the previous script, the JWT token assigns claims to the Ephemeral Agent. Incidentally, the claims are similar to the values used by Routr when configuring a regular agent.

Please note that while you can use an arbitrary aor, the domainRef and domain claims must match a domain in the server.

Finally, run the following script to generate a fresh JWT token:

node create-jwt.js

After running the previous script, you will get a JWT token with an output similar to this:

Deploying Routr with Docker

You will use Docker Compose for this setup. If you don't have Docker installed, download it from the official website. Once you have Docker, create a new file named compose.yaml with the following content:

Filename: voipnet/compose.yaml

version: "3"

services:
  routr:
    image: fonoster/routr-one:latest
    environment:
      EXTERNAL_ADDRS: ${DOCKER_HOST_ADDRESS}
      CONNECT_VERIFIER_PUBLIC_KEY_PATH: /keys/public.key
    ports:
      - 51908:51908
      - 5062:5062
    volumes:
      # Makes sure that the data survives container restarts
      - shared:/var/lib/postgresql/data
      - ./work/public.key:/keys/public.key

  simplephone:
    image: psanders/simplephone:latest
    ports:
      - 8080:8080

volumes:
  shared:

# NOTE: Be sure to update the IP address
DOCKER_HOST_ADDRESS=192.168.1.7 docker compose up

You are all set and need a few seconds for the containers to initialize.

Create a new Domain in Routr

You will need to create a new Domain using the Routr command-line tool. Issue the following command and follow the prompt:

rctl domains create --insecure

Notice the --insecure flag, which is required since we don't have a TLS certificate.

The output of your command will look similar to the output below:

Press ^C at any time to quit.
 ›   Warning: Egress rules unavailable due to 0 configured numbers.
? Friendly Name Local Domain
? SIP URI sip.local
? IP Access Control List None
? Ready? Yes
Creating Domain Local Domain... 3b20410a-3c80-4f66-b7b3-58f65ff65352

You might verify the Domain's configuration by running the following command:

rctl domains get --insecure --extended

Registering a SIP.js client using the JWT token

Finally, configure your WebRTC client to register to the server using the claims in the JWT token by adding the X-Connect-Token with the value of the token we created previously.

Here is an example of a SIP.js client using the new JWT token to register to Routr:

What's next?

This tutorial taught you how to use Ephemeral Agents to secure SIP.js clients. You created a JWT token and used it to register a SIP.js client to a Routr server. You also learned how to create private and public keys and deploy Routr with Docker.

Please comment if you find this tutorial helpful, and check out the following related tutorials:

Building scalable IVRs for businesses with Routr and Asterisk

Pedro Sanders — Sun, 25 Feb 2024 20:12:37 +0000

In this tutorial, I will share how to create a VoIP network combining Routr, RTPEngine, and Asterisk for highly available voicemail, conference, IVR, or any other application in Asterisk.

The added advantage of this setup is that you can use Asterisk as a feature server and have dedicated instances for each feature you would like to provide.

fonoster / routr

⚡ The future of programmable SIP servers.

Requirements

Before you start this tutorial, you will need the following:

Docker Engine installed on your computer or the cloud
NodeJS 18+ (Use nvm if possible)
Routr command-line tool (Install it with npm install -g @routr/ctl)

Deploying Routr and Asterisk using Docker Compose

You will use Docker Compose for this setup; however, I recommend using Docker Swarm mode or Kubernetes for a production-ready setup.

Please see Routr's Helm chart for details on how to run Routr in K8s

To get started, first create a folder named voipnet. In the new folder, create a file name compose.yaml with the following content:

Filename: voipnet/compose.yaml

version: "3"

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

  rtpengine:
    image: fonoster/rtpengine:latest
    ports:
      - 22222:22222/udp
      - 10000-10100:10000-10100/udp
    environment:
      PUBLIC_IP: ${DOCKER_HOST_ADDRESS} 
      PORT_MIN: 10000
      PORT_MAX: 10100

  asterisk-01:
    image: fonoster/mediaserver:latest
    expose:
      - 6060
    environment:
      EXTERN_ADDR: ${DOCKER_HOST_ADDRESS}
      SIPPROXY_HOST: routr
      SIPPROXY_USERNAME: asterisk
      SIPPROXY_SECRET: asterisk
    volumes:
      - ./extensions.conf:/etc/asterisk/extensions.conf
      - ./sounds/count_1.sln16:/var/lib/asterisk/sounds/count.sln16

  asterisk-02:
    image: fonoster/mediaserver:latest
    expose:
      - 6060
    environment:
      EXTERN_ADDR: ${DOCKER_HOST_ADDRESS}
      SIPPROXY_HOST: routr
      SIPPROXY_USERNAME: asterisk
      SIPPROXY_SECRET: asterisk
    volumes:
      - ./extensions.conf:/etc/asterisk/extensions.conf
      - ./sounds/count_2.sln16:/var/lib/asterisk/sounds/count.sln16

  simplephone:
    image: psanders/simplephone:latest
    ports:
      - 8080:8080

volumes:
  shared:

A few things to note:

We added the shared volume to make sure the data survives container restarts
The simplephone and rtpengine services are optional, and you may remove them if you don't need support for WebRTC
Notice how we mapped the sounds count_1.sln16 to asterisk-1 and count_2.sln16 to asterisk-2 respectively.

Next, in the same folder, create the file extensions.conf

Filename: voipnet/extensions.conf

[local-ctx]
exten => asterisk,1,NoOp()
 same => n,Playback(count)
 same => n,Hangup()

The previous configuration features the equivalent of a "Hello world" for Asterisk. However, you could use the same principle and instead connect it to a voice application or conference.

Then, create a sounds folder and download count_2.sln16 and count_2.sln16 from here.

Your folder structure will end up like this:

.
├── compose.yaml
├── extensions.conf
└── sounds
    ├── count_1.sln16
    └── count_2.sln16

Finally, run the following command to start all the services:

# NOTE: Be sure to update the IP address
DOCKER_HOST_ADDRESS=192.168.1.7 docker compose up

The previous command will pull all the services from Docker Hub and run the containers. You could also add the -d option to run the service in the background.

Configuring the network with Routr Command-Line Tool

You will use Routr's command-line tool to issue commands to the server and build the VoIP network.

For the setup, we will create a Domain with the sip.local URI, an Agent to test the calls and a Peer to represent Asterisk.

Remember that while we are using Agents for testing, in production, you would instead use Trunks to accept PSTN traffic, which is not covered in this tutorial.

We will start by creating a Domain with:

rctl domains create --insecure

Notice the --insecure flag, which is required since we don't have a TLS certificate.

The output of your command will look similar to the output below:

Press ^C at any time to quit.
 ›   Warning: Egress rules unavailable due to 0 configured numbers.
? Friendly Name Local Domain
? SIP URI sip.local
? IP Access Control List None
? Ready? Yes
Creating Domain Local Domain... 3b20410a-3c80-4f66-b7b3-58f65ff65352

Next, create two sets of credentials, one for Asterisk and one for John Doe, by issuing the following command:

rctl credentials create --insecure

Your output will be similar to this:

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... 5fbc7367-a59d-4555-9fc4-a15ff29c24c8

Repeat the process for Asterisk, and set the password to asterisk.

Next, create an Agent to represent the test Agent, John Doe, with the following command:

rctl agents create --insecure

Your output will be like the one below:

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... 662a379d-66f1-4e6e-9df5-5126f1dcb930

Finally, create a Peer to represent Asterisk with:

rctl peer create --insecure

Follow the prompt, select Round Robin as the balancing algorithm, and sip:asterisk as the Address of Record (AOR).

The output should look like this:

This utility will help you create a new Peer.
Press ^C at any time to quit.
? Friendly Name Asterisk PBX
? Username asterisk
? Address of Record sip:asterisk
? Contact Address 
? Max Contacts 
? IP Access Control List None
? Credentials Name Asterisk - Credentials
? Enable Session Affinity? No
? Balancing Algorithm Round Robin
? Enabled? Yes
? Ready? Yes
Creating Peer Asterisk PBX... 1f859fee-5c4c-4771-b8fd-a6c469ffe9bf

You might use the get subcommand to verify your settings.

For example:

rctl agents get --insecure --extended

Calling Asterisk from the Browser using SIP.js

The compose file we created at the beginning of this tutorial contains the simplephone container, a softphone implemented with SIP.js, which is available at http://localhost:8080.

Here is what the SimplePhone will look like:

Set your instance to look like the one below, then click "Save and connect," followed by "Call."

You should hear the numbers alternate every time you press "Call," showing that the calls are correctly load-balanced.

What’s next?

Please comment if you find this tutorial helpful and check out the following relevant tutorials:

Calling a door phone from a web browser

Pedro Sanders — Fri, 23 Feb 2024 18:27:26 +0000

Calling a door phone from a web browser

In this tutorial, I will take you through the steps of building a VoIP network that will allow you to make calls from a web browser out to a door phone. This setup would be helpful for access control for commercial buildings, monitoring and security, calls for assistance in hospitals, and more.

We will use SIP.js as the client, Routr as the signaling server, and RTPEngine to proxy RTP traffic.

fonoster / routr

⚡ The future of programmable SIP servers.

Requirements

Before you start this tutorial, you will need the following:

Docker Engine installed on your computer or the cloud
NodeJS 18+ (Use nvm if possible)
Routr command-line tool (Install with npm install -g @routr/ctl)
A door phone such as Fanvil i20S

Running Routr and RTPEngine with Docker Compose

This tutorial will use Routr for signaling and RTPEngine to proxy RTP traffic.

The simplest way to run both services is using Docker Compose.

To run the services with Docker Compose, first, create a folder named voipnet and, in it, a file named compose.yaml with the following content:

Filename: voipnet/compose.yml

version: "3"

services:
  routr:
    image: fonoster/routr-one:latest
    environment:
      EXTERNAL_ADDRS: ${DOCKER_HOST_ADDRESS}
      RTPENGINE_HOST: rtpengine
    ports:
      - 51908:51908
      - 5062:5062
      - 5060:5060
    volumes:
      # Ensures the data survives container restarts
      - shared:/var/lib/postgresql/data

  # RTPEngine requires network mode "host" to work properly. However, this option doesn't work on 
  # Windows and MacOs. For development, we are opening a few ports to the host machine. 
  # For production, you must use the network_mode: host which works on Linux.
  rtpengine:
    image: fonoster/rtpengine:latest
    # Uncomment the following line for production
    # network_mode: host
    environment:
      # Set DOCKER_HOST_ADDRESS to an IP address that is reachable to the SIP clients
      PUBLIC_IP: ${DOCKER_HOST_ADDRESS}
      PORT_MIN: 10000
      PORT_MAX: 10100
      LOG_LEVEL: 6
    ports:
      - 22222:22222/udp
      - 10000-10100:10000-10100/udp

volumes:
  shared:

Notice how we included the environment variables EXTERNAL_ADDRS and PUBLIC_IP in the previous file, whose value must be set to an IP that all parties can reach to avoid wrong signaling and audio issues.

Also noteworthy is that the port 51908 was opened for administration, 5060 for TCP signaling, and 5062 for signaling with SIP.js

Next, save the file and run the following command:

# NOTE: Be sure to update the IP address
DOCKER_HOST_ADDRESS=192.168.1.7 docker compose up

The previous command will pull Routr and RTPEngine from Docker Hub and start the containers. You could also add the -d option to run the service in the background.

Configuring a Domain and a set of Agents

You will use Routr's command-line tool to issue commands to the server and build the VoIP network.

The network will have a Domain, sip.local, an Agent named "Door Phone," and an Agent named "Admin."

To build the VoIP network, first create a new Domain with:

rctl domains create --insecure

Notice the --insecure flag, which is required since we don't have a TLS certificate.

The output of your command will look similar to the output below:

Press ^C at any time to quit.
 ›   Warning: Egress rules unavailable due to 0 configured numbers.
? Friendly Name Local Domain
? SIP URI sip.local
? IP Access Control List None
? Ready? Yes
Creating Domain Local Domain... 3b20410a-3c80-4f66-b7b3-58f65ff65352

Next, create two sets of credentials—one for the administrator and one for the door phone.

To create a set of credentials, issue the following command:

rctl credentials create --insecure

You must do this twice, one for the Door Phone and one for Admin. Please set the Door Phone username to doorphone1 and the Admin to admin

Your output will be similar to this:

This utility will help you create a new set of Credentials.
Press ^C at any time to quit.
? Friendly Name Door Phone #1 - Credentials
? Username doorphone1
? Password [hidden]
? Ready? Yes
Creating Credentials Door Phone - Credentials... 5fbc7367-a59d-4555-9fc4-a15ff29c24c8

Finally, create Agents to represent the Door Phone and the Admin using the following command:

rctl agents create --insecure

Follow the prompt and ensure that the username matches that of the credentials.

Your output will look similar to this:

This utility will help you create a new Agent.
Press ^C at any time to quit.
? Friendly Name Door Phone #1
? Select a Domain sip.local
? Username doorphone1
? Credentials Name Door Phone #1 - Credentials
? Max Contacts 1
? Privacy None
? Enabled? Yes
? Ready? Yes
Creating Agent Door Phone #1... 662a379d-66f1-4e6e-9df5-5126f1dcb930

Be sure to repeat the process for the Admin.

You might use the get subcommand for any previously created resources to verify your settings. For example, to get a list of Agents, you might run this:

rctl agents get --insecure

Configuring the door phone

The configuration on your door phone will depend on the make and model. However, generally speaking, it should have the following parameters:

Username
Password
Domain
Proxy/Server

For a Fanvil iS20, the configuration will be like this:

Building a barebones tool for calling

To create the SIP Agent, we will use the SimpleAgent implementation SIP.js, which is perfect for testing.

For a bare-bone SIP Agent, copy the following code in a file named index.html:

Filename voipnet/index.html

<!DOCTYPE html>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">

<head>
  <meta charset="utf-8" />
  <title>Video Feed</title>
  <style>
    h1 { font-family: 'Courier New', Courier, monospace; }
  </style>
</head>

<body>
  <h1>Door Phone Video Feed</h1>
  <div style="border: 1px solid black;  width: 300px; height: 300px;">
    <video id="remoteVideo" autoplay muted style="background-color: black; height: 100%"></video>
  </div>

  <br />

  <button id="callButton">Call Door Phone</button>
  <button id="hangupButton">Hangup</button>

  <audio style="display: none" id="remoteAudio" controls>
    <p>Your browser doesn't support HTML5 audio.</p>
  </audio>
  <script type="module">
    import { Web } from "https://unpkg.com/[email protected]/lib/index.js";

    document.addEventListener('DOMContentLoaded', () => {
      const remoteVideo = document.getElementById('remoteVideo');
      const callButton = document.getElementById('callButton');
      const hangupButton = document.getElementById('hangupButton');
      const remoteAudio = document.getElementById('remoteAudio');

      const config = {
        server: "ws://localhost:5062",
        aor:  "sip:[email protected]",
        doorPhoneAor: "sip:[email protected]"
      }

      const options = {
        aor: config.aor,
        media: {
          constraints: { audio: true, video: true },
          remote: {
            audio: remoteAudio,
            video: remoteVideo
          }
        },
        userAgentOptions: {
          authorizationUsername: "admin",
          authorizationPassword: "1234",
        }
      };

      const simpleUser = new Web.SimpleUser(config.server, options);

      callButton.addEventListener('click', async() => {
        await simpleUser.connect();
        simpleUser.call(config.doorPhoneAor);
      });

      hangupButton.addEventListener('click', () => {
        simpleUser.hangup();
      });
    });
  </script>
</body>

</html>

Then, lunch the SIP Agent with:

npx http-server .

Calling the door phone from the web browser

Now that created a SIP agent using SIP.js, we only need to register the door phone to Routr and press the "Call Door Phone" button in the web browser.

If you have issues calling the door phone, please inspect the browser's console for errors.

The SIP agent should connect to the door phone, and you should see a video feed.

Example of the output:

What's next?

Please comment if you find this tutorial helpful and check out the following relevant tutorials:

Browser-to-Browser calling with SIP.js and Routr

Pedro Sanders — Thu, 22 Feb 2024 13:08:27 +0000

In this tutorial, I will show you how to use SIP.js and Routr to develop seamless calling experiences without losing your hair. By the end of this tutorial, you will be able to apply the same principles to building 1-1 video calls, chat applications, click-to-call buttons, and more.

Remember that this is one way to accomplish this task, and it is especially relevant if you plan to make future calls to the PSTN (Private Switch Telephone Network).

fonoster / routr

⚡ The future of programmable SIP servers.

Requirements

Before you start this tutorial, you will need the following:

Docker Engine installed on your computer or the cloud
NodeJS 18+ (Use nvm if possible)
Routr command-line tool (Install with npm install -g @routr/ctl)

Running Routr server with Docker Compose

This tutorial will use Routr to establish a call between two phones running on separate browsers.

The simplest way to run Routr is using Docker Compose.

To run Routr with Docker Compose, first, create a folder named voipnet and in it, a file named compose.yaml with the following content:

Filename: voipnet/compose.yml



version: "3"

services:
  routr:
    image: fonoster/routr-one:latest
    environment:
      EXTERNAL_ADDRS: ${DOCKER_HOST_ADDRESS}
    ports:
      - 51908:51908
      - 5062:5062
    volumes:
      # Ensures the data survives container restarts
      - shared:/var/lib/postgresql/data

volumes:
  shared:

Notice how we included the environment variable EXTERNAL_ADDRS in the previous file, whose value must be set to an IP that all parties can reach to avoid wrong signaling.

Also noteworthy is that the ports 51908 and 5062 were opened for administration and signaling.

Next, save the file and run the following command:



# NOTE: Be sure to update the IP address
DOCKER_HOST_ADDRESS=192.168.1.7 docker compose up

The previous command will pull Routr from Docker Hub and run the container. You could also add the -d option to run the service in the background.

Configuring the VoIP network

You will use Routr's command-line tool to issue commands to the server and build the VoIP network.

To build the VoIP network, first create a new Domain with:



rctl domains create --insecure

Notice the --insecure flag, which is required since we don't have a TLS certificate.

The output of your command will look similar to the output below:



Press ^C at any time to quit.
 ›   Warning: Egress rules unavailable due to 0 configured numbers.
? Friendly Name Local Domain
? SIP URI sip.local
? IP Access Control List None
? Ready? Yes
Creating Domain Local Domain... 3b20410a-3c80-4f66-b7b3-58f65ff65352

Next, create two sets of credentials—one for John and one for Jane.

To create a set of credentials, issue the following command:



rctl credentials create --insecure

You must do this twice, one for John and one for Jane. Please set John's username to 1001 and Jane's to 1002.

Your output will be similar to this:



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... 5fbc7367-a59d-4555-9fc4-a15ff29c24c8

Finally, create Agents to represent John and Jane using the following command:



rctl agents create --insecure

Follow the prompt and ensure that the username matches that of the credentials.

Your output will look similar to this:



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 1
? Privacy None
? Enabled? Yes
? Ready? Yes
Creating Agent John Doe... 662a379d-66f1-4e6e-9df5-5126f1dcb930

Be sure to repeat the process for Jane.

You might use the get subcommand for any previously created resources to verify your settings. For example, to get a list of Agents, you might run this:



rctl agents get --insecure

Running the SimplePhone with Docker Compose

SimplePhone is a phone built using SIP.js that runs as a Docker container. Please see the documentation at https://sipjs.com/ to develop your implementation.

To run the phone, you must first update the compose.yaml file with the following code:

Filename: voipnet/compose.yaml



--snip--

  simplephone:
    image: psanders/simplephone:latest
    environment:
      NODE_ENV: production
    ports:
      - 8080:8080

volumes:
  shared:

Then, re-run the docker compose up command. You can go to http://localhost:8080 to see the phone when all the services are up.

Making a call between the two phones

Remember the Agents you created at the start of this tutorial? You will now use the same values to configure two phone instances.

On a tab on your browser, open an instance of the SimplePhone and enter the information for John; click "Save and connect" followed by "Register."

The SimplePhone will look similar to this:

If you have issues connecting or registering, please inspect the browser's console for errors.

Then, open a new tab or browser and repeat the process for Jane.

Finally, click on the "Call" button to reach John or Jane.

What's next?

Please comment if you find this tutorial helpful and check out the following relevant tutorials:

The essentials of building Voice Applications with Fonoster

Pedro Sanders — Sat, 03 Jul 2021 13:24:00 +0000

The purpose of this tutorial is to show the basics of Fonoster. Here you will find how to create a Voice Application, add a Number, and then use that Number to originate a call. Please follow the guide in sequence, as each step builds on the last one.

fonoster / fonoster

🚀 The open-source alternative to Twilio.

Requirements

Before you start this guide, you will need the following:

A set of credentials from here 👈
An account for access to a SIP Service Provider (For US and Canada, we recommend voip.ms)
NodeJS 14+ (Use nvm if possible)
Fonoster command-line tool (install with npm install -g @fonoster/ctl)
Ngrok (install with npm install -g ngrok)

You can login to the server with:

fonoster auth:login

And your output will be similar to:

Access your Fonoster infrastructure
Press ^C at any time to quit.
? api endpoint api.fonoster.io
? access key id psanders
? access key token *************************...
? ready? Yes
Accessing endpoint api.fonoster.io... Done

Then, set the default Project:

# Get the PROJECT_ID of the project using the 'projects:list' command 
fonoster projects:use ${PROJECT_ID}

Creating a basic Voice Application

A Voice Application is a server that takes control of the flow of a call. A Voice Application can use any combination of the following verbs:

Answer - Accepts the call
Hangup - Closes the call
Play - It takes an URL or file and streams the sound back to the calling party
Say - It takes a text, synthesizes the text into audio, and streams the result
Gather - It waits for DTMF events and returns back the result
SGather - It listen for a stream DTMF events and returns back the result
Record - It records the voice of the calling party and saves the audio on the Storage sub-system
Mute - It tells the channel to stop sending media, thus effectively muting the channel
Unmute - It tells the channel to allow media flow

To create a Voice Application perform the following steps.

First, clone the NodeJS example template as follows:

git clone https://github.com/fonoster/nodejs-voiceapp

Next, install the dependencies:

cd nodejs-voiceapp
npm install

Finally, launch the Voice Application with:

npm start

Your output will look like this:

info: initializing voice server
info: starting voice server on @ 0.0.0.0, port=3000

Your app will live at http://127.0.0.1:3000. ⚠️ Be sure to leave the server up!

Using Ngrok to publish your Voice Application

Now that we have our Voice Application up and running, we need to make it available on the Internet——the fastest way to enable public access by using Ngrok. For example, with ngrok, you can publish a web server with a single command.

On a new console, run Ngrok with the following command:

ngrok http 3000

The output will look like this:

Leave this service running, and save the Forwarding URL for use in the next step.

Building a SIP Network

A SIP Network has all the building blocks needed to establish communication between two SIP endpoints(i.e., softphone, webphone, cellphone, the PSTN, etc.) We want to configure a Number and route the calls to our Voice Application on this guide.

Let's start by creating a SIP Service Provider.

Adding a SIP Service Provider

A SIP Service Provider is an organization that will terminate your calls to the phone network (or PSTN). You will need the username, password, and host you obtained from your SIP Service Provider for this section.

Create a new provider with:

fonoster providers:create

The output will look similar to this:

This utility will help you create a new Provider
Press ^C at any time to quit.
? friendly name VOIPMS
? username 215706
? secret [hidden]
? host newyork1.voip.ms
? transport tcp
? expire 300
? ready? Yes
Creating provider YourServiceProvider... Done

Adding a SIP Number

A Number, often referred to as DID/DOD, is a number managed by your SIP Service provider.

If your Provider doesn't accept E164, you can append the --ignore-e164-validation

fonoster numbers:create --ignore-e164-validation

Here is an example of the output:

This utility will help you create a new Number
Press ^C at any time to quit.
? number in E.164 format (e.g. +16471234567) 9842753574    
? service provider VOIPMS
? aor link (leave empty)
? webhook https://5a2d2ea5d84d.ngrok.io # Replace with the value you obtained from Ngrok
? ready? Yes
Creating number +17853178071... KyjgGEkasj

⚠️ Be sure to replace the information with what was given to you by your Provider.

Creating a SIP Domain

A SIP Domain is a space within the SIP Network where SIP entities live (usually SIP Agents). To create a SIP Domain, you can use the command-line tool or the SDK.

In this step, you need to select the Number you just created as your Egreess Number. Also, make sure to use an "unclaimed" uri or you will receive this error: "› Error: This Domain already exists."

Create a new Domain with:

fonoster domains:create

Your output will look similar to this:

This utility will help you create a new Domain
Press ^C at any time to quit.
? friendly name Acme Corp
? domain uri (e.g acme.com) sip.acme.com
? egress number none
? egress rule .*
? ready? Yes
Creating domain Acme Corp... Jny9B_qaIh

⚠️ In the demo server, you don't need to own the Domain. Any available URI is fair game!

Using the API to make a call

To make a call, you need install the SDK.

Install the SDK, from within the voiceapp, with:

npm install --save @fonoster/sdk

Next, create the script call.js with the following code:

// This will load the SDK and reuse your Fonoster credentials
const Fonoster = require("@fonoster/sdk");
const callManager = new Fonoster.CallManager();

// Few notes:
//  1. Update the from to look exactly as the Number you added 
//  2. Use an active phone or mobile
//  3. Replace the webhook with the one from your Ngrok
callManager.call({
 from: "9842753574",
 to: "17853178070",
 webhook: "https://5a2d2ea5d84d.ngrok.io",
 ignoreE164Validation: true
})
.then(console.log)
.catch(console.error);

Finally, run your script with: node call.js

If everything goes well, you will start seeing the output in the console you are running your Voice Application. You will also receive a call that will stream a "Hello World," which further confirms that everything is behaving as it should.

Troubleshooting

1. Are you not receiving the call at all?

The first thing to check is that your SIP Service Provider configuration is correct. Next, double-check the username, password, and host. If your Provider has an Admin console, check if you can see the registration from Fonoster.

Next, make sure the from matches the Number given to you by your Provider. Also, double-check the to has the correct prefix (for example, +1, etc.).

2. You receive the call but immediately hang up (did not hear a sound)

First, verify that Ngrok is still running. Next, compare Ngrok's URL with the webhook on your Number. They both need to match!

Then observe the console's output where your Voice Application is running, and see if there are any errors.

Giving feedback to Team Fonoster

We want to provide you with the best possible experience. To do that, we need your valuable feedback. Because we know you are busy, we provide two ways to get quick feedback from you. From the command line, use the fonoster bug command to start a GitHub issue. Or, you can use the fonoster feedback command to complete a short survey (which takes less than 30 seconds).

fonoster / fonoster

🚀 The open-source alternative to Twilio.

How we created an open-source alternative to Twilio and why it matters

Pedro Sanders — Fri, 02 Jul 2021 10:55:00 +0000

Last year, when I started assembling Team Fonoster, I published a post on Reddit that sparked a great conversation and placed Fonoster on Github's trending list even though we didn't have much to show.

fonoster / fonoster

🚀 The open-source alternative to Twilio.

As a result, I had the opportunity to interview dozens of CTOs from companies worldwide and speak with several investors who were interested in the idea of an open-source stack of Programmable Telecommunications.

In the interviews, I found we need an innovative approach to a cloud-based stack for Programmable Telecommunications.

Why we needed CPaaS in the first place?

Building an application that takes advantage of the existing Telecom network has always been a difficult task compared with, for example, building a web-based application.

This is difficult because it involves a particular set of skills that is challenging to find and can get really costly.

Let's face it, no one wants to read through dozens of RFCs to program a phone call.

So, when the API era arrived along with UCaaS and CPaaS providers, it was a no-brainer to use one of those providers to deploy a solution within weeks instead of spending months only to get a simple use-case.

So what's wrong with traditional CPaaS?

There is nothing wrong with traditional CPaaS. In fact, in most cases, using a CPaaS is a great option to deploy a Telecommunications solution.

However, even though the concept of using a CPaaS to go to market quickly is fantastic, it comes at a high price for some use-cases. After all, if something goes wrong, you will have no other option but to migrate to another CPaaS or build your own solution and start again on square zero.

Some companies complain about the high prices for using a CPaaS. A startup CTO once told me, “It almost feels that we are paying for a lot of features we don't need.” This is because, with a traditional CPaaS, you start on a pay-as-you-go model, but costs can quickly get out of control.

Other companies find themselves limited by their providers' features because with traditional CPaaS you have no option but to use what they have available. There is no chance for customization. And even though that's not a problem for most companies, it is a deal-breaker for technology companies.

Then you have use-cases, especially in the healthcare industry, that can't benefit from using a traditional CPaaS due to privacy concerns and local regulations.

In which of those categories does your company fall?

How can we make this better?

The primary innovation of Fonoster lies in researching and developing the means for creating a highly portable, cloud-based Programmable Telecommunications stack.

This Programmable Telecommunications stack will allow businesses to call an API to dial, answer a call, establish a video session, send SMS, etc. There won't be any concern about what servers and networks are doing with that information in the background.

Our overall approach to building Fonoster is to use existing open-source solutions that are best in their class when possible and build our own when necessary. We then integrate this individual open-source software into a cohesive set of APIs that resembles a traditional CPaaS.

For example, to start a simple Voice Application one could write a Javascript code like the one below:

const { VoiceServer } = require("@fonoster/voice");

const serverConfig = {
  pathToFiles: `${process.cwd()}/sounds`,
};

new VoiceServer(serverConfig).listen(
  async (req, res) => {
    console.log(req);
    await res.answer();
    await res.play(`sound:${req.selfEndpoint}/sounds/hello-world.sln16`);
    await res.hangup();
  }
);

Or to make a call to the telephone network, you could use the SDK and write a simple script like this:

const Fonoster = require("@fonoster/sdk");
const callManager = new Fonoster.CallManager();

callManager.call({
 from: "9842753574",
 to: "17853178070",
 webhook: "https://5a2d2ea5d84d.ngrok.io"
})
.then(console.log)
.catch(console.error);

Want to create a reminders application? No problem, in few easy steps, you can create and deploy a Cloud Function that will run based on a given Cron schedule.

First, initialize your Cloud Function with:

fonoster funcs:init

Then, edit the handler with the following code:

const Fonoster = require("@fonoster/sdk");
const callManager = new Fonoster.CallManager();

// 🚀 Let's get started
// Use fonoster funcs:deploy to send to the cloud functions
module.exports = async(request, response) => {
  await callManager.call({
    from: "9842753589",
    to: "17853178070",
    webhook: "https://5a2d2ea5d84d.ngrok.io"
  })
  return response.succeed("OK");
};

Finally, deploy to the Cloud Functions subsystem with a Cron string.

fonoster funcs:deploy --schedule "*/5 * * * *"

You get the idea.

The Cloud Functions capability if offered by the integration with OpenFaaS (by Alex Ellis)

What's next?

Be sure to check The essentials of building Voice Applications with Fonoster to overview the Programmable Voice features available on Project Fonoster. Star the project on Github and contact us via:

Twitter: @fonoster
Email: [email protected]">[email protected]
Slack channel