Installation Guide

Requirements for HA Deployment

• Replay Server for HA Deployment

• Database for VRS metadata + Keycloak — PostgreSQL (supported from VRS 14.10.0) or SQL Server 2019–2022

• Two SIP Trunks for HA

• VRS solution on two separate machines for HA

• Keycloak for authentication:

  • EFCX: EFCX Server (Keycloak/IAM)

  • Cisco: deploy a separate Keycloak (shared by both VRS HA nodes; do not use EFCX Keycloak)

FQDN Mapping for Multi-tenancy

• An FQDN for VRS nginx in a format like vrs.<ef-cx-rootDomain> in case multi-tenancy. eg, if CX core root domain is expertflow.com, vrs root domain will be vrs.expertflow.com

• Tenant Name.ROOT DOMAIN should be routed to this vrs.expertflow.com on port 444. For example, we have two tenants, mtt01 and mtt02, and our root domain is vrs.expertflow.com. mtt01.vrs and mtt02.vrs should be routed to vrs.expertflow.com on port 444 so the VRS can be accessible on the these URLs: https://mtt01.vrs.expertflow.com:444/#/login and https://mtt02.vrs.expertflow.com:444/#/login

There are two types of installation: EFCX and Cisco (UCCX & UCCE). For EFCX, most of the steps are not required, as Keycloak, JtapiConnector, and Mixer are not required.

Allow ports in the firewall for VRS

If there is an active firewall, allow the following ports.

443/tcp
444/tcp
8088/tcp
5060/tcp (only for Cisco)
16386-32768/udp (only for Cisco)
8021/tcp
1433 /tcp
5432 /tcp


# Additional port to open in case of High Availability (HA)
8500
8300
8301 /tcp/udp
8302 /tcp/udp
8303 /tcp/udp
8600 /tcp/udp

Installation Steps

1. Please make sure that Solution Prerequisites are met for the desired deployment type. 

2. Download the deployment script deployment.sh and place it in the user’s home or any desired directory. This script will:

   1. Delete the recording-solution directory if it exists.

   2. Clone the required files for deployment

3. To execute the script, give it permissions to execute and run it as follows.

   Bash

   $ chmod 755 deployment.sh                  
   $ ./deployment.sh
   

git clone -b 14.12.0 https://gitlab.expertflow.com/voice-recording-solution/recording-solution.git

4. Follow this guide to install and configure Freeswitch. The recording path in Free SWITCH and in the Docker Compose volume must be the same.

5. Follow this guide to configure ESL. (for Pause and Resume Recording)

6. Follow this guide to create an application user on CUCM for JTAPI Connector.

7. Create databases vrs and keycloak_vrs, then run the VRS schema on vrs only:

   • PostgreSQL (14.10.0+ / 14.11.0): run data/scripts/postgres.sql against database vrs (pgAdmin Query Tool or psql -h <db_host> -U <user> -d vrs -f data/scripts/postgres.sql). 14.11.0 adds hold_time and converts tag_id to an array so a call can have multiple tags.

   • SQL Server: run data/scripts/sqlserver.sql against database vrs (SSMS or sqlcmd). 14.11.0 stores tag_id as a JSON array and adds hold_time. Rename any leftover CallVariable1–10 columns to call_variable1–10.

   Leave keycloak_vrs empty — Keycloak creates its own tables. See also the VRS Upgrade Guide from 14.10.0 to 14.11.0.

   Cisco only: From VRS 14.12.0, the skeleton postgres.sql / sqlserver.sql scripts on vrs already include dual archival columns (archival_setting storage fields and related session stamps). Do not run the EFCX fusionpbx SQL on the Cisco vrs database. EFCX: apply the EFCX-only fusionpbx SQL later in this guide (before install-efcx.sh).

8. Navigate to recording-solution/docker directory.

9. Open the docker-compose-cisco.yml file.

   • For non-HA deployments: Uncomment the archival-process container and keep the consul container commented.

   • For HA deployments: Uncomment the consul container and keep the archival-process container commented.
     After making the changes, save and close the file.

10. Open docker/config.env and set Keycloak database variables (do not hardcode these in docker-compose-cisco.yml): KC_DB, KC_DB_URL, KC_DB_USERNAME, KC_DB_PASSWORD.

    • PostgreSQL: KC_DB=postgres, KC_DB_URL=jdbc:postgresql://<db_host>:5432/keycloak_vrs

    • SQL Server: KC_DB=mssql, KC_DB_URL=jdbc:sqlserver://<db_host>:1433;databaseName=keycloak_vrs;encrypt=true;trustServerCertificate=true

    DB_ENGINE and KC_DB must match (postgres with postgres, or sqlserver with mssql).

11. In the same config.env, set VRS metadata DB variables: DB_DRIVER, DB_ENGINE, DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD. PostgreSQL defaults (14.10.0): org.postgresql.Driver, postgres, 5432, vrs. For SQL Server use com.microsoft.sqlserver.jdbc.SQLServerDriver, sqlserver, 1433.

12. Set KC_HOSTNAME in config.env to the recorder server IP/FQDN.

13. Save and close config.env. Keycloak image in compose is 23.0.7 (prefer 23.0.7+).

14. Run chmod 755 install-cisco.sh && ./install-cisco.sh. The script uses --env-file docker/config.env so Keycloak ${KC_*} values resolve. Verify Keycloak at http://<IP>:8088/auth.

    Security: Change the Keycloak admin console default password (admin / admin) before production use.

15. Add the following KeyCloak variables in config.env for CISCO deployment only, using the keycloak setup guide. In the case of EFCX, these variables will be commented out.

16. Open config.env in the same directory and update the environment variables given below.

Also set these Cisco / archival variables in config.env:

Set display labels for Cisco call variables call_variable1–10 (UCCE TCD Variable1–10 / UCCX customvariable1–10). Change the text to match what your call variables hold:

CALL_VARIABLE1_LABEL=Customer Name
CALL_VARIABLE2_LABEL=Extension
CALL_VARIABLE3_LABEL=Account No.
CALL_VARIABLE4_LABEL=IVR Code
CALL_VARIABLE5_LABEL=Reference ID
CALL_VARIABLE6_LABEL=Customer Type
CALL_VARIABLE7_LABEL=Branch Code
CALL_VARIABLE8_LABEL=Service Type
CALL_VARIABLE9_LABEL=Priority Level
CALL_VARIABLE10_LABEL=Campaign/Source

The below Env variables are only for UCCX.

In the same docker/config.env, set these mixer variables for Informix CRA (UCCX only):

After changing these values, recreate/restart the mixer. Place a test UCCX call and confirm wrap-up / queue / hold / call variables after the usual sync delay.

The below Env variables are only for UCCE.

17. Add the Following environment variables for pause and resume recording.

Update the Database environment variables in config.env.

Update some additional variables for either CISCO or EFCX deployment.

18. For EFCX Deployment Profile, the line <param name="url" value="http://127.0.0.1/app/xml_cdr/xml_cdr_import.php"/> in the xml_cdr.conf.xml file should be uncommented. Run the following command to open the xml_cdr.conf.xml and uncomment the above line.

nano /etc/freeswitch/autoload_configs/xml_cdr.conf.xml

Once the file is open, then uncomment the line and save it. Then restart the Freeswitch. systemctl restart freeswitch

19. For EFCX Deployment profile: The root domain vrs.expertflow.com should be mapped to the IP address of the VRS server. Ask IT to configure this.

20. Each tenant’s root domain should be routed to vrs.expertflow.com on port 444.

    For example, if we have two tenants — mtt01 and mtt02 — and the root domain is vrs.expertflow.com, then:

    • mtt01.vrs and mtt02.vrs should both point to vrs.expertflow.com on port 444.

    This will make the VRS accessible at the following URLs:

    • https://mtt01.vrs.expertflow.com:444/#/login

    • https://mtt02.vrs.expertflow.com:444/#/login

    • In the case of a Single Tenant, simply map a FQDN to the Media Server IP on port 444 to access VRS.

21. To update the self-signed certificates for VRS, get the public authority or domain signed certificate .crt and .key files, name them server.crt and server.key, and replace the files in /recording-solution/config/certificates with these two new files. Names should be the same.

22. Navigate to the recording-solution directory and assign permissions to the install script.

23. chmod 755 install-cisco.sh  #in case of CISCO
    chmod 755 install-efcx.sh   #in case of EFCX
    chmod 755 install-replay.sh #in case of HA CISCO
    

24. Perform this step only if Deployment Profile is EFCX (VRS 14.12.0+). For Cisco, dual archival columns are already included when you run the skeleton data/scripts/postgres.sql or data/scripts/sqlserver.sql on database vrs earlier in this guide. EFCX uses the Media Server fusionpbx database instead — those ALTERs are not in the recording-solution skeleton, so run them manually here before starting the stack.

    On the Media Server, note the database password:

    cat /etc/fusionpbx/config.conf | grep database.0.password
    

    Connect to fusionpbx (enter the password when prompted; use your DB host if it is not local):

    psql -h 127.0.0.1 -p 5432 -U fusionpbx -d fusionpbx
    

    Run the following SQL (dual archival settings + CDR stamps):

    SQL

    -- EFCX / fusionpbx — dual archival settings + CDR stamps
    -- Run after connecting:
    --   psql -h <db_host> -p 5432 -U fusionpbx -d fusionpbx
    
    ALTER TABLE archival_setting
      ADD COLUMN IF NOT EXISTS storage_type VARCHAR(20) NOT NULL DEFAULT 'sftp';
    
    ALTER TABLE archival_setting
      ADD COLUMN IF NOT EXISTS sftp_server_ip   VARCHAR(255),
      ADD COLUMN IF NOT EXISTS sftp_username    VARCHAR(255),
      ADD COLUMN IF NOT EXISTS sftp_password    VARCHAR(255),
      ADD COLUMN IF NOT EXISTS sftp_folder_path VARCHAR(512),
      ADD COLUMN IF NOT EXISTS s3_endpoint      VARCHAR(255),
      ADD COLUMN IF NOT EXISTS s3_access_key    VARCHAR(255),
      ADD COLUMN IF NOT EXISTS s3_secret_key    VARCHAR(255),
      ADD COLUMN IF NOT EXISTS s3_folder_path   VARCHAR(512);
    
    UPDATE archival_setting
    SET
      sftp_server_ip   = CASE WHEN COALESCE(storage_type, 'sftp') NOT IN ('s3','minio','wasabi')
                              THEN external_server_ip ELSE sftp_server_ip END,
      sftp_username    = CASE WHEN COALESCE(storage_type, 'sftp') NOT IN ('s3','minio','wasabi')
                              THEN username ELSE sftp_username END,
      sftp_password    = CASE WHEN COALESCE(storage_type, 'sftp') NOT IN ('s3','minio','wasabi')
                              THEN password ELSE sftp_password END,
      sftp_folder_path = CASE WHEN COALESCE(storage_type, 'sftp') NOT IN ('s3','minio','wasabi')
                              THEN folder_path ELSE sftp_folder_path END,
      s3_endpoint      = CASE WHEN COALESCE(storage_type, 'sftp') IN ('s3','minio','wasabi')
                              THEN external_server_ip ELSE s3_endpoint END,
      s3_access_key    = CASE WHEN COALESCE(storage_type, 'sftp') IN ('s3','minio','wasabi')
                              THEN username ELSE s3_access_key END,
      s3_secret_key    = CASE WHEN COALESCE(storage_type, 'sftp') IN ('s3','minio','wasabi')
                              THEN password ELSE s3_secret_key END,
      s3_folder_path   = CASE WHEN COALESCE(storage_type, 'sftp') IN ('s3','minio','wasabi')
                              THEN folder_path ELSE s3_folder_path END
    WHERE sftp_server_ip IS NULL
       OR sftp_folder_path IS NULL
       OR (storage_type IN ('s3','minio','wasabi') AND s3_endpoint IS NULL);
    
    ALTER TABLE v_xml_cdr
      ADD COLUMN IF NOT EXISTS archive_storage VARCHAR(16) NULL;
    
    ALTER TABLE v_xml_cdr
      ADD COLUMN IF NOT EXISTS archive_path VARCHAR NULL;
    

    See also Archival Process Configuration for EFCX.

25. Run ./install-efcx.sh for EFCX or run ./install-cisco.sh for Cisco UCCX and UCCE.

26. Run the following command to ensure all the components are running. 

    # docker ps
    

27. Once VRS is deployed with EFCX Deployment profile. Run this command on Media Server to give the permission to recording directory.

    chmod 777 -R /var/lib/freeswitch/recordings/
    

28. In the case of Cisco Deployment Profile, navigate this URL to access the Application: https://localmachineip/#/login, whereas for EFCX Deployment Profile use the FQDN / port 444 URLs from the multi-tenant (or single-tenant) mapping steps above (steps 19–20).

29. For HA-specific deployment, proceed following steps.

29. Follow this guide for the creation of an rsync job on All VMs Recorder 1, Recorder 2, and Replay Server.

30. Go to the replay server, add permission to install.sh script and then run ./install-replay.sh.

31. Configure two SIP Trunks on Cisco Call Manager in HA Mode and set priorities for both Machines.

32. Do the following steps for both recorder1 and recorder2.

33. Open recording-solution/docker/docker-compose-cisco.yml

34. Inside the docker-compose-cisco file, Uncomment the Consul Container.

35. In the container_name variable, set the name as consul1 for Recorder 1 and consul2 for Recorder 2.

36. Add your interface card. This can be found using the ifconfig or ip address command.

- CONSUL_BIND_INTERFACE=ens192   #ens192 or end32

37. In the command section, set the name of the consul in the -node=<any-name> as shown in the code snippet below. This name must be different than the second recorder.

38. Set the -advertise=<Local-Machine-IP> and set -retry-join=<IP-Second recorder> . Keep the other values as they are

#    command: "agent -node=consul-106 -server -ui -bind=0.0.0.0 -client=0.0.0.0 -advertise=192.168.1.106 -bootstrap-expect=2 -retry-join=192.168.1.101"

39. Save changes and exit.

40. Run ./install-cisco.sh

41. Check containers on both recorders using the docker ps command

42. Deploy the Recorder 2 in the same way.

43. Deploy the replay server. For the replay server, just add the config.env file. and run the ./install-replay.sh command.