Page Comparison

On this page

📋 What’s about

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.

Image Removed

 

on the same XCALLY server

Image Removed

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

Building and Running the Docker Image DA SPOSTARE SOPRA COME SPIEGAZIONE

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.

Requirements

Before running the docker compose file:

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

⚙️ Configuration Steps

📁 Archive to download

• With the command wget, you can directly download the zip file on the server → launch this command to unarchive:

tar zxvf /tmp/push-gateway.tar.gz -C /var/opt/

• The push gateway folder will be created. To enter the folder, run the command:

cd /var/opt/push-gateway

TCP Configuration

• You have to retrieve your public IP

curl https://ifconfig.me/ip 

From the output you will be able to copy your IP (the string e.g. 11.222.33.444)

• Open your favorite editor (e.g. vi or nano)

vi conf/flexisip.conf

• Modify Transports Configuration: update the transports line in the file with your public IP

quadrato giallo dove push-gateway.xcally.com:5060 da sostituire con your public IP

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

Image Removed

• Run docker container:

cd /var/opt/push-gateway
docker compose up -d

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:

on another machine (our recommended choice)

Image Added

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

Image Added

tar zxvf /tmp/push-gateway.tar.gz -C /var/opt/

cd /var/opt/push-gateway

curl https://ifconfig.me/ip 

vi conf/flexisip.conf

Image Added

• replace push-gateway.xcally.com with your public IP

• if you install the flexisip on a separated server, you can indicate as chosen port 5060 (recommended choice), if you use the same machine, you can set as port e.g. 9998

cd /var/opt/push-gateway
docker compose up -d

• 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

TLS Configuration

Copiare certificati

/var/opt/push-gateway/tls

vi conf/flexisip.

confImage Removed

conf

• Modify Transports Configuration in the file:

Image Added

• replace push-gateway.xcally.com

SOSTITUITO CON your domain
xcally.crt e xcally.key sostituiti con your KeyCert and your Cert with Chain (only 1 file IN THE SAME FILE)

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

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

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

• Now launch this command

Code Block
cd /var/opt/push-gateway docker compose up -d

🛑 How to run and stop the containers

Note
To launch this commands you always need to be in the folder /var/opt/push-gateway

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

Code Block
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):

Code Block
docker compose down -v

 

Instead, to remove the single container:

Code Block
docker compose down <service name>

 

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

Code Block
docker compose ps

You can see the containers correctly present

➡️ How to restart the container

Code Block
docker compose restart <service name>

 

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

To recreate the single container:

Code Block
docker compose up <service name> -d

 

👁️ How to view logs or status

To view container logs:

Code Block
docker logs <container name>

 

To view container status:

Code Block
docker stats

 

To access a container:

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

To exit the container, type exit.

Image Removed

• 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

Info
This is an optional step

 

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:

Code Block
http://serverIP:5540

Info
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 Sectionyou will need to specify your Push Gateway Address with the correct port.Image Removed

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

Image Removed

• 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

Info
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

To view logs of flexisip:

Code Block
cd /var/opt/push-gateway/log tail -f flexisip-proxy.log

▶️ Useful commands

InfoThese 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

• with your domain with certificates

• indicate your TLS number port: if you install the flexisip on a separated server, you can indicate as chosen port 5061 (recommended choice), if you use the same machine, you you can set as port e.g. 9999

• replace xcally.crt and xcally.key with your Cert with Chain and KeyCert paths

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

• Now launch this command to run the docker container:

Code Block
cd /var/opt/push-gateway docker compose up -d

▶️ Useful commands

Info
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

Note
To launch this commands you always need to be in the folder /var/opt/push-gateway

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

Code Block
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):

Code Block
docker compose down -v

 

Instead, to remove the single container:

Code Block
docker compose down <service name>

 

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

Code Block
docker compose ps

You can see the containers correctly present

➡️ How to restart the container

Code Block
docker compose restart <service name>

 

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

To recreate the single container:

Code Block
docker compose up <service name> -d

 

👁️ How to view logs or status

To view container logs:

Code Block
docker logs <container name>

 

To view container status:

Code Block
docker stats

 

To access a container:

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

To exit the container, type exit.

Image Added

• 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.

🔥 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 Sectionyou will need to specify your Push Gateway Address with the correct port.

Image Added

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

Image Added

• 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

Note
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

To view logs of flexisip:

Code Block
cd /var/opt/push-gateway/log tail -f flexisip-proxy.log

📊 Access RedisInsight

Info
This is an optional step

 

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

• Add xc-redis Database in RedisInsight

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

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

Code Block
http://serverIP:5540

Info
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.