Versions Compared

Version Old Version 11 New Version 12
Changes made by

Product Knowledge

Product Knowledge

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

On this page

Table of Contents
minLevel1
maxLevel3
outlinefalse
stylenone
typelist
printablefalse

📋 What’s about

Note

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 Sectionyou will need to specify your Push Gateway Address

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;
      Refer to the official Flexisip Configuration Reference Guide for detailed explanations of configuration parameters of flexisip.conf

  • 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.
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 zip file reported below, firstly choosing if you want to install the push gateway:

on another machine (our recommended choice)

image-20240905-160135.pngImage Removedimage-20250114-155738.pngImage 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-20240905-160651.pngImage Removedimage-20250114-155826.pngImage Added

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

Info

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

(blue star) Requirements

Panel
bgColor#EAE6FF

  • 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 thisdepends on the expected traffic)

  • As operating system, we recommend to use Debian

  • If you want to use TLS, you need to retrieve files of certificates data: Cert with Chain (in a unique file) and KeyCert,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 versionand 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

⚙️ Configuration Steps

📁 Archive to download

ZIP TO DOWNLOAD

View file
namepush-gateway.tar.gz

  • With the command wget, you can directly download the zip file on the server

  • Launch this command to unarchive:

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

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

Code Block
cd /var/opt/push-gateway

Then you have to choose if you want to configure TCP or TLS. Explore the relative documentation to know the configuration procedure

🔧 TCP Configuration

  • You have to retrieve your public IP

Code Block
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 editor (e.g. vi or nano) and configure the flexisip.conf file:

Code Block
vi conf/flexisip.conf

  • Modify Transports Configuration in the file:

image-20250114-153332.png

  • 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

  • Run docker container:

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

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

🔧 TLS Configuration

If instead, you want to use TLS, you need to copy your certificates data: KeyCert and Cert with Chain,that you will need when you configure the flexisip.conf file

  • Enter in the folder and upload your TLS certificates:

Code Block
/var/opt/push-gateway/tls

  • Open your favorite editor (e.g. vi or nano) and configure the flexisip.conf file:

Code Block
vi conf/flexisip.conf

  • Modify Transports Configuration in the file:

image-20250114-154311.png

  • replace push-gateway.xcally.com 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-20240614-073957.png

  • 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-20240905-103018.png

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-20240906-073837.png

  • 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

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

(info) Logs Management

To view logs of flexisip:

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