Deploying Voice Gateway on Docker

Before you begin

• Install Docker on the host where you plan to run the gateway. The Docker Engine provides a lightweight runtime for the containers that make up the voice gateway, the SIP Orchestrator and Media Relay. Docker Community Edition and Enterprise Edition Version 1.13 or later are supported.

  Windows systems: Note that Docker for Windows requires 64-bit Windows 10 Pro. On earlier versions of Windows, you must install Docker Machine as part of Docker Toolbox. Deploying on Docker Machine is slightly different, as noted in the deployment steps.

• Clone or download the sample.voice.gateway GitHub repository, which contains sample Watson Assistant dialogs, configuration files, and other items to help you get started.

• Sign up for an IBMid and IBM Cloud account, and create the following Watson services:

  • Speech to Text
  • Text to Speech (self-service only)
  • Watson Assistant (self-service only)

  Make note of the credentials for each service that you created. You'll need to specify the credentials in the Voice Gateway configuration.

  Important: For Watson Assistant, you'll need to add a workspace with a dialog. You can quickly get started by importing the conversation/sample-conversation-en.json file from your cloned sample.voice.gateway GitHub repository. To learn more about importing JSON files, see Creating a dialog skill in the Watson Assistant documentation. If you build your own dialog instead of using the sample, ensure that your dialog includes a node with the conversation_start condition and node with a default response.

• If you plan to deploy Voice Gateway behind a firewall and you want to connect to that gateway through a SIP trunk or SIP client that is outside your firewall, make sure that all required ports are open. For more information, see Port settings for firewalls.

Deploying Voice Gateway

1. Docker Machine only: Before you can log in to Docker, run this command from the command line to set the shell to point to the Docker Engine:

   Windows:

   @FOR /f "tokens=*" %i IN ('docker-machine env default --shell cmd') DO @%i
   

   UNIX and Mac OS X:

   eval "$(docker-machine env default)"
   

2. Log in to IBM Cloud:

   ibmcloud login --sso
   

3. Set the target region to global for IBM Container Registry command line tool:

   ibmcloud cr region-set global
   

4. Log in to the IBM Container Registry:

   ibmcloud cr login --client docker
   

   For more information, see Add Using Docker to access the registry

5. Pull the latest Docker images of the SIP Orchestrator (voice-gateway-so) and Media Relay (voice-gateway-mr):

   docker pull icr.io/voice-gateway/sip-orchestrator:latest
   
   docker pull icr.io/voice-gateway/media-relay:latest
   

6. Go to the directory where you cloned sample.voice.gateway repository on your machine, and open the docker directory, which contains the following sample configuration files:

   • docker-compose-self-service.yml
   • docker-compose-agent-assist.yml

   These sample files are preconfigured with the minimum configuration for each implementation and point to the latest images of the voice gateway. You'll need to modify the file for your implementation type to include your Watson service credentials. For agent assistants, also configure transcription reporting events.

   1. Copy the file related to your type of implementation to a new file named docker-compose.yml. Keep the file in the same directory.

   2. In the new docker-compose.yml file, fill in any blank environment variables, such as the credentials for your Watson services.

   ...
      # Credentials for IBM Cloud Speech-To-Text
      - WATSON_STT_APIKEY=MssmPWlXKeXkOeeZ1o93va5kSAzlqMSligZkso_FSopY
      - WATSON_STT_URL=https://api.us-south.speech-to-text.watson.cloud.ibm.com/instances/{instance_id}
   ...
    ```
    For a complete listing of all variables, see [Configuration environment variables](https://www.ibm.com/docs/en/voice-gateway?topic=reference-configuration-environment-variables).
   
   **Tip:** To find the Watson Assistant workspace ID, go to the Workspaces view within the Watson Assistant tool. On the skill that you want to integrate, click the Actions icon (**⋮**) and select **View details**.
   
   **Note:** For the `WATSON_CONVERSATION_URL` configuration parameter in the `docker-compose.yml` file, use only the portion of the URI up to and including the `api` level. For example,
   
   ```yml
     - WATSON_CONVERSATION_URL=https://api.us-south.assistant.watson.cloud.ibm.com/instances/{instance_id}
   ```
   
   **Important:** If you're deploying to a public cloud, be sure to also define the whitelist variables to prevent denial-of-service (DoS) attacks and other unwanted sessions from outside sources, which could incur unnecessary Watson service charges and affect Voice Gateway performance. By default, these variables are commented out in the Compose files.
   
   ```yml
      - WHITELIST_TO_URI=2345556789
   ```
   

   For more information, see Whitelisting callers and callees

7. In the directory where you modified the docker-compose.yml file, create a .env file and set the EXTERNAL_IP variable. These commands assume you're using vi for editing, but you can use any editor.

   For most Docker installations, the IP address that you set is the IP of your local system. For Docker Machine, which runs the containers in a virtual machine, determine the IP address of the VM by running the docker-machine ip command.

   1. Enter the following commands to create the .env file and open it for editing.

   touch .env
   vi .env
   

   1. Enter i to switch to edit mode. At the top of the .env file, add the following line:

   EXTERNAL_IP=<IP address of local system or Docker Machine VM>
   

   1. Press the Esc key to exit edit mode, and enter :wq to exit the editor.

8. Create and start up the containers by running the following command:

   docker-compose up
   

   Tips:

   • If the docker-compose command isn't found, you must install Docker Compose.
   • If you see a grpc: the connection is unavailable error when you start the containers, restart the Docker daemon and try the command again.
   • If you see the following error on startup, you likely have another application listening on port 5060. Shut down any conflicting applications, and try the command again.

   Bind for 0.0.0.0:5060 failed: port is already allocated
   

What to do next

After you deploy the Voice Gateway on Docker Engine, test your deployment as described in Getting started with Voice Gateway.

You can further configure your Voice Gateway deployment by editing the docker-compose.yml file to add or change configuration variables and then redeploying the containers. You can use the optimal configuration settings that are included in the most recent release by setting either the USE_OPTIMAL_CONFIGURATION environment variable. See Using optimal configuration settings.

Protecting sensitive information: Both the Text to Speech caching and audio recording collection are disabled by default. If you enable these features, take appropriate measures to protect and mitigate sensitive data when you deploy Voice Gateway. It's recommended that you encrypt the disk where Voice Gateway is deployed. Hard disk encryption can protect any recordings or text to speech responses that are cached in the file system, because they might contain sensitive information. Encrypting the hard disk only encrypts data stored in Voice Gateway. You must take additional steps to secure data in services that are integrated with Voice Gateway.