The documentation you're currently reading is for version 2.5.1. Click here to view documentation for the latest stable version.


Like Docker? And Kubernetes? So do we!

One of the quickest ways to get BWC running is using Docker. This page will show you the basics of how to use BWC with Docker.

For more detailed information and examples, check out the README at our st2-docker GitHub repo.

Host Requirements

Docker Images

The stackstorm/stackstorm image comes pre-installed with the st2, st2web, st2mistral and st2chatops packages.

We use version tags, so if you install the image stackstorm/stackstorm:2.3.2, then it has the BWC 2.3.2 release packages. Similarly, if you install image stackstorm/stackstorm:2.2.1, then it has the BWC 2.2.1 release packages. The stackstorm/stackstorm:latest image simply references the image with the highest version number. Don’t worry, this will still be a stable GA release, not a nightly build.

The mongo, rabbitmq, postgres and redis containers store their data on persistent storage. Additionally, the stackstorm container persists the contents of /var/log. If you do not wish to persist this data, then remove the appropriate entries from docker-compose.yml.


Assuming Docker engine and docker-compose are properly installed, getting started is easy.

First, clone the st2-docker repository and change directory to st2-docker. Unless specified otherwise, all subsequent commands assume they are run within st2-docker directory:

git clone
cd st2-docker

Second, execute:

make env

to create the environment files under conf/ used by docker-compose. Prior to doing so, you may want to change some variables as necessary. The defaults should be okay if you are not using any off-cluster services (e.g. mongo, redis, postgres, rabbitmq).

Below is the complete list of available options that can be used to customize your container:

Parameter Description
ST2_USER BWC account username
ST2_PASSWORD BWC account password
MONGO_HOST MongoDB server hostname
MONGO_PORT MongoDB server port (typically 27017)
MONGO_DB (Optional) MongoDB dbname (will use st2 if not specified)
MONGO_USER (Optional) MongoDB username (will connect without credentials if this and MONGO_PASS are not specified)
MONGO_PASS (Optional) MongoDB password
RABBITMQ_HOST RabbitMQ server hostname
RABBITMQ_PORT RabbitMQ server port (typically 5672)
POSTGRES_HOST PostgreSQL server hostname
POSTGRES_PORT PostgreSQL server port (typically 5432)
POSTGRES_DB PostgreSQL database
POSTGRES_USER PostgreSQL username
REDIS_HOST Redis server hostname
REDIS_PORT Redis server port
REDIS_PASSWORD (Optional) Redis password

Third, start the containers:

docker-compose up -d

This will pull the required images from Docker Hub, and then start them.

To stop the containers, run:

docker-compose down