StackStorm in Docker containers

The default container configuration is as follows:

• stackstorm (st2 + st2web + st2mistral)
• mongo
• rabbitmq
• postgres
• redis

READ FIRST!!

• Check the CHANGELOG.rst file for any potential changes that may require restarting containers.
• Be sure to use the latest docker-compose.yml. Run git pull in your st2-docker workspace!
• Run st2ctl reload --register-all to reload all services.

TL;DR

make env
docker-compose up -d
docker-compose exec stackstorm bash

Open https://localhost in your browser. StackStorm Username/Password can be found in: cat conf/stackstorm.env

Running on Kubernetes? See runtime/kubernetes-1ppc

Usage

We use Version 3 of the compose file format, so if you want to run docker-compose, you'll need to ensure you're running Docker Engine release 1.13.0+.

First, execute

make env

to create the environment files used by docker-compose. You may want to change the values of the variables as necessary, but the defaults should be okay if you are not using any off-cluster services (e.g. mongo, redis, postgres, rabbitmq).

NOTE: make env only needs to be run once.

As an example, if you want to change the username and password used by StackStorm, change the ST2_USER and ST2_PASSWORD variables in conf/stackstorm.env prior to bringing up your docker environment.

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

Parameter	Description
ST2_USER	StackStorm account username
ST2_PASSWORD	StackStorm 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)
RABBITMQ_DEFAULT_USER	RabbitMQ username
RABBITMQ_DEFAULT_PASS	RabbitMQ password
POSTGRES_HOST	PostgreSQL server hostname
POSTGRES_PORT	PostgreSQL server port (typically 5432)
POSTGRES_DB	PostgreSQL database
POSTGRES_USER	PostgreSQL username
POSTGRES_PASSWORD	PostgreSQL password
REDIS_HOST	Redis server hostname
REDIS_PORT	Redis server port
REDIS_PASSWORD	(Optional) Redis password

Second, start the docker environment.

If you would like to run all stackstorm services in one container, and the databases in their own container, use:

docker-compose up -d

On the other hand, if you want to run one process per container, use:

docker-compose -f runtime/compose-1ppc/docker-compose.yml run -d

This will pull the required images from docker hub, and then start them.

However, if you find need to modify the stackstorm image, you will need to build it. Run:

REPO=stable
docker build --build-arg ST2_REPO=${REPO} -t stackstorm/stackstorm:${REPO} images/stackstorm

where REPO is one of 'stable', 'unstable', 'staging-stable', 'staging-unstable'. Otherwise, the following docker-compose command will download the specified image from docker hub.

After you spin up the environment, you can play around with following this tutorial guide.

To stop the docker environment, run:

docker-compose down

Data persistence

It's designed to suffice the ordinary use case by default. If you need to customize it, check below and modify docker-compose.yml

• The mongo, rabbitmq, postgres and redis containers store their data on persistent storage
• The stackstorm container persists the contents in following directories
  • /var/log
  • /opt/stackstorm/packs
  • /opt/stackstorm/virtualenvs
  • /opt/stackstorm/configs

Running custom shell scripts on boot

The stackstorm container supports running arbitrary shell scripts when the container launches:

• Scripts located in /st2-docker/entrypoint.d are executed before the init process starts any stackstorm services.
• Scripts located in /st2-docker/st2.d are executed after stackstorm services are running.

NOTE: Only scripts with a suffix of .sh will be executed, and in alphabetical order of the file name.

/st2-docker/entrypoint.d

For example, if you want to modify /etc/st2/st2.conf to set system_packs_base_path parameter, create modify-st2-config.sh with the follwing content:

#/bin/bash
crudini --set /etc/st2/st2.conf content system_packs_base_path /opt/stackstorm/custom_packs

Then bind mount it to /st2-docker/entrypoint.d/modify-st2-config.sh

• via docker run

  docker run -it -d --privileged \
    -v /path/to/modify-st2-config.sh:/st2-docker/entrypoint.d/modify-st2-config.sh \
    stackstorm/stackstorm:latest
  

• via docker-compose.yml

  services:
    stackstorm:
      image: stackstorm/stackstorm:${TAG:-latest}
       : (snip)
      volumes:
        - /path/to/modify-st2-config.sh:/st2-docker/entrypoint.d/modify-st2-config.sh
  

The above example shows just modifying st2 config but basically there is no limitation so you can do almost anything.

You can also bind mount a specific directory to /st2-docker/entrypoint.d then place scripts as much as you want.

/st2-docker/st2.d

Scripts in this directory can be used to register packs, reload or restart services, etc. You can bind mount these scripts as mentioned in the previous section.

NOTE: These scripts are currently not available when running in 1ppc mode.

To enable/disable chatops

Chatops is installed in the stackstorm image, but not started by default.

To enable chatops, delete the file /etc/init/st2chatops.override using a script in /st2-docker/entrypoint.d.

#!/bin/bash

sudo rm /etc/init/st2chatops.override

If you need to disable chatops, run the following using a script in /st2-docker/entrypoint.d:

#!/bin/bash

echo manual | sudo tee /etc/init/st2chatops.override