Skip to content

Latest commit

 

History

History
298 lines (210 loc) · 10.1 KB

README.md

File metadata and controls

298 lines (210 loc) · 10.1 KB

Contribute with Gitpod Sponsor this Discord GitHub Twitter Follow

Routr is a lightweight sip proxy, location server, and registrar that provides a reliable and scalable SIP infrastructure for telephony carriers, communication service providers, and integrators.

Table of Content

Community

We are building Routr in the open. The best to communicate with us via GitHub Discussions.

Special Announcement:

We now have a Discord Channel
There we plan to discuss roadmaps, feature requests, and more
Join us today

Features

Routr's main features are:

  • Common SIP Server functions; Proxy, Registrar, Location Service
  • Programmable routing
  • Load balancing strategies against Media Servers like Asterisk and FreeSWITCH
  • Session Affinity
  • Multi-Tenant/Multi-Domain with Domain level Access Control List
  • Region-based routing
  • Configurable routing strategies; Intra-Domain, Domain Ingress, Domain Egress, and Peer Egress
  • No single point of failure
  • Transport: TCP, UDP, TLS, WS, WSS
  • In-memory and Redis Location Service
  • JSON and YAML files as a data source
  • Postgres as a data source
  • Server management with the gRPC API
  • NodeSDK
  • Command-Line Tool
  • RTPEngine Middleware
  • Helm Chart for Kubernetes Deployments
  • Endpoint Authentication with JWT (For web phones)
  • Support for STIR/SHAKEN
  • Web Application

To learn more, read the documentation 📚

The official handbook

This handbook offers a detailed information about of the innovative features, challenges, and opportunities associated with using Routr.

Get the eBook.

Give a Star! ⭐

If you want to support this project, please give it a star. Thanks 🙏

Deployment

Instant server deployment with Docker and Compose

First, create a directory named "routr". Navigate into the new folder, and then copy the content below:

Filename: docker-compose.yml

version: "3"

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

volumes:
  shared:

Then, start the server with:

# Be sure to replace with your IP address
DOCKER_HOST_ADDRESS=192.168.1.3 docker-compose up

Wait a few seconds for the containers to initialize. Afterward, you can verify the status of the containers using:

docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Status}}'

You should see a container with the status "Up." It should look like the one below:

CONTAINER ID  IMAGE                                     STATUS
6c63fd573768  fonoster/routr-one:latest                 Up About a minute

If the status of your services is "Up," you are ready to go.

Finally, install the command-line tool and start building your SIP Network.

You can install the tool with npm as follows:

npm install --location=global @routr/ctl

And here is an example of creating a SIP Domain:

rctl domains create --insecure

The --insecure flag is required as we did not set up the TLS settings.

For additional examples, refer to the command line documentation.

Kubernetes

Routr can be installed in Kubernetes using Helm. The following instructions assume that you have a Kubernetes cluster up and running.

You can use Minikube or Docker Desktop to create a local Kubernetes cluster.

First, add the Helm repository:

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

Then, create a namespace for Routr:

kubectl create namespace sipnet

Next, install Routr with the following command:

helm install sipnet routr/routr-connect --namespace sipnet

Finally, wait a few minutes for the pods to start. You can check the status of the pods with the following command:

kubectl get pods -n sipnet

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

For more details, please refer to the chart's README.

Deploying in development mode with Gitpod

Routr's one-click interactive deployment will familiarize you with the server in development mode.

Open in Gitpod

To connect to your instance, follow these steps:

First, add your public SSH keys to your Gitpod account by going to Gitpod account keys and adding your public key.

Next, find your Gitpod workspace and click on the "More" button. Then, select "Connect via SSH."

Finally, copy the SSH Command and run it in your terminal by pasting it and pressing Enter. The command should look like this:

ssh -L 5060:localhost:5060 <workspace-ssh-connection>

Replace with your own workspace SSH connection.

For example, your command might look like this:

ssh -L 5060:localhost:5060 fonoster-routr-mn8nsx0d9px@fonoster-routr-mn8nsx0d9px.ssh.ws-us90.gitpod.io

This command forwards traffic from your local port 5060 to your Gitpod workspace's port 5060, allowing you to access your instance.

Example configuration

Consider a situation where you want to deploy the server and send all PSTN traffic to a conference room within Asterisk. For such a scenario, you must configure a Peer to present your feature server and a Number to route calls from the PSTN.

First, start by creating a Peer configuration for your Asterisk server similar to the following one:

apiVersion: v2beta1
kind: Peer
ref: peer-01
metadata:
  name: Asterisk (Media Server)
spec:
  aor: backend:conference
  username: asterisk
  credentialsRef: credentials-01
  loadBalancing:
    withSessionAffinity: true
    algorithm: least-sessions

Notice that the loadBalancing section sets the withSessionAffinity to true. We need session affinity to ensure that all calls related to the conference arrive on the same Asterisk server. Every Asterisk server that registers with the asterisk username will join the backend:conference Address of Record (AOR).

Next, instruct Routr to map all inbound calls from a specific number to the conference room in Asterisk by setting the aorLink and sessionAffinityHeader parameters for the desired number. Here's an example:

apiVersion: v2beta1
kind: Number
ref: number-01
metadata:
  name: "(706)604-1487"
  geoInfo:
    city: Columbus, GA
    country: USA
    countryISOCode: US
spec:
  trunkRef: trunk-01
  location:
    telUrl: tel:+17066041487
    aorLink: backend:conference
    sessionAffinityHeader: X-Room-Id
    extraHeaders:
      # Appends the X-Room-Id header to all inbound calls
      - name: X-Room-Id
        value: jsa-shqm-iyo

The last scenario is one of the many possible scenarios you can accomplish with Routr (v2). Please spend some time getting familiar with the configuration files.

Bugs and Feedback

For bugs, questions, and discussions, please use the Github Issues

Contributing

For contributing, please see the following links:

Sponsors

We're glad to be supported by respected companies and individuals from several industries.

Find all our supporters here

Become a Github Sponsor

Authors

License

Copyright (C) 2023 by Fonoster Inc. MIT License (see LICENSE for details).