Page Comparison

On this page

Table of Contents

minLevel	1
maxLevel	23
outline	false
style	none
type	list
printable	false

📋 What’s about

Note

The XCALLY Flexisip Docker Project aims to build a Docker image based on Debian 12 with Flexisip. Flexisip is

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 (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

for handling SIP communications and Apple
Push Notifications for the XCALLY mobile app. This project ensures a simple setup to integrate Flexisip

- 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 Added

on the same XCALLY server

Image Added

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

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)
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 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

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
- DRACHTIO_HOST=drachtio | Host address of the Drachtio server
- DRACHTIO_PORT=9022 | Port of the Drachtio server
- DRACHTIO_SECRET=cymru | Secret for the Drachtio server

Remember that if you decide for any reason to define another drachtio host, port, or secret, these data must also be changed in the variables above.

⚙️ 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.

🔧 Building and Running the Docker Image

To build and run the Docker image for the project, execute the following command in your terminal

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

Code Block
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 .

⚙️ Configuration Steps

Retrieve Public IPon 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 yourpublic IP addressand modify the flexisip.conf file by updating the following line:

Code Block
redis-server-domain=your_public_ipv4

Add xc-redis Database in RedisInsight

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

Modify Transports Configuration

Update

Info
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`)

Image Added

Modify Transports Configuration: update the transports line in the

flexisip.conf

file with your public IP and docker private

IPs:

IP

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

Info

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

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

Note
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 as shown below:

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

Update the transports line to include the TLS port:.

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

Image Added

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

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

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

Image Added

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.

➡️ Running and Stopping the Project

To start the project, use the following command:

Code Block
docker compose up -d --build

To stop the project, run:

Code Block
docker compose down

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.

👥 XCALLY Agent Mobile Configuration

In the XCALLY mobile agent configuration, set the Push Gateway field with the appropriate domain or IP, followed by the port:

For TCP: 35.180.251.85:5060
For TLS: flexisip.xcally.com:5061

Remember to configure the correct codec in the Voice section (tab) to ensure proper 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:

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 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
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
A log directory is created to store Flexisip log files. To adjust the log verbosity, modify the loglevel parameter in the flexisip.conf file:

Code Block
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 repositoruy repository at the following link

▶️ 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

To start the project, use the following command:

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

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
🔄 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:

Code Block
docker compose down

Then you have to download the new Docker image:

Code Block
docker pull xcally/push-gateway

Finally you reactivate the processes:

Code Block
docker compose up -d

Version	Old Version 2	New Version 3
Changes made by	Product Knowledge	Product Knowledge
Saved on	Dec 18, 2024	Dec 19, 2024

Page Comparison

Versions Compared

Key

📋 What’s about

📁 Configuration folders and scenarios

Requirements

⚙️ Configuration Steps

📁 Archive to download

🔧 Building and Running the Docker Image

🔧 Building and Running the Docker Image

⚙️ Configuration Steps

➡️ Running and Stopping the Project

👥 XCALLY Agent Mobile Configuration

📊 Access RedisInsight

🔥 Configure the firewall

👥 XCALLY Agent Mobile Configuration

Logs Management

🔖 Repository Availability

▶️ Useful commands

🛑 How to run and stop the containers

➡️ How to restart the container

👁️ How to view logs or status

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