XCALLY App Setup your Push Gateway

On this page

📋 What’s about

To use XCALLY Mobile App, it is necessary to configure your own push gateway by following these guidelines and when you create Mobile Agents in Staff Section you will need to specify your Push Gateway Address (we'll see in this guide what settings to enter based on the scenario you choose)

The XCALLY Push Gateway, consists of different modules:

Flexisip that includes:
- a SIP proxy specifically used to handle SIP communications: via SIP comes the registration from a mobile phone and the push gateway takes the register notification and sends it to XCALLY server, which responds to push gateway and push gateway responds to mobile);
- Push Notification system: when the app is in the background, the call comes to XCALLY and it's necessary to resume the app to manage the call. So there is a notification system that contacts Apple Push Notification which sends a notification to the agent's mobile. Device receives the Push Notification and agent can manage the call;
Redis Cache system used to keep in memory foreground and background devices;
Redis Insight: cache dashboard to view what mobiles connected on database. By default dashboards are installed, so you can hook up your database, and if you have mobiles connected, you will see them on dashboard cache.

These modules are run through the docker, so container where the application runs regardless of the operating system. In fact the XCALLY App Flexisip Docker aims to build a Docker image based on Debian 12 with Flexisip, within a Dockerized environment for improved scalability and manageability.
Since you need to run multiple containers, it’s possible to use docker-compose.yml: you define the containers to run (with their variables, ports...) and launching docker compose file (available below), the 4 modules will be executed automatically. So in next sections you can find instructions on how to launch the docker compose file.

📁 Configuration folders and scenarios

To configure the push gateway you have to download the following archive, firstly choosing if you want to install the push gateway:

on another machine (our recommended choice) if you want to use the same push gateway for multiple servers or multiple clients (by opening port 5060 or 5061 on all servers).
Moreover, for security reasons, in this way the push gateway is isolated.

on the same XCALLY server

Moreover as transport protocol, you can decide if you want to use UDP/TCP or TLS protocol with secure certificate.

Requirements

In Settings/Networks section you need to correctly set your localNET and ExternIP (that you can retrieve by launching the command curl https://ifconfig.me/ipand from the output you will be able to copy your IP (the string e.g. 11.222.33.444)
Hardware with minimum 1 CPU and 2 GB RAM (but always consider that this depends on the expected traffic)
You can use all operating systems, that support the required Docker Engine for example Debian
You will download the file published in this page (with or without tls depending on your needs) in tmp.
When you will dearchived it by launching the command -c, file will be inserted in /etc push gateway folder
If you want to use TLS, you need to retrieve files of certificates data: KeyCert and CertFile, that you will need when you configure the flexisip.conf file
Before running the docker compose file:
- ensure that Docker Engine is installed on the system where you want to run the containers.
  To verify if the Docker is already installed, you can launch the command docker - v and the output will show you the installed Docker version:
  motion@xc-aws-mil-dev-xc01:~$ docker -v
  Docker version 24.0.7, build afdd53b
  If you install the push gateway on an other machine and this error appears bash: docker: command not found, you can follow the Debian documentation at this link to install the Docker: https://docs.docker.com/engine/install/debian/
  (If you prefer to use an operating system different than Debian, you need to consider the relative docker commands documentation)
- ensure that Docker Compose is installed, as the docker-compose.yml file will be used to manage the containers.
  To verify if the Docker Compose is correctly installed you can launch the command docker compose version and the output will show you the installed Docker compose version:
  motion@xc-aws-mil-dev-xc01:~$ docker compose version
  Docker Compose version v2.21.0
  If the command is not found, you can launch this command to install it as user no root (configured with permission to launch docker): sudo apt-get install docker-compose-plugin

Environment Variables Configuration:

Some environment variables are required for the services to function correctly. Make sure that they are correctly configured before running the file:
- DEBUG_LEVEL=info | debug level for the push gateway
- TOKEN_KEY=xcally.p8 | Token key for authentication
- TOKEN_KEY_ID=X4R3256H89 | Token key ID
- TOKEN_TEAM_ID=7WCL6FH953 | Team ID of the token

⚙️ Configuration Steps

📁 Archive to download

ZIP TO DOWNLOAD
XXXXXX

With the command wget, you can directly download the zip file on the server → command to unarchive and launch it.

SCREEN

The push gateway folder will be created. To enter the folder, run the command cd push-gateway

COSA MANCA???

🔧 Building and Running the Docker Image

The following directory and file structure is included:

conf/: Contains Flexisip configuration files, Apple Push Notification (APN) certificates, and TLS certificates.
flexisip.conf: Main configuration file for Flexisip. Refer to the official Flexisip Configuration Reference Guide for detailed explanations of configuration parameters.
The xc-flexisip container is configured to use the host network, which exposes TCP and UDP ports externally. By default, ports 5060 (for SIP) and 5061 (for TLS) are exposed. Modify these
ports in the configuration as required for your XCALLY environment.

Consider that if you want to configure push gateway on the same server, in SIP protocol the used default ports are 5060 (for UDP/TCP) and 5061 (for TLS), but on XCALLY the Stack SIP is already present with Asterisk. So if you use the same server, for the Stack SIP it’s necessary to insert other ports (e.g. 9999 for TLS and 9998 for TCP/UDP.

To run the docker image, follow these steps:

Open a terminal or command prompt
Open the docker-compose.yml file with a text editor. Modify, if necessary, the environment variables published in requirements
As ports you can view this configuration
In the directory where the file is located, run the Docker Compose Command to start the containers:

docker compose up -d --build

With this command, Docker Compose will start the containers in the background

The Docker Compose setup includes:

redis: Used for Flexisip's cache management
redisinsight: A tool to visualize and manage Redis content on dashboard

Add xc-redis Database in RedisInsight

On the first launch, add the xc-redis database in RedisInsight for Redis cache management

Modify flexisip.conf file

Retrieve your public IP address and modify the file by updating the following line:

redis-server-domain=your_public_ipv4

You need to retrieve the public IP: to do that, you can launch the command curl https://ifconfig.me/ip
From the output you will be able to copy your IP (the string 11.222.33.444)

Modify Transports Configuration: update the transports line in the file with your public IP and docker private IP

transports=sip:your_public_ipv4:5060;maddr=your_private_ipv4

If you install the flexisip on the same machine, you can set 5060 as port, if you have a separated server, you need to indicate the chosen port e.g. 9998

If you are using AWS, you can retrieve the private IP by running the following command:

curl http://169.254.169.254/latest/meta-data/local-ipv4

Consider that UDP protocol is not supported and usage could cause potential performance issues and functionality problems, such as CallerID not being displayed correctly in push notifications. So on your mobile agents, select only TCP transport.

Enable TLS Support

To enable TLS encryption, first of all upload your TLS certificates to the conf/tls directory and configure their paths in the flexisip.conf file.

If you want to use TLS line, add a # to comment the line related to TCP and enable the TLS line

update the transports line in the file with your public IP, docker private IP and include the indication of your domain with certificates and TLS number port

transports=sip:your_public_ipv4:5060;maddr=your_private_ipv4
sips:your_domain_name:5061;maddr=your_private_ipv4

If you install the flexisip on the same machine, you can set 5061 as TLS port, if you have a separated server, you need to indicate the chosen port e.g. 9999

Below you can see rows related to upload certificates, so you need to indicate the same name of .crt file and .key file inserted in the folder

tls-certificates-file=path_to_cert
tls-certificates-private-key=path_to_key

Flexisip uses a registration mechanism:

in reg-domains you indicate which domains registrations are accepted from: * means from all domains, but it is possible to specify the desired domain.
max/min expires indicates the number of minutes for which the app is kept active (in this case 7 days)

APN Certificate for Apple Push Notifications

The conf/apn directory contains the com.xcally.mobile.voip.prod.pem certificate used for Apple Push Notifications. It is essential to regenerate and share this certificate with clients annually to ensure continued compatibility and functionality.

📊 Access RedisInsight

RedisInsight is the module installed in the docker compose file to view cache content (it works as cache dashboard).

Once running, you can access the RedisInsight web interface by opening your browser and navigating to:

http://serverIP:5540

As serverIP you need to indicate the IP of the push gateway machine

By default it is created without database and you need to add it. Click on Add Redis Database and insert:

host : xc-redis
use the default port
define the desired alias
you can test connection

Add database

Every time a mobile app is connected, you will see all the keys saved in cache memory.

The services are now running and ready to be used.

🔥 Configure the firewall

It’s necessary to configure the firewall to accept requests arriving on different ports:

5060 for TCP/UDP (mandatory to make it work)
5061 for TLS (mandatory to make it work)
10000-20000 for RTP stream to allow the voice connection. These ports are open during the call but they are used by Asterisk only after having negotiated ports with external phones
5540 for RedisInsight: optional if you want to reach the service from the web to view cache dashboard

👥 XCALLY Agent Mobile Configuration

When you create Mobile Agents in Staff Section you will need to specify your Push Gateway Address with the correct port.

In Staff → Agents → Edit Mobile Agent → Mobile App section → Mobile App Push Gateway you need to specify your push gateway address, so the server on which you have installed the push gateway + the port used for it. Remember that if you decide to use a different port in the file, you need to specify it also here, by replacing the 5060 with the selected one:

For TCP: installed on other server XX.XXX.XXX.XX:5060 | installed on same server XX.XXX.XXX.XX:9998

For TLS: installed on other server e.g. flexisip.xcally.com:5061 | installed on same server flexisip.xcally.com:9999
In fact consider that if you want to use TLS protocol (being a secure protocol that requires a certificate) the registered domain must be that of the certificate, so in this field you can apply only the certified domain and not the IP.

Moreover in the agent’s Voice section it’s important to configure the correct codec to ensure proper functionality, so the same transport protocol that you decide to use on push gateway:

if you use TLS, you need to select tls protocol; moreover it’s necessary to enable encryption=yes
if you use a configuration with tcp/udp, you have to select tcp option

It is recommended to avoid using the UDP protocol due to potential performance issues and functionality problems, such as CallerID not being displayed correctly in push notifications.
So if you have UDP enabled in your mobile agent, remove the option and leave only TCP transport

Logs Management

A log directory is created to store Flexisip log files. To adjust the log verbosity, modify the loglevel parameter in the flexisip.conf file:

log-level=debug

After making changes to the configuration, restart the xc-flexisip container to ensure Redis cache consistency and prevent the loss of mobile app registrations.

🔖 Repository Availability

This project is available in our Bitbucket repository at the following link

▶️ Useful commands

These common commands are useful if you need to stop or restart containers or if you want to view logs, but obviosly you need firstly to follow the procedure described above and then use these commands only if necessary

🛑 How to run and stop the containers

To start the project, use the following command:

docker compose up -d --build

To stop and remove the containers (preserving the data), run the following command in the same directory as the docker-compose.yml file:

docker compose down

This command will stop and remove all containers associated with the docker-compose.yml file.

Otherwise, to remove the whole stack (including data):

docker compose down -v

Instead, to remove the single container:

docker compose down <service name>

To verify Container Startup: to verify the status of the containers, you have to run the command:

docker compose ps

You can see the containers correctly present

➡️ How to restart the container

docker compose restart <service name>

<service name> is the name assigned within the docker-compose.yml

To recreate the single container:

docker compose up <service name> -d

👁️ How to view logs or status

To view container logs:

docker logs <container name>

To view container status:

docker stats

To access a container:

docker exec -ti <container name> /bin/bash

To exit the container, type exit.

🔄 How to update Push Gateway with a new Docker image version

When a new Docker image is available, it’s necessary to launch these commands, starting from the directory where docker-compose.yml file is located:

First of all you need to suspend the processes:

docker compose down

Then you have to download the new Docker image:

docker pull xcally/push-gateway

Finally you reactivate the processes:

docker compose up -d