Push Gateway on the same server

Owned by Product Knowledge
Last updated: Oct 17, 2024
7 min read

 

This documentation is work in progress

 

What’s about

This scenario occurs if you decide to install the push gateway on the same machine.

image-20240905-160853.png


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

  • Retrieve your public IP and PushGatewayDnsName to enter then in Drachtio configuration

  • If you want to use TLS, you need to retrieve these 3 files of certificates data: KeyCert, CertFile and ChainCert, that you will need when you configure the Drachtio Conf file

  • Before running the docker compose file:

    • ensure that Docker Engine is installed on the system where you want to run the containers. If for the push gateway you use the same XCALLY server, Docker Engine is installed by default.
      To verify the Docker installation, 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

    • ensure that Docker Compose is installed, as the docker-compose.yml file will be used to manage the containers. By using the same machine, Docker Compose is installed by default.
      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

  1. Environment Variables Configuration:

  • Some environment variables are required for the services to function correctly. Make sure to configure them properly before running the docker compose 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.

Video Tutorial - same server with TLS

In this video you will see the scenario in which you choose to install the push gateway on the same server with TLS
Let’s see the steps to follow:

https://app.guidde.com/share/playbooks/fSgLJs25JdD9LEckywdFHm?origin=3wPlti10dEfOGQjG7BKQvB2q4IC3

List of commands:

  • tar zxvf push-gateway-same-machine.tar.gz -C /etc

  • cd /etc/push-gateway

  • curl https://ifconfig.me/ip

  • cd ssl
    ls -la

  • nano conf/drachtio.conf.xml

  • docker compose up -d

  • docker compose ps

Archive to download

ONLY WITH UDP/TCP

WITH TLS

ONLY WITH UDP/TCP

WITH TLS

 

  • You need to open the desired file on your Linux machine and you will see it in this way:

image (8)-20240906-154131.jpg

  • You have to unarchive the file:

    • by launching the command tar zxvf push-gateway-same-machine.tar.gz if you use the folder only with UDP/TCP

    • by launching the command tar zxvf push-gateway-same-machine-tls.tar.gz if you use the TLS

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

  • Then you need to launch command nano conf/drachtio.conf.xml to edit file in conf folder for Drachtio configuration in which you will need to specify your public IP and Push Gateway Dns Name

To retrieve the public IP of your server, 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)

Drachtio Conf with TLS

<drachtio>         <admin port="9022" secret="cymru">0.0.0.0</admin>   <sip>     <contacts>       <contact dns-names="YourPushGatewayDnsName" external-ip="YourPushGatewayPubblicIp">sips:*:9999;transport=tls</contact>       <contact dns-names="YourPushGatewayDnsName" external-ip="YourPushGatewayPubblicIp">sip:*:9998;transport=udp,tcp</contact>     </contacts>     <tls>       <key-file>/etc/ssl/xcally/YourKeyCertFile</key-file>       <cert-file>/etc/ssl/xcally/YourCertFile</cert-file>       <chain-file>/etc/ssl/xcally/YourChainCertFile</chain-file>       <dh-param>/etc/ssl/xcally/dh2048.pem</dh-param>     </tls>   </sip>   <logging>      <console/>      <sofia-loglevel>3</sofia-loglevel>      <loglevel>info</loglevel>   </logging> </drachtio>

In file drachtio.conf.xml you need to:

  • insert YourPushGatewayDnsName in contact dns-names section

  • insert YourPushGatewayPublicIp in external-ip section

After you unarchived the file, automatically you will have the folder /etc/pushgateway/ssl, where you need to move your certificate data and it’s mandatory to have these 3 files: KeyCert, CertFile and ChainCert

  • so in tls section, specify:

    • YourKeyCertFile

    • YourCertFile

    • YourChainCertFile

 

Drachtio Conf without TLS

<drachtio>     <admin port="9022" secret="cymru">0.0.0.0</admin>   <sip>     <contacts>       <contact dns-names="YourPushGatewayDnsName" external-ip="YourPushGatewayPubblicIp">sip:*:9998;transport=udp,tcp</contact>     </contacts>   </sip>   <logging>      <console/>      <sofia-loglevel>3</sofia-loglevel>      <loglevel>info</loglevel>   </logging> </drachtio>

In the file drachtio.xonf.xml you need to:

  • insert YourPushGatewayDnsName in contact dns-names section

  • insert YourPushGatewayPublicIp in external-ip section

 

 

Run the docker-compose.yml

To run the docker-compose.yml file, 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

ports: - 9999:9999 - 9998:9998 - 9998:9998/udp

 

  • In the directory where the docker-compose.yml file is located, run the Docker Compose Command to start the containers:

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

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

You can see the 4 containers correctly present

  • Ensure all services listed in the docker-compose.yml file are running correctly

At the end of the process you will have:

  • push-gateway for notification system

  • redis for cache

  • redisinsight for dashboard

  • drachtio for the stack SIP. As we have seen, you can indicate as ports for UDP/TCP the 9998 and for TLS the 9999, but if you prefer, you can decide to change it (in this case remember to use this information also in mobile agent configuration and to edit them in the drachtio conf file that we’ve analysed above).

  • volumes configuration

  • logging data for logs file

  • restart : always = if the container crashes, it automatically restarts

  • networks section

 

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:

By default it is created without database and you need to add it, by inserting

  • host : 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. You can interact with the push gateway, the Redis server, and the Drachtio server as required.

Configure the firewall

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

  • 9998 for Drachtio TCP/UDP

  • 9999 for Drachtio TLS

  • 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

How to configure Mobile Agents

In this scenario, 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 the push gateway address, that in this case is your IP/XCALLY server address (the same machine you are using) + the specific port used for push gateway (e.g. myxcallyaddress:9999)

 

Moreover in the agent’s Voice section it’s important to use the same Transport protocol that you decide to use on push gateway.

We recommend to use both udp,tcp options if you use a configuration without tls

If you use TLS, you need to select tls protocol as transport.

 

 

Moreover for TLS it’s necessary to enable encryption