Deploying SMS Gateway on Docker

Before you begin

• Create a phone number with SMS capabilities and create the IBM Watson™ Assistant service as described in Getting started with SMS Gateway.

• Install Docker on the host where you plan to run the gateway. Docker Engine provides a lightweight runtime for the SMS Gateway container.

  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.

• Make sure that either of the following ports are open for the connection to your SMS provider:

  • Secured connections: Port 9443
  • Unsecured connections: Port 9080

Deploying SMS 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. Change to a directory from which you want to deploy SMS Gateway, and pull the latest Docker image:

   docker pull icr.io/voice-gateway/sms-gateway:latest
   

3. Go to the directory where you cloned sample.voice.gateway repository on your machine, and open the sms/docker directory, which contains the sample docker-compose.yml configuration file.

   The sample file is preconfigured with the minimum configuration and points to the latest image. For a complete listing of all variables, see Configuration environment variables for SMS Gateway.

4. Copy the sample file to the directory where you pulled the Docker image.

5. Modify the file to configure Watson Assistant, your SMS provider, and the tenant phone number.

   • For Watson Assistant, specify the service credentials and workspace ID. For information about how to find the service credentials, see Service credentials for Watson services.

     Tip: To find the Watson Assistant workspace ID, go to the Workspaces view within the Watson Assistant tool. On the workspace that you want to integrate, click the Actions icon (⋮) and select View details.

     For example:

     environment:
      - WATSON_CONVERSATION_URL=https://api.us-south.assistant.watson.cloud.ibm.com/instances/{instance_id}
      - WATSON_CONVERSATION_APIKEY=MssmPWlXKeXkOeeZ1o93va5kSAzlqMSligZkso_FSopY
      - WATSON_CONVERSATION_WORKSPACE_ID=a23de67h-e527-40d5-a867-5c0ce9e72d0d
     

   • For the SMS provider, specify the API URL and login credentials.

     The user name maps to the account SID, and the password maps to the authentication token. You can find both of these values in the console for your SMS provider.

     For example:

       - SMS_PROVIDER_URL=https://api.twilio.com
       - SMS_PROVIDER_USERNAME=A23de67h0236e5e7c7f1ead4499h7f54cb
       - SMS_PROVIDER_PASSWORD=9h7f54cb3b1d3736e19ac64aa23de67h
     

   • For the tenant phone number, specify the full phone number from your SMS provider. Use the exact number format that the SMS provider requires. For example, to specify a Twilio phone number, include a plus sign (+) and the country and area codes. For RestcommONE, don't include the plus sign (+).

   For example:

     - TENANT_PHONE_NUMBER=+12345556789
   

   • Optional: If you want to allow users to create SMS sessions by sending an SMS message to the gateway, set ALLOW_SESSION_CREATE_VIA_SMS to true. By default, SMS sessions can only be created by using the REST API.

     For example:

       - ALLOW_SESSION_CREATE_VIA_SMS=true
     

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

7. Create and start up the container by running the following command:

   docker-compose up
   

   After you start the container, you'll see a number of messages as the SMS Gateway server deploys.

   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 container, restart the Docker daemon and try the command again.
   • If you see the following error on startup, you likely have another application listening on the specified port. Shut down any conflicting applications, and try the command again.

   Bind for 0.0.0.0:9080 failed: port is already allocated
   

What to do next

After you deploy the SMS Gateway on Docker, set up a webhook and test your deployment as described in Getting started with SMS Gateway.

You can further configure your SMS Gateway deployment by editing the docker-compose.yml file to add or change configuration variables and then redeploying the container.