Containers¶

Using BotCity's available images you can quickly have access to BotCity CLI and BotCity Runner for your project. You can also setup your development environment in no time.

Available Images¶

We currently provide the following images:

Image Name	Description
botcity-base	BotCity Image with BotCity Runner and CLI from BotCity Studio SDK
botcity-java-web-firefox	Extension of `botcity-base` with Java and Firefox browser
botcity-java-web-chrome	Extension of `botcity-base` with Java and Chrome browser
botcity-python-web-firefox	Extension of `botcity-base` image with Python 3.11 and Firefox browser
botcity-python-web-chrome	Extension of `botcity-base` image with Python 3.11 and Chrome browser
botcity-python-desktop	Extension of `botcity-base` image with Python 3.11 and Desktop support

botcity-base image is a base image and contains Java as well as the BotCity Runner and CLI. All other images are derived from this image and add additional features.

Alert

The images provided by BotCity were built for amd64 architectures, we suggest that the host where you will run the containers supports this architecture or has a compatibility mode.

Mirrors¶

BotCity container images are available in the following mirrors:

Mirror	Image Prefix
Docker Hub	`botcity/`
Amazon AWS ECR	`public.ecr.aws/`

When to use which image¶

If you intend to simply use the BotCity CLI, you can use the botcity-base image.

For Web automations in headless mode, you can choose the appropriate image for your project depending on the browser and language used. For example, botcity-python-web-firefox or botcity-java-web-chrome.

For desktop applications that require a graphical interface, you can choose the botcity-python-desktop image.

Configuration¶

In order to use it you will need to provide the following environment variables:

SERVER: The server prefix. E.g.: developers for developers.botcity.dev.
LOGIN: The Orchestrator BotCity Maestro login information available at the Dev. Environment page.
KEY: The BotCity Maestro key information available at the Dev. Environment page.
WORKSPACE: The BotCity Maestro workspace information available at the Dev. Environment page.
MACHINE_ID: The machine ID to be used by the Runners page.
IGNORE_SSL: (Optional) If set to true, it will ignore SSL certificate validation. Use with caution!
DEBUG_ENABLED: (Optional) If set to true, it will enable debug mode and produce more verbose logs. Use with caution!

Important

The SERVER, LOGIN, KEY, WORKSPACE environment variables are mandatory for the correct operation of the BotCity CLI tool and MACHINE_ID is mandatory for the BotCity Runner. The other variables are optional configurations.

For more information about the configuration, please visit the Dev. Environment page.

Usage¶

The images contain the BotCity Runner and BotCity CLI tools from the BotCity Studio SDK.

They can be launched via the BotCLI and BotRunner commands and all parameters are forwarded to the respective tools.

BotCity CLI¶

To start the BotCLI tool, simply run the following command:

<docker config> <image name> BotCLI <parameters here>

Important

For the examples presented, we will assume that you already have the values for:

<docker config>: Refers to the command for configuring environment variables.

docker run --rm -ti -e WORKSPACE=YOUR_WORKSPACE -e SERVER=YOUR_SERVER -e LOGIN=YOUR_LOGIN -e KEY=YOUR_KEY -e MACHINE_ID=YOUR_MACHINE_ID

<image name>: Refers to the name of the image you want to use.

botcity/botcity-base:latest

<parameters here>: Refers to the parameters you want to pass to the BotCLI command.

machine status --mid "vm-01"

For more information about the BotCLI tool, see the BotCity CLI documentation.

BotCity Runner¶

To launch the Runner tool, simply run the following command:

<docker config> <image name> BotRunner

Important

For the BotCity Runner, the MACHINE_ID environment variable is mandatory.

You can add the -single parameter at the end of the command to run a single task and terminate the container execution.

For more information about the BotCity Runner tool, please refer to the BotCity Runner documentation.

Examples¶

Here are some practical examples using BotCity container images.

Info

For the purposes of this example we will assume the following:

Our BotCity server is running on company.botcity.dev
Our BotCity workspace is company
Our BotCity login is company
Our BotCity key is COM_123ABCBA321
Our Machine ID is DOCKER_01

The <docker config> will be for all cases:

docker run --rm -ti -e WORKSPACE=company -e SERVER=company -e LOGIN=company -e KEY=COM_123ABCBA321 -e MACHINE_ID=DOCKER_01

Creating a Machine with the BotCity CLI¶

In this example we will use the BotCity CLI to create a new machine with the machineId as DOCKER_01 using the AWS ECR mirror.

<docker config> public.ecr.aws/botcity/botcity-base:latest BotCLI machine new -machineId DOCKER_01

The command explained:

<docker config> Refers to the command for configuring environment variables that we described at the beginning of this section.
public.ecr.aws/botcity/botcity-base:latest is the image used, where:
- botcity-base is the name.
- :latest is the tag.
BotCLI is the name of the command.
machine new is the command action.
-machineId DOCKER_01 are parameters sent to the BotCLI machine new command.

Tip

To use Docker Hub as the mirror, simply change the image name from public.ecr.aws/botcity/botcity-base:latest to botcity/botcity-base:latest.

Deploying a Bot with the BotCity CLI¶

In this example we will deploy a Python automation available on the file BotPython-1.0.tar.gz using the Docker Hub mirror.

Since we need the BotCity CLI to have access to the BotPython-1.0.tar.gz file, we will need to share the folder with the container.

<docker config> -v my_code_folder:/code botcity/botcity-base:latest BotCLI bot deploy -version 1.0 -botId BotPython -file /code/BotPython-1.0.tar.gz -python

The command explained:

<docker config> Refers to the command to configure the environment variables that we described at the beginning of this section.
-v my_code_folder:/code is the folder with the BotPython-1.0.tar.gz file to share with the container.
- :/code is the path where the file will be saved inside the container.
botcity/botcity-base:latest is the image used, where:
- botcity-base is the name.
- :latest is the tag.
BotCLI is the name of the command.
bot deploy is the command action.
-version 1.0 -botId BotPython -file /code/BotPython-1.0.tar.gz -python are the parameters sent to the BotCLI bot deploy command.

Important

In order to deploy or update a Bot or perform any other action which relies on files on the disk, you will need to share this folder with the container and adjust the path accordingly.

For more information about shared folders and Docker please visit the Docker documentation.

BotCity Runner for Headless Python Firefox Automations¶

In this example we will use the BotCity Runner to run Python automations that use Firefox browser in headless mode using the AWS ECR mirror.

<docker config> public.ecr.aws/botcity/botcity-python-web-firefox:latest BotRunner

The command explained:

<docker config> Refers to the command for configuring environment variables that we described at the beginning of this section.
public.ecr.aws/botcity/botcity-python-web-firefox:latest is the image used, where:
- botcity-python-web-firefox is the name.
- :latest is the tag.
BotRunner is the name of the command.

No additional parameters are required for a standard BotCity Runner run, but you can use -single to customize the run.

Tip

To use Docker Hub as the mirror, simply change the image name from public.ecr.aws/botcity/botcity-python-web-firefox:latest to botcity/botcity-python-web-firefox:latest.

Creating a Compose File¶

You can also use Docker Compose to manage your containers more efficiently and organized. You can create a docker-compose.yml file with the following structure:

version: "3.0"
services:
  docker-1:
    image: botcity/botcity-python-web-chrome
    command: BotRunner
    environment:
        SERVER: developers
        LOGIN: YOUR_LOGIN
        KEY: YOUR_KEY
        MACHINE_ID: YOUR_MACHINE_ID

And then you can run the docker-compose up command in the terminal to start the container.

Warning

The Chrome images require the --shm-size parameter to be set to at least 1g. Example: --shm-size="1g".

The --shm-size parameter allows you to specify the shared memory size available for containers in bytes units. This is useful in scenarios where you run applications inside containers that extensively use shared memory.

If you are using docker compose, you can set this parameter via the shm-size parameter. See the example below:

version: "3.0"
services:
    docker-1:
    image: botcity/botcity-python-web-chrome
    command: BotRunner
    environment:
        SERVER: developers
        LOGIN: YOUR_LOGIN
        KEY: YOUR_KEY
        MACHINE_ID: YOUR_MACHINE_ID
    shm_size: '1gb'

Tip

You can also create different Runner instances to run at the same time with Docker Compose, as in the example below:

    version: "3.0"
    services:
      docker-1:
        image: botcity/botcity-python-web-chrome
        command: BotRunner
        environment:
            SERVER: YOUR_SERVER
            LOGIN: YOUR_LOGIN
            KEY: YOUR_KEY
            MACHINE_ID: YOUR_MACHINE_ID_1
      docker-2:
        image: botcity/botcity-python-web-chrome
        command: BotRunner
        environment:
            SERVER: YOUR_SERVER
            LOGIN: YOUR_LOGIN
            KEY: YOUR_KEY
            MACHINE_ID: YOUR_MACHINE_ID_2

Customizing the Images¶

If you need to customize the images, you can create your own Dockerfile and use one of the BotCity images as the base, as they already have all the tools for using the BotCLI and BotRunner commands ready.

Then, from an existing image, you can add the necessary packages for your project.

As an example, we used the botcity-python-desktop image as the base and added the freerdp2-x11 package as a project dependency.

FROM botcity/botcity-python-desktop:latest

# Install System Dependencies
RUN apt-get update && \
     \
    apt-get -y install freerdp2-x11 \
    --no-install-recommends && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

Then you can build the image using the following command:

docker build -t my-botcity-python-desktop-rdp:latest .

And then you can use the my-botcity-python-desktop-rdp:latest image in your project.

version: "3.0"
services:
  docker-1:
    image: my-botcity-python-desktop-rdp
    command: BotRunner
    environment:
        SERVER: YOUR_SERVER
        LOGIN: YOUR
        KEY: YOUR_KEY
        MACHINE_ID: YOUR_MACHINE_ID

Important

When creating a custom image using the Dockerfile, be careful not to overwrite the ENTRYPOINT or CMD instructions, as this will break the BotCity Runner and BotCity CLI tools.

As a best practice, we recommend using the BotCity image as a base and adding only the dependencies you need.

For more information about Dockerfiles and how to use them, visit the Docker documentation.

Troubleshooting¶

When using the AWS ECR mirror, I get an error message saying

pull access denied for public.ecr.aws/botcity/botcity-base, repository does not exist or may require 'docker login': denied: Your authorization token has expired. Reauthenticate and try again.

. What do I do?

The images are available publicly in the AWS ECR mirror so you don't need to have credentials to pull them.

If you are receiving this message, please try to follow the instructions on the AWS ECR documentation.

When I try to run the BotCity CLI tool, I get an error message saying Login failed. Check your internet connection, server availability or SERVER parameter in config.properties. What do I do?

Make sure you have provided the correct SERVER environment variable. If your server URL is developers.botcity.dev, then the correct SERVER environment variable is developers.

If the SERVER environment variable is correct, then make sure you have provided the correct LOGIN and KEY environment variables as well.