This docker image allows for a microservice to run within your LAN (Local Area Network) to accept POST and GET requests. The POST needs a JSON (Java Script Object Notation) object in its body to sent the SMS and the GET needs a watermark id to query for logs. The logs confirm the status of the message, example “delivered”. Authentication to Vodacom Messaging is handled by the container.
The image (which builds to a container) is called carlpaton/vodacommessagingxml2sms and is available at https://store.docker.com/community/images/carlpaton/vodacommessagingxml2sms
The code running in the container is written in C# (C-Sharp) and is a Microsoft WEB API project running on .NET Core 2. The Massive value in using .NET Core is it will run on Linux which will appeal to corporates and hopefully impress your boss!
What is Vodacom Messaging XML2SMS?
Vodacom Messaging is an online mobile messaging and gateway provider, in a nutshell, their services provide mobile communication tools to send and receive messages in popular formats such as SMS (Short Message Service).
Although the world has moved on with instant messaging clients like WhatsApp and even E-mail (Electronic mail), in South Africa SMS is still hugely popular with corporates needing to communicate with their client base in a ubiquitous manner.
The XML2SMS product is a tool aimed at developers to integrate SMS capabilities into their applications, this can be used for a number of event driven messages such as access tokens or OTP (One Time Pin) for banking applications or real-time notifications of spend or activity. Every SMS Is tracked with status updates available of delivery for auditing purposes.
All my testing was done on Ubuntu Server version 17 running as a virtual machine hosted on my notebook which runs Windows 10. Ubuntu then hosted docker, the images and containers.
If you are un-familiar with Docker & its capabilities I suggest you go through my article “Docker -Containers – The future” before going any further, if you are already using docker and want to either publish your own containers or see a summary of how to use mine see “Building Docker Images”
If you are reading this and are still puzzling how to use my image perhaps this illustration will help clear things up for you.
Steps By Step
You can use docker for windows but for the purpose of this demo I have focused on Ubuntu Server in the configuration described above.
- Setup Docker on Linux, there are detailed steps here to setup your VM Player (Virtual Machine Player), the hosted Linux OS (Operating System)
- Create an environmental properties file, these will be injected into the container when it is created.
I called mine env_file_name.env, below are the environmental properties the container will need. You can also set these in appsettings.json – if you dont use the env file the container will look at appsettings.json instead.
USERNAME_ENVIRONMENT= PASSWORD_ENVIRONMENT= SMSGW_ENVIRONMENT=
This is the authentication the container will pass to Vodacom Messaging, you will need an account with them to send SMS.
This is the flag to set the response from the container, you can have JSON or XML
During development the container can mock the response from the SMS Gateway, set this flag to 1 for mocking or 0 to send the SMS Request to Vodacom Messaging.
Editing the file on the server with nano
- Create your shell script to pull the image & spin up the container (Remember to mark it executable with chmod +x)
Below is the content of my script:
--- This tells the script to run with bash #!/bin/bash --- This pulls the image locally, the tag v1.0.0 can be omitted for latest. --- I’ve found when developing its best to specify a version so you know the --- only change is in your own code. docker pull carlpaton/vodacommessagingxml2sms:v1.0.0 --- If the container is already built and running as xml2sms, stop it. sudo docker container kill xml2sms --- Delete the container you just stopped. --- The value with the above steps is repatability. sudo docker rm xml2sms --- This spins up the new container. --- -d means run detached, --- -p is the port mapping 81 external to Linux and 80 internal to the container, --- name is the containers name followed by which image to build from. sudo docker run --env-file=env_file_name.env -d -p 81:80 --name xml2sms carlpaton/vodacommessagingxml2sms:v1.0.0 --- start the container you just created sudo docker start xml2sms --- Display all the containers on the host. sudo docker ps –all
Execute the shell script above:
- Send a POST request with a JSON object to the container and note the response.
If you set MOCKMODE_ENVIRONMENT=1 then the container will not call Vodacom Messaging but rather mock the response. The below are example POST methods from postman.
This shows the postman’s POST:
Note the key returned was 202, this will be used in the GET below.
- GET a HTTP request to the container with the watermark ID received in the POST above.
You can then query the containers logs with:
sudo docker logs xml2sms
All this code is open source and licenced MIT (Massachusetts Institute of Technology) so I encourage developers to fork the code and adapt to work for their environment. Some ideas I can think of would include
- HTTPS Traffic to the container from your applications
- Persist the requests / responses to a database (look at my ISmsLogger.cs)
- Authentication HASH per application
- Additional send options such as EMS (Extended Messaging Service), this already works on Vodacom Messaging and won’t take much effort to add to the container.