Running bots

Running a bot locally for development

During development, it can be very handy to have a script to run your bot, setting the proper environment variables in the same scope as the bot.

Create a new file in the bot folder called run.sh, then fill it up with the bot key and host:

#!/bin/bash

export TW_API_APPID=your_app_id
export TW_API_SECRET=your_secret
export TW_API_HOST=https://your_backend_url

BOT_DIR=`dirname "$0"`

echo running $1, please wait...

python3 $BOT_DIR/$1

Then, you can call this script from any place by running on command line:

$> run.sh your_bot.py

Running a bot with Docker

In order to simplify the deployment of bots in production, we provide a Docker image containing all the requirements and an installation of the latest available version of the Teamwire SDK, which you can use as a base for creating a Docker image for deploying your own bot applications.

Such docker image, named harbor.teamwire.eu/bots/sdk-base is available for Teamwire Partners on Teamwire's Harbor Registry. To access the Harbor link, your IP must be whitelisted, for which you need a harbour account. Contact our support team in order to get access to Teamwire Harbor repositories.

In the rest of this section we present a brief primer on how to create a Docker image for your bot and how to run and manage it.

Creating a Docker image for your bot

For the sake of explanation, let's suppose that you have developed a Teamwire bot named ExampleBot, whose python script is a directory with the following structure:

- ExampleBot
  |
  +- example-bot.py
  |
  +- requirements.txt

In particular, requirements.txt will contain the list of dependencies of ExampleBot, which normally would be installed with:

$> pip3 install -r requirements.txt

In order to be able to execute the bot in a Docker environment, first we need to create a Docker image containing it. This is possible by creating a Docker configuration file (Dockerfile) in the same directory containing the python script:

- ExampleBot
  |
  +- Dockerfile
  |
  +- example-bot.py
  |
  +- requirements.txt

The content of the Dockerfile for the above ExampleBot should be close to the following:

# Base the current Docker image on the Teamwire SDK image
FROM harbor.teamwire.eu/bots/sdk-base:1.6.0

# Add the content of the current directory to the image:
ADD . /app/

# Install python setuptools in the image and install dependencies
# from the requirements.txt file
RUN apt-get update && \
    apt-get install -y python3-setuptools && \
    pip3 install --upgrade -r /app/requirements.txt

# This is the command that will be executed at runtime when running the bot
# in a Docker container
CMD python3 /app/example-bot.py

Please consider that the RUN section is only needed if the bot has third party dependencies that need to be installed in the image. In the simplest case where no requirements.txt is present, the Dockerfile would be similar to the following:

# Base the current Docker image on the Teamwire SDK image
FROM harbor.teamwire.eu/bots/sdk-base:1.6.0

# Add the the python script to the image:
ADD example-bot.py /app/

# This is the command that will be executed at runtime when running the bot
# in a Docker containe
CMD python3 /app/example-bot.py

Once the Dockerfile is ready, the image can be built with:

$> docker build -t your-org/examplebot:v1.0.0 .

issued in the same directory containing the Dockerfile. The -t org/name:tag option is used to assign a name and optionally a tag to the image. In particular, the org part refers to the name of your organisation on DockerHub.

Pushing your image to DockerHub

In order to be able to push your bot image to DockerHub, you need to create a repository for it, whose name must correspond to the name of the Docker image we created in the previous steps. In particular, supposing your account on DockerHub is named "your-org", the repository for the ExampleBot will be named your-org/examplebot.

Once the docker image has been built, it can be pushed with:

$> docker push your-org/examplebot:v1.0.0

Pulling and running the bot in a Docker container

In order to deploy the ExampleBot to a server with a live Docker environment, the image must be first pulled:

$> docker pull your-org/examplebot:v1.0.0

Then it can be executed with:

$> docker run -d --restart always --network host --name examplebot -e TW_API_APPID="EXAMPLE-BOT-APP-ID" -e TW_API_SECRET="EXAMPLE-BOT-SECRET" -e TW_API_HOST="https://backend.teamwire.eu" your-org/examplebot:v1.0.0

Let's detail the meaning of all the involved arguments to the above command:

  • -d: execute the container in background
  • --restart always: always restart the container if its main process exits, regardless of the exit status. This ensures that even in cases where the bot would crash, the container is automatically restarted by Docker
  • --network host: [optional] all interfaces from the host are made available to the container
  • --name examplebot: set the name of the container as examplebot 
  • -e <ENV_VAR>: we pass the environment variables needed to run the bot, namely the "App ID", the "API secret" and the "API host", through the -e options

In the end, the docker run command specifies the name of the image to be executed.

Managing the container

The list of running containers can be obtained with:

$> docker ps

The result of the above command will be similar to the following:

CONTAINER ID        IMAGE                         COMMAND
CREATED             STATUS              PORTS               NAMES
4fc38184dafe        your-org/example-bot:v1.0.0   "/bin/sh -c 'python3…"
5 weeks ago         Up 5 days                               examplebot

The running container can be stopped with:

$> docker stop examplebot

and restarted with:

$> docker start examplebot

Updating the container

In order to execute an updated container with a new version of the docker image, you have to perform similar steps to those detailed in the above sections. In particular, supposing you have updated your bot's code, you will need to publish a new version (e.g. v1.0.1) of the image:

$> docker build -t your-org/examplebot:v1.0.1 .
$> docker push your-org/examplebot:v1.0.1

On the production server you'll have to pull the new version:

$> docker pull your-org/examplebot:v1.0.1

For running the new image you have first to remove the container of the previous version:

$> docker rm examplebot

Then you can run a new container based on the new image:

$> docker run -d --restart always --network host --name examplebot -e TW_API_APPID="EXAMPLE-BOT-APP-ID" -e TW_API_SECRET="EXAMPLE-BOT-SECRET" -e TW_API_HOST="https://backend.teamwire.eu" your-org/examplebot:v1.0.1