/
Installation Guide

Installation Guide

 

Internet should be available on the machine where the application is being installed, and connections on port 9242 should be allowed in the network firewall to carry out the installation steps.

All the commands start with a #, indicating that root user privileges are required to execute these commands. Trailing # is not a part of the command.

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

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

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

This command will clone the skeleton project: recording-solution. This recording-solution directory contains all the required files for deployment. It will be cloned in the same place as the deployment script is placed.

Now, our cloning has been completed. Our VRS files, deployment files, and directories have been downloaded. We can proceed to configure it.

14.11.0: deployment.sh clones branch 14.11.0. If you clone the files yourself:

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

Confirm with cd recording-solution && git branch --show-current — it should print 14.11.0.

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

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

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

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

  5. Navigate to recording-solution/docker directory.

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

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

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

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

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

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

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

 

Names

Description

 

Names

Description

1

KEYCLOAK_REALM_NAME

Usually VRS. Must match Keycloak realm exactly (case-sensitive). Follow Keycloak setup guide for a new realm.

2

KEYCLOAK_CLIENT_ID

Usually vrs. Must match Keycloak client.

3

KEYCLOAK_CLIENT_SECRET

From Keycloak → Clients → vrs → Credentials (follow Keycloak setup guide).

4

KEYCLOAK_URL

Internal URL for backend: http://keycloak:8080/

5

KEYCLOAK_ADMIN_USERNAME

Keycloak admin console user (default admin — change before production)

6

KEYCLOAK_ADMIN_PASSWORD

Keycloak admin console password (default admin — change before production)

7

KEYCLOAK_PERMISSION_GROUP

Usually AGENT_GROUP (Finesse gadget)

8

KC_HOSTNAME

Hostname Keycloak advertises (recorder IP/FQDN)

9

KC_DB

postgres or mssql — set in config.env (not compose)

10

KC_DB_URL

Full Keycloak JDBC URL for keycloak_vrs

11

KC_DB_USERNAME

Keycloak DB username

12

KC_DB_PASSWORD

Keycloak DB password

14.11.0 tagging: all users can view tags. Create the realm role evaluatetag and assign it to users who should assign or unassign tags on Media Recordings. The viewtag role is no longer required. See the Keycloak setup guide and VRS Authorization & Permissions.

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

Name

Description

Name

Description

1

VRS_URL

CISCO → URL of a local machine. example, https: //192.168.1.101

EFCX → Keep it as “http”

2

TZ

Time Zone. e.g, Asia/Karachi

3

LOCAL_MACHINE_IP

CISCO → Local machine IP. example 192.168.1.101 *

EFCX → FQDN that is mapped to Media Server IP (only used for on-prem Single Tenant deployment). For Multi-Tenant this variable will be commented out.

4

EFCX_FQDN

CISCO → This variable is no longer required for VRS 14.6.1 and later deployments; keep it commented out.

EFCX → FQDN of EFCX. e.g. https://FQDN. This variable is only used for Single Tenant (on-prem) Deployment

5

DEPLOYMENT_PROFILE

CISCO (for Cisco Contact Center)
EFCX (for Expertflow CX Contact Center)

6

PEER_ADDRESS

Add the IP or FQDN of the Second Recorder VM (For HA)

7

JTAPI_HA_MODE

Set it true for HA and false for Non-HA

8

SCREEN_RECORDING

If Screen recording is enabled, set it to true; otherwise, false

9

CONSUL_URL

(Only for CISCO HA) Add the IP address with port 8500 of the local machine http://192.168.1.101:8500

10

CISCO_TYPE

Type of CISCO, either UCCX or UCCE

11

DIRECTORY_PATH_TO_MONITOR

The path for the archival process to monitor should be the same path where sessions are kept, e.g, /var/vrs/recordings/cucmRecording/sessions/

12

FINESSE_URL

URL or FQDN of Finesse, e.g. https://uccx12-5p.ucce.ipcc:8445

13

RETRY_LIMIT

Limit to retry in case the connection fails. e.g 2

14

ARCHIVAL_PROCESS_NODE

active

15

CUCM_APPLICATION_USER_NAME

CUCM Application username that has been created in step 6.

16

CUCM_APPLICATION_USER_PASSWORD

Password for the CUCM Application User.

17

CUCM_IP

IP address of Call Manager

18

LICENSE_CHECKING

false (Keep it false)

19

NO_OF_DEL_DAYS

No of days after which the streams will be deleted

20

ENCRYPTION_ENABLED

Should be “true”

21

TEMP_MERGED_RECORDING_PATH

Add the complete path where files are created in the session folder. e.g. /var/vrs/recordings/cucmRecording/sessions/

22

ENABLE_AGENT_DOWNLOAD

Turns download capability on or off at the deployment level. Individual users still need the Keycloak download role; without that role the Download button stays hidden. See VRS Authorization & Permissions.

23

ENABLE_FINESSE_GADGET

This config is to enable/disable auto-login while VRS is embedded in Finesse as a gadget.

24

TRUST_STORE_PATH

Only if needed. Uncomment these and provide the path of the truststore dir which is ssl directory in the recording-solution.

25

TRUST_STORE_PASSWORD

Only if need. Uncomment it and Provide the password of the truststore.

26

COMPRESSION_ENABLED

Enable compression when using a Cisco profile. (True/False)

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

Name

Description

Name

Description

ARCHIVAL_JOB_INTERVAL

Archival scheduler interval in hours (e.g. 8)

CALL_ID_FORMULA

Optional call-id formatting expression; leave empty for default

CISCO_WRAPUP_BACKFILL_ENABLED

true to enable mixer wrap-up / call-variable sync

CISCO_WRAPUP_SYNC_LAG_MIN

Minutes to wait after call end before reading wrap-up data (default 2)

CISCO_WRAPUP_SYNC_BATCH_SIZE

Max wrap-up rows processed per sync cycle (default 500)

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.

Name

Description

Name

Description

1

CCX_PRIMARY_IP

Primary UCCX IP address. e.g 192.168.1.33

2

CCX_SECONDARY_IP

Secondary UCCX IP, e.g, 192.168.1.33

3

CCX_ADMIN_USERNAME

CCX Admin username

4

CCX_ADMIN_PASSWORD

CCX Admin password

The below Env variables are only for UCCE.

Name

Description

Name

Description

1

UCCE_IP

UCCE IP

2

UCCE_DATABASE

UCCE awdb database name

3

UCCE_USERNAME

UCCE awdb database user’s username

4

UCCE_PASSWORD

UCCE awdb database user’s password

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

 

Names

Description

 

Names

Description

1

ESL_HOST

IP address of the Recorder Machine

2

ESL_PORT

Port of the Record where ESL commonly used 8021

3

ESL_PASSWORD

Password of ESL

4

REC_PATH_STREAMS

Path where streams are saved, e.g, vrs/var/recordings/cucmRecording/streams

Update the Database environment variables in config.env.

 

Name

Description

 

Name

Description

1

DB_DRIVER

JDBC driver. PostgreSQL: org.postgresql.Driver. SQL Server: com.microsoft.sqlserver.jdbc.SQLServerDriver

2

DB_ENGINE

postgres or sqlserver (must match KC_DB: postgres or mssql)

3

DB_HOST

IP/FQDN of the VRS metadata database host

4

DB_NAME

VRS metadata database name (usually vrs). For EFCX, from /etc/fusionpbx/config.conf

5

DB_USER

VRS DB username. For EFCX, from /etc/fusionpbx/config.conf