Skip to content
Switch branches/tags
Go to file

StackStorm in Docker Compose

Circle CI Build Status

This docker-compose is provided as a way to allow "get up and running" quickly with StackStorm using Docker (based on st2-dockerfiles). It is not designed to be used in production, but rather a way to test out StackStorm and facilitate pack development.

If you need Highly Availability experience, there is Kubernetes installation available via Helm charts at


docker-compose up -d
docker-compose exec st2client bash  # this gives you access to the st2 command line

Open http://localhost/ in your browser. StackStorm Username/Password by default is: st2admin/Ch@ngeMe.



  • Docker Engine 18.09+
  • Docker Compose 1.12+

Compose Configuration

The image version, exposed ports, and "" directory is configurable with environment variables.

  • ST2_VERSION this is the tag at the end of the docker image (ie: stackstorm/st2api:v3.3.0)
  • ST2_IMAGE_REPO The image or path to the images. Default is "stackstorm/". You may change this is using the Enterprise version or a private docker repository.
  • ST2_EXPOSE_HTTP Port to expose st2web port 80 on. Default is, and you may want to do to expose on all interfaces.
  • ST2_PACKS_DEV Directory to development packs, absolute or relative to docker-compose.yml. This allows you to develop packs locally. Default is ./ When making a number of packs, it is recommended to make a directory outside of st2-docker, with each subdirectory underneath that being an independent git repo. Example: ST2_PACKS_DEV=${HOME}/mypacks, with ${HOME}/mypacks/st2-helloworld being a git repo for the "helloworld" pack.


The files/htpasswd file is provided with a default username of st2admin and a default password of Ch@ngeMe. This can be changed using the htpasswd utility.

Another file (files/st2-cli.conf) contains default credentials and is mounted into the "st2client" container. If you change credentials in htpasswd, you will probably want to change them in st2-cli.conf.

Further configuration

The base st2 docker images have a built-in /etc/st2/st2.conf configuration file. Each st2 Docker image will load:

  • /etc/st2/st2.conf (default st2.conf)
  • /etc/st2/st2.docker.conf (values here will override st2.conf)
  • /etc/st2/st2.user.conf (values here will override st2.docker.conf)

Review st2.docker.conf for currently set values, and it is recommended to place overrides in st2.user.conf.


If your system has SELinux enabled you will likely see problems with st2 startup, specifically the st2makesecrets container will repeatedly restart and docker logs shows:

/bin/bash: / Permission denied

The fix is to disable SELinux (or to put it in permissive mode).

  • Disable temporarily with: setenforce 0
  • Change to use permissive mode on the next reboot with: sed -ie 's|^SELINUX=.*|SELINUX=permissive|' /etc/selinux/config

Step by step first time instructions

First, optionally set and export all the environment variables you want to change. You could make a .env file with customizations.


export ST2_PACKS_DEV=$HOME/projects/stackstorm-packs

Secondly make any customizations to files/st2.user.conf, files/htpasswd, and files/st2-cli.conf.


To enable sharing code between actions and sensors, add these two lines to files/st2.user.conf:

enable_common_libs = True

Third, start the docker environment:

docker-compose up -d

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

To stop the docker environment, run:

docker-compose down

Regular Usage

To run st2 commands, you can use the st2client service:

docker-compose exec st2client st2 <st2 command>


$ docker-compose exec st2client st2 run core.echo message=hello
id: 5eb30d77afe5aa8493f31187
action.ref: core.echo
context.user: st2admin
  message: hello
status: succeeded
start_timestamp: Wed, 06 May 2020 19:18:15 UTC
end_timestamp: Wed, 06 May 2020 19:18:15 UTC
  failed: false
  return_code: 0
  stderr: ''
  stdout: hello
  succeeded: true

Alternatively, you could run docker-compose exec st2client bash to be dropped into a container with st2. At that point, you can just run st2 commands.


$ docker-compose exec st2client bash
Welcome to StackStorm v3.3.0 (Ubuntu 18.04.4 LTS GNU/Linux x86_64)
 * Documentation:
 * Community:
 * Forum:

 Here you can use StackStorm CLI. Examples:
   st2 action list --pack=core
   st2 run core.local cmd=date
   st2 run core.local_sudo cmd='apt-get update' --tail
   st2 execution list

root@aaabd11745f0:/opt/stackstorm# st2 run core.echo message="from the inside"
id: 5eb310f571af8f57a4582430
action.ref: core.echo
context.user: st2admin
  message: from the inside
status: succeeded
start_timestamp: Wed, 06 May 2020 19:33:09 UTC
end_timestamp: Wed, 06 May 2020 19:33:09 UTC
  failed: false
  return_code: 0
  stderr: ''
  stdout: from the inside
  succeeded: true

Pack Configuration

Pack configs will be in /opt/stackstorm/configs/$PACKNAME, which is a docker volume shared between st2api, st2actionrunner, and st2sensorcontainer. You can use the st2 pack config <packname> in the st2client container in order to configure a pack.

Use st2 pack config

$ docker-compose exec st2client st2 pack config git
repositories[0].branch [master]:
~~~ Would you like to add another item to  "repositories" array / list? [y]: n
Do you want to preview the config in an editor before saving? [y]: n
Do you want me to save it? [y]: y
| Property | Value                                                        |
| id       | 5eb3164f566aa824ea88f536                                     |
| pack     | git                                                          |
| values   | {                                                            |
|          |     "repositories": [                                        |
|          |         {                                                    |
|          |             "url":                                           |
|          | "",         |
|          |             "branch": "master"                               |
|          |         }                                                    |
|          |     ]                                                        |
|          | }                                                            |

Copy a config file into a container

First, find the actual container name of st2api by running docker-compose ps st2api.

$ docker-compose ps st2api
      Name                    Command               State    Ports  
compose_st2api_1   /opt/stackstorm/st2/bin/st ...   Up      9101/tcp

Next, use docker cp to copy your file into place.

docker cp git.yaml compose_st2api_1:/opt/stackstorm/configs/git.yaml

Register the pack config

If you used docker cp to copy the config in, you will need to manually load that configuration. The st2client service does not need access to the configs directory, as it will talk to st2api.

$ docker-compose exec st2client st2 run packs.load packs=git register=configs
id: 5eb3171c566aa824ea88f538
action.ref: packs.load
context.user: st2admin
  - git
  register: configs
status: succeeded
start_timestamp: Wed, 06 May 2020 19:59:24 UTC
end_timestamp: Wed, 06 May 2020 19:59:25 UTC
  exit_code: 0
    configs: 1
  stdout: ''

Local Pack Development

See Create and Contribute a Pack for how to actually develop a pack.

If you are working on a development pack, you will need to register it and install the virutalenv (if it's python). directory

As mentioned above, your default directory is relative to your docker-compose.yml file. However, if you start developing here, git will not like being inside another git directory. You will want to set ST2_PACKS_DEV to a directory outside of st2-docker and restart the docker-compose services.

Example: We have a pack called helloworld in The directory name has to match the pack name. So even if you have a git repo named "st2-helloworld", it should be cloned locally as "helloworld".

For these examples, we will be operating inside the st2client container.

Register the pack

Register the pack by running st2 run packs.load packs=<pack1>,<pack2> register=all. Alternatively you can specify different register option (like register=actions) to focus on the parts you need to (re)register. You will be running this command a lot as you develop actions, sensors, rules and workflows.

root@aaabd11745f0:/opt/stackstorm# st2 run packs.load packs=helloworld register=all
id: 5eb3100f71af8f57a458241f
action.ref: packs.load
context.user: st2admin
  - helloworld
  register: all
status: succeeded
start_timestamp: Wed, 06 May 2020 19:29:19 UTC
end_timestamp: Wed, 06 May 2020 19:29:21 UTC
  exit_code: 0
    actions: 13
    aliases: 0
    configs: 0
    policies: 0
    policy_types: 3
    rule_types: 2
    rules: 0
    runners: 15
    sensors: 0
    triggers: 0

Create the Python Virtual Environment

If you are using python-runners in your locally developed pack, you will need to create the virtual environment by hand. You should typically only have to run this if you have changed your requirements.txt.

To setup the virtual environment: st2 run packs.setup_virtualenv packs=<pack1>,<pack2>

root@aaabd11745f0:/opt/stackstorm# st2 run packs.setup_virtualenv packs=helloworld
id: 5eb311f871af8f57a4582433
action.ref: packs.setup_virtualenv
context.user: st2admin
  - helloworld
status: succeeded
start_timestamp: Wed, 06 May 2020 19:37:28 UTC
end_timestamp: Wed, 06 May 2020 19:37:36 UTC
  exit_code: 0
  result: 'Successfully set up virtualenv for the following packs: helloworld'
  stderr: 'st2.actions.python.SetupVirtualEnvironmentAction: DEBUG    Setting up virtualenv for pack "helloworld" (/opt/stackstorm/
    st2.actions.python.SetupVirtualEnvironmentAction: INFO     Virtualenv path "/opt/stackstorm/virtualenvs/helloworld" doesn''t exist
    st2.actions.python.SetupVirtualEnvironmentAction: DEBUG    Creating virtualenv for pack "helloworld" in "/opt/stackstorm/virtualenvs/helloworld"
    st2.actions.python.SetupVirtualEnvironmentAction: DEBUG    Creating virtualenv in "/opt/stackstorm/virtualenvs/helloworld" using Python binary "/opt/stackstorm/st2/bin/python"
    st2.actions.python.SetupVirtualEnvironmentAction: DEBUG    Running command "/opt/stackstorm/st2/bin/virtualenv -p /opt/stackstorm/st2/bin/python --always-copy --no-download /opt/stackstorm/virtualenvs/helloworld" to create virtualenv.
    st2.actions.python.SetupVirtualEnvironmentAction: DEBUG    Installing base requirements
    st2.actions.python.SetupVirtualEnvironmentAction: DEBUG    Installing requirement six>=1.9.0,<2.0 with command /opt/stackstorm/virtualenvs/helloworld/bin/pip install six>=1.9.0,<2.0.
    st2.actions.python.SetupVirtualEnvironmentAction: DEBUG    Installing pack specific requirements from "/opt/stackstorm/"
    st2.actions.python.SetupVirtualEnvironmentAction: DEBUG    Installing requirements from file /opt/stackstorm/ with command /opt/stackstorm/virtualenvs/helloworld/bin/pip install -U -r /opt/stackstorm/
    st2.actions.python.SetupVirtualEnvironmentAction: DEBUG    Virtualenv for pack "helloworld" successfully created in "/opt/stackstorm/virtualenvs/helloworld"
  stdout: ''

Remove everything

If you want to uninstall, or start from a "clean" installation, docker-compose can remove all the containers and volumes in one comamnd.

docker-compose down --remove-orphans -v