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 add the bot key and host (and optionally a proxy):
#!/bin/bash
export TW_API_APPID=your_app_id
export TW_API_SECRET=your_secret
export TW_API_HOST=https://your_backend_url
export HTTPS_PROXY=https://your_proxy_url # optional
export HTTP_PROXY=http://your_proxy_url # optional
BOT_DIR=`dirname "$0"`
echo running $1, please wait...
python3 $BOT_DIR/$1
Then, you can call this script from any directory by running:
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.
This 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 Harbor account. Contact our support team 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 stored in a directory with the following structure:
── ExampleBot
├── example-bot.py
└── requirements.txt
In particular, requirements.txt will contain the list of ExampleBot dependencies, which would normally be installed with:
In order to execute the bot in a Docker environment, we first need to create a Docker image containing it. This is possible by creating a Docker configuration file (Dockerfile) in the same directory as 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:2.0.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 note that the RUN section is only needed if the bot has third-party dependencies that must 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:2.0.0
# Add 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 container
CMD python3 /app/example-bot.py
Once the Dockerfile is ready, the image can be built with:
Run this command in the same directory as 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:
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 first be pulled:
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://your_backend_url" \
-e HTTPS_PROXY="https://your_proxy_url" -e HTTP_PROXY="http://your_proxy_url" \
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 the 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 crashes, 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 asexamplebot-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-eoptions- note: the
HTTPS_PROXYandHTTP_PROXYenvironment variables are optional and should be provided only if your Teamwire backend is behind a proxy.
Finally, 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:
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:
and restarted with:
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, assuming you have updated your bot's code, you will need to publish a new version (e.g. v1.0.1) of the image:
On the production server, you'll have to pull the new version:
Before running the new image, you first have to remove the container for the previous version:
Then you can run a new container based on the new image: