Community Blog

Community Blog

Run a Symphony bot in less than three minutes on Docker

March 03, 2017

Having fun with our community on bot-butler, Coffescript and CI/CD

The Symphony Software Foundation hosts a very interesting project called bot-butler, led by Symphony Senior Solutions Architect Vinay Mistry.

The bot-butler is, in short, a very convenient way to write a bot for the Symphony chat platform, based on the Github Hubot and the Hubot-Symphony adapter: write a script, as the ones defined in the project, and you're good to go.

I wanted to play more with this project for a while, but I couldn't postpone any longer when I saw a Dockerfile landing on the project codebase.

After couple of days of work with Vinay, we accomplished something that is worth sharing.

Run it!

We wrote extensive documentation to explain how to configure, run and customize the bot; give it a try and let us know if you find it as easy and straightforward as we do.

Below we’re going to walk you through the Docker run as it’s the quickest way to start; if you’re planning to do intensive development, we’d advise you to try the local run.


Before starting, there are a few pieces of information to gather that will make the next steps much easier; most of them refer to the Symphony authentication mechanism for bots and therefore is applicable for all Symphony bot development activities.

  1. Install Docker on your workstation

  2. Identify the Symphony pod to use for this test; if you’re a Foundation committer, you can use the Open Developer Platform

  3. Collect Symphony pod coordinates:

  4. Collect service account credentials for the bot to authenticate against the Symphony pod: a user identity public certificate (<your_bot>-cert.pem) and a private key (<your_bot>-key.pem) to authenticate the bot against the Symphony pod; the key can (or should) be password protected:
    a. HUBOT_SYMPHONY_PUBLIC_KEY=./certs/<your_bot>-cert.pem
    b. HUBOT_SYMPHONY_PRIVATE_KEY=./certs/<your_bot>-key.pem

  5. Collect user account credentials (username/password) to the Symphony pod, used to interact with the bot

Make sure that the service account is properly configured:

  1. Access the Symphony Admin Console (or delegate to your Symphony Administrator)
  2. Make sure that a service account exists and the username matches with the Common Name (CN) of the public certificate (mentioned above on step #4); to check it, type:
    a. openssl x509 -noout -subject -in ./certs/<your_bot>-cert.pem
  3. Access the Manage Certificates dashboard and import the the root signing certificate that signed the user identity (mentioned above on step #4)

Build and run a container

119 seconds. This is the time it took me to run through these steps, assuming that my ./certs folder and files are ready (see prerequisites above).

1. Checkout the bot-butler project 

git clone bot-butler

2. Add the User Identity certificate and Key to authenticate the bot against the Symphony pod

mkdir ./certs ; cp <your_cert>-key.pem <your_cert>-cert.pem ./certs

Define an file, starting from, then edit the file and change the environment variables mentioned in the prerequisites

cp ; open

Build the Docker image

docker build -t butler:v0.9.0 .

5. Run the Docker image

docker run butler:v0.9.0

Ping the bot

  1. Access the Symphony pod - via mobile (as shown below) or web interface  - with the user account credentials mentioned above
  2. Search for the bot user (using the service account username or display name) and open a chat
  3. Play around :-)


Let’s see what Tesla and Apple Inc. are trading at today.


Project automation

The bot-butler project is also raising the bar for project automation within the Foundation infrastructure; below we report some of the project automation tools and configurations that are adopted in order to make developers life easier and move towards project activation.

Continuous integration

On every commit and PR, Travis CI runs the build tasks, defined in .travis.yaml; when functional/integration tests will be available in the project, Travis CI will be able to run them continuously against the Foundation Open Developer Platform.

License and security scanning

Making sure that all dependencies have a licence that complies with Foundation bylaws can be a daunting process, if manually done (same for security vulnerabilities); Versioneye parses the yarn.lock file, extracts dependencies, versions and licenses; outdated versions are notified and licenses are matched against a whitelist defined by the Foundation. As you can see by the Versioneye dashboard, there's still some work to be done:

  • Upgrade dependencies to use the most updated and secure versions
  • Validate unknown licenses, optionally suggest them to Versioneye and/or project maintainer; incrementally refine the Foundation license whitelist
  • Make sure the build fails for identified license violations

What’s next?

It’s really easy to write your own scripts or customize the existing ones; check out the hubot coffeescript docs to know more about scripting syntax.

Found a bug in the documentation? Want to contribute a script that you've built? Having some trouble running the bot? Ping us at, open an issue or send us a pull request.

Interested in building an open source bot, app or integration on the Symphony platform? Pre-register for our Open Innovation Challenge Silicon Valley!