This recent pull request started to clear things up, most specifically in the Updates and Upgrades document. But I still really can't find anywhere in the docs that detail how to properly store your configuration within st2.

The "Updates and Upgrades" doc includes statements like "all StackStorm content and artifacts are simple files, and should be kept under source control" and "Package all your pack from the old VERSION_OLD instance and place them under some SCM like git (you should have done it long ago)", but where are the instructions on how to do this, and what to place in a VCS?

I've shied away from diving into st2 for this very reason. I see lots of talk of mongo and postgres and whatnot, and just assumed there'd be a bunch of configuration in a database somewhere (which is not the direction I want to go). This new doc makes it sound like that's not the case, so this is a large hole in the docs.

Make sure enum type clearly documented, and explain that it will appear as drop-down box in st2web

The installation docs https://docs.stackstorm.com/install/ say "Get yourself a clean 64-bit Linux box that fits the system requirements."

For a one-line install, it assumes a clean, basic system. But people try to run the installer on customized systems that have things like non-standard authentication and $HOME setups, and this breaks. It is possible to install ST2 on those systems, but it needs to be a manual install, not a one-line install.

We have added checks to the one-line install script to look for things like disk space, ports in use, etc. That helps, but we can't catch everything.

We need to update the docs to stress this more clearly - a one-line install only works on an unadulterated Linux system. Perhaps a warning box, or similar?

Leaving this here per a request to do so when I mentioned it on IRC:

on the stackstorms docs pages (start page [start.html]) ... the example:

#And for fun, same post with st2" is broken -- "# And for fun, same post with st2
# st2 run core.http method=POST body='{"you": "too", "name": "st2"}' url=https://localhost/api/v1/webhooks/sample headers='x-auth-token=put_token_here;content-type=application/json' verify_ssl_cert=False"

; should be a ,

The HA docs (https://docs.stackstorm.com/reference/ha.html) don't mention how to use rabbit or mongodb in HA mode, the normal config docs do: https://docs.stackstorm.com/install/config/config.html

We need some documentation on how to utilize and work with /v1/stream API endpoint.

In the docs, it's not obvious which default parameters come with each runner type. I opened this issue: StackStorm/st2#3251 before I knew the hosts argument was built in to the run-remote-script runner, and I was beating my head on the desk for a while wondering why stackstorm was complaining about me not providing a parameter that wasn't defined in the action metadata.

I only found this out by finding another example - the docs should definitely be clearer here.

Many people have problem with figuring this out. Take this example and put it in docs.
https://github.com/StackStorm/st2cd/blob/master/actions/workflows/st2_get_installed_version.yaml#L24

At https://docs.stackstorm.com/ we show latest link for the current st2docs master which is development branch.

The proposal is to rename it to dev or similar, because it's more explicit and latest might be understood as latest stable.

This will also require a path update for the st2cd machinery.

make docs assumes that the docs branch has a matching branch on st2 which is the incorrect assumption.

Fix the branch fixation by referring to version.txt

I'm not sure exactly of the specifics but i tried following the documentation for "setting up a developer environment" here: https://docs.stackstorm.com/development/index.html#setting-up-a-development-environment

This basically states that i need to use st2vargrant or "one liner" install.

With this default install i was not able to run the unit tests because MongoDB had authorization enabled. Disabling authorization allowed me to start running unit tests.

Not sure if there are other steps that need to be followed above and beyond the "one liner" install phase?

• One person tried to install st2 in i386 and he could never install. Packagecloud said this is apt specific. apt doesn't give appropriate error message. So let's note in docs.
• Another user complained about hash sum mismatch. This http://askubuntu.com/questions/41605/trouble-downloading-packages-list-due-to-a-hash-sum-mismatch-error fixed the issue for them. Manas also found http://blog.packagecloud.io/eng/2016/03/21/apt-hash-sum-mismatch/.

We should add a troubleshooting doc here https://github.com/StackStorm/st2docs/tree/master/docs/source/troubleshooting

passwd_kv = self.action_service.get_value(name=lookup_key, local=False, decrypt=True)

The documentation says:
To display subtasks, run st2 execution get <execution-id> --tasks

It looks like the default for st2 execution get displays all subtasks by default?

https://github.com/StackStorm/st2docs/blob/ed3fa0c113d1d0681c7e6e4a46cc91733bfa9dea/docs/source/reference/ha.rst contains references to https://gist.github.com/manasdk/fce14029900e533a385d. I don't plan to delete these anytime soon but perhaps a better idea to take over the content. Perhaps put it under a StackStorm owned and managed github users gist.

Pack config files at /opt/stackstorm/configs/.yaml when created manually should be given owner:group = st2:root. Docs can be updated to state this for cases when user does not use st2 pack config <pack> for configuring pack.

Related to: https://github.com/StackStorm/ops-infra/pull/126#discussion_r109145971

Steps for "Start Services" & "Register sensors, rules and actions" are listed twice in the doc. Should be needed only once.

Please document somewhere what permissions StackStorm needs in RabbitMQ. Questions to cover:

• What is the default user/pass? (guest/guest) Where can that be changed?
• What is the default vhost and are alternative vhosts supported (and where to configure that)?
• What permissions are required? configure, read, and write privs: Does ST2 require * for each?

As @LindsayHill said in slack:

There's a small mention in the docs about vhost in connection string
https://docs.stackstorm.com/install/config/config.html#configure-rabbitmq
Doesn't cover permissions though

A Note on Security points out where the RabbitMQ connection settings need to be configured.

While reviewing 2.1 docs, our team ended up searching the st2 source repo to track down the actual values of the three system roles:

https://github.com/StackStorm/st2/blob/8e7572bc132713582193e3056a489a444e485997/st2common/st2common/rbac/types.py#L213

We'd like to see the values for these roles documented in the following section:

https://docs.stackstorm.com/2.1/rbac.html#system-roles

Previously, we were unaware of these system roles and had implemented several custom roles instead.

A user was noticing duplicate chatops aliases when they made changes to them - apparently st2chatops caches each iteration of these.

Turns out, restarting st2chatops reloads these from the filesystem, so we should add a note to the docs that highlights this.

Maybe consider adding here: https://docs.stackstorm.com/chatops/aliases.html#removing

https://docs.stackstorm.com/webhooks.html#api-key-based should point to https://docs.stackstorm.com/authentication.html?highlight=api%20key#api-keys

jeremybr on slack:

https://docs.stackstorm.com/sensors.html#creating-a-sensor shows a blank class as the sample sensor impl. I can just look in the installed packs but I would fix this. the SamplePollingSensor is blank too.

https://docs.stackstorm.com/packs.html#configuring-a-pack does not mention register-configs

st2ctl reload --register-configs must be run for the pack to pickup configs.

It says:
"There are more nice tricks on pack configuration, see Pack Configuration."

But appears to be requirement not a trick.

Please add a link for:
https://docs.stackstorm.com/authentication.html#api-keys on the manual install docs so that when doing a manual install it is noted that you will need to create an api key in order for chatops to work properly

To Add a note to the installation docs, and to reference/proxy for https://stackstorm.com/2017/02/10/installing-stackstorm-offline-systems/

Moving to package managers will be a big help, but the transition may be confusing (i.e. 1.2 -> 1.3 is not supported via package manager). Perhaps the docs can clear up some confusion?

https://docs.stackstorm.com/sensors.html#debugging-a-sensor-from-a-pack

root@stackstorm:/opt/stackstorm# st2sensorcontainer
st2sensorcontainer: command not found

If a user installs a new CentOS 7.x system from installation ISO, by default the local firewall will block all non-SSH traffic.

This is confusing for users who do not have the Linux experience to diagnose & remediate firewall configurations. We do not want to automatically reconfigure the user's firewall settings, but we should help them resolve it, by providing the commands they can run to resolve it.

Our documentation for installing ST2 on CentOS 7.x should include info about running these commands to add rules to allow HTTP & HTTPS traffic, and to make those changes survive reboot:

firewall-cmd --zone=public  --add-service=http --add-service=https
firewall-cmd --zone=public --permanent --add-service=http --add-service=https

We probably also need to update the main install page with a reference to these firewall rule changes.

NB: If you use Vagrant and the centos/7 box, it does not have this issue. firewalld is installed, but is disabled by default. This is only an issue if you are installing from the CentOS ISO.

I'm going to open this as an issue first to get some notes in place. Maybe after some thinking and discussion, we can shape this into PR against the proxy readme. I'm new to stackstorm, and new to npm/nodejs modules. So I'm trying to take knowledge from working in linux and python and apply it to this arena. That doesn't always work. For example, one of the first thing I found is that hubot uses an npm http library that doesn't honor HTTP_PROXY type environment variables.

uppercase vs lowercase

My first comment is that most of the docs reference HTTP_PROXY and HTTPS_PROXY capital, which is ok. But I think we should make mention that the lowercase variants of these often take precedence in linux. Another variable that is useful, but does not seem to be implemented very well through npm modules is NO_PROXY or no_proxy variable, which is standard in linux to exclude sites from hitting the proxy. Great for excluding localhost. See my example in ansible-st2.

Upper vs lowercase:

• https://superuser.com/questions/876100/https-proxy-vs-https-proxy
• https://curl.haxx.se/docs/manpage.html
• http://unix.stackexchange.com/questions/212894/whats-the-right-format-for-the-http-proxy-environment-variable-caps-or-no-ca

getting hubot to use proxies in general

For hubot, they provide instructions for getting hubot to work behind a proxy. To make that work, simply create a file /opt/stackstorm/chatops/scripts/proxy.coffee with the following, and that will cause hubot and most scripts to work through a proxy. It does not have provisions like NO_PROXY to exclude localhost. There is no need to edit external-scripts.json, as hubot will load any file in this scripts directory.

proxy = require 'proxy-agent'
module.exports = (robot) ->
  robot.globalHttpOptions.httpAgent  = proxy('http://my-proxy-server.internal', false)
  robot.globalHttpOptions.httpsAgent = proxy('http://my-proxy-server.internal', true)

In addition to npm install proxy-agent, I had to npm install proxy, which probably should be a dependency, but wasn't.

getting slack to work through proxy.

You do not need to create the hubot scripts/proxy.coffee script to get slack to work.

The slack adapter (and probably all of the adapters) load before the scripts are loaded. I learned that hubot-slack added a fix to read the https_proxy environment variable (lowercase only) in [email protected]. My freshly installed version had [email protected].

npm upgrade hubot-slack upgraded the depency modules and brought in slack/[email protected] under hubot-slack. Once this is done, you can add https_proxy=http://proxy:3128/ to your st2chatops.env file and restart st2chatops service.

The current theme is showing its age. In particular, literally 40% of the page is totally blank, unused space due to the fact that the content body is so narrow:

As you can see, this presents problems for content that must occupy a certain amount of space.

We should consider adopting a more modern-looking theme, one that uses the full screen. Some notable examples are:

• Kubernetes
• Salt

I had issues initially getting the, st2 pack commands working with a proxy. I had followed the instructions from:
https://docs.stackstorm.com/reference/proxy.html?highlight=proxy

When i ran a, st2 pack search monitoring I got the following output:
400 Client Error: Bad Request MESSAGE: No results from the index: tried https://index.stackstorm.org/v1/index.json. Status: [ { "url": "https://index.stackstorm.org/v1/index.json", "message": "SSLError(SSLError(SSLError(\"bad handshake: SysCallError(104, 'ECONNRESET')\",),),)", "error": "unresponsive", "packs": 0 } ] for url: http://127.0.0.1:9101/v1/packs/index/search

Fix

add: HTTP_PROXY and HTTPS_PROXY to the environment
HTTP_PROXY=http://username:password@proxy:port/
HTTPS_PROXY=http://username:password@proxy:port/
no_proxy="127.0.0.1"

RUN:

sudo st2ctl restart

Might be needed - I made these changes too:

Modify: /opt/stackstorm/st2/lib/python2.7/site-packages/st2common/services/packs.py

ADD:

`proxies = {
'http': 'http://username:password@proxy:port',
'https': 'http://username:password@proxy:port',
}'

Modify

request = requests.get(index_url)

To

request = requests.get(index_url, proxies=proxies)

RUN:

sudo st2ctl restart

The following packages are required for successfully build and run st2docs locally on linux:
sudo apt-get install libpython-dev libssl-dev

The README needs to be updated accordingly.

@DoriftoShoes shows me the commands to fix my needle in the stack error.

Starting Singlethreaded st2api Worker

/opt/stackstorm/st2/bin/gunicorn_pecan /opt/stackstorm/st2/lib/python2.7/site-packages/st2api/gunicorn_config.py -k eventlet -b 127.0.0.1:9101 --workers 1 --threads 1 --graceful-timeout 10 --timeout 30

Starting Singlethreaded st2auth Worker

/opt/stackstorm/st2/bin/gunicorn_pecan /opt/stackstorm/st2/lib/python2.7/site-packages/st2auth/gunicorn_config.py -k eventlet -b 127.0.0.1:9100 --workers 1 --threads 1 --graceful-timeout 10 --timeout 30

Want to stage it here for my reference thing, so i dont forget to pr a real doc to the docs when i got the time, or maybe someone other is faster :-)

Under "Essential Mistral Links:" on https://docs.stackstorm.com/mistral.html the link to v2 DSL is out of date.
It links to http://docs.openstack.org/developer/mistral/dsl/dsl_v2.html
But that redirects to https://docs.openstack.org/mistral/latest/
I think it should point to https://docs.openstack.org/mistral/latest/admin/dsl_v2.html

I'm putting this here because I don't have time to do it at the moment and I don't want to forget, but maybe I can submit a PR later.

https://docs.stackstorm.com/actionchain.html#passing-data-between-different-workflows only briefly mentions how actionchains publish variables:

The cumulative published variables are also available in the result of an ActionChain execution under the published property

Could elaborate on this with an example:

---
    chain:

        -
            name: "task1"
            ref: "testpack.chain-nested"
            on-success: "task2"
        -
            name: "task2"
            ref: "core.local"
            parameters:
              cmd: "echo 'inner task said {{ task1.published.myvar }}'"

---
    chain:

          - name: "innertask1"
            ref: "core.noop"
            publish:
                myvar: "FOO"

It seems that the datastore requires that all values be strings. Since it is backed by mongo, I figured it would be happy to store json objects as well. It feels funny to do a json.dumps to store a json object as a string in what is ultimately backed by a json-native document store.

Maybe clarify in the docs about what data types are allowed for datastore values, and hopefully explain why those requirements are there.

Several folks on the community slack channel have asked about relative imports for Python actions, thinking that we were doing something funky with PYTHONPATH.

Need to document the existing behavior wrt PYTHONPATH, and some best practices around structuring code that exceeds a single file

• How to do relative imports, including when the relative import must use .. to go up a directory
• When it's a good idea to put your code in a separate lib and upload to pypi (and some pointers to this)

Just generally need to provide some guidance for those that have more than a simple file for a Python action, and may not know how to properly structure it.

Every few weeks, someone asks about a specific use case, and it would be nice to have a doc that explicitly mentions this.

Basically the "traditional" flow of triggering a rule via webhook, and in turn, calling an action to do some work, is a bit too asynchronous for some - primarily because a webhook doesn't guarantee an execution ID. There are times when users just want to execute an action and get a result back.

When this comes up in slack, we usually just direct the user to the execution API to run an action directly. For instance, you can run st2 --debug run mypack.myaction and see how it executes the action, and periodically queries for the status of the execution.

So we should add something to docs that explains this, so we can point users to it instead of explain. It might also be useful to include a few points about the nginx configuration, as it might be believed that webhooks are the only external service exposed to the network (see this thread)

Proposed by @lakshmi-kannan

Problem

In #community newcomers from time to time suffer finding good/easy ChatOps templating examples, something to start with. (remember Google pack not working).

Idea

The idea is to gather in one doc several useful ChatOps examples with interesting Jinja templating, including screenshots, aka Tips & Tricks.
Something like that:

TODO Briefly:

• Gather & Screenshot more Ideas with Use Cases:
  • service restart
  • something from twitter pack
  • executed in 30s feature demonstration
  • ...
• ...
• Docs page
• Blog Post: "ChatOps Formatting Tips/Tricks"
• It could additionally encourage us to implement more useful Jinja filters (see Ansible example)

We're using CircleCI for most ST2-related projects now, including BWC docs and core ST2.

We should probably move st2docs to CircleCI too, to standardize things.

Documentation should make it clear that passwords, etc should be quoted when used/generated via CLI.

This is to avoid issues like this StackStorm/st2#3216 where the intention is to have a password like pas$word.

If a user enters st2 auth user -p pas$word, the shell will expand $word, usually to a blank string. It should be entered as st2 auth user -p 'pas$word'. Similarly when htpasswd is used to generate a password hash.

Locations such as this should include a note on escaping passwords https://docs.stackstorm.com/authentication.html?highlight=st2%20auth#usage, and we should always use single quotes around passwords where we use st2 auth in the docs.

We need to put a banner on any docs that are not the latest stable version, e.g. similar to that at the top of this page http://www.sphinx-doc.org/en/1.4.9/install.html

RTD uses this Javascript to do that: https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/core/static-src/core/js/doc-embed/version-compare.js

@enykeev do you know how we could integrate something like that into our theme?

At this location (https://bwc-docs.brocade.com/install/index.html) and after the sentence saying the “..install will take about 4 minutes..”, can we add a note to Automation Suite users who already have BWC installed?

Insert this text:
NOTE: If you have already installed Workflow Composer and would like instructions for installing a Workflow Composer Automation Suite, use the Topics List on the left of the screen to locate and select your automation suite.

I uploaded a doc explaining in greater detail.

BWC doc change request.docx

Should we fix this doc to talk about the DatastoreService methods instead? https://docs.stackstorm.com/datastore.html#storing-and-retrieving-from-python-client

https://docs.stackstorm.com/roadmap.html requires massive sync-up.

Last record is:

• Done in v1.1

Looks like it needs more love, like grabbing/sorting all important things that were implemented since that version. Probably blog posts with feature announcements can help.

• Document under which user different st2 components are running
• Document local runner st2actionrunner paswordless sudo requirements
• Document where StackStorm packages are installed (virtualenv path, etc.)

I've tried to run stackstorm from source, on a CentOS 7.3 machine, but failed during 'make requirements'.

After enabling pip output, I saw that gcc fails, due to a missing openssl-devel package.

For Ubuntu libssl-dev is mentioned in the requirements, but for Fedora openssl-devel isn't.

Googling for stackstorm concepts very often leads to very old versions of our docs. We should take steps to ensure that only the latest version comes up in search queries

Current system requirements list total disk size for test & production systems. This works for users that have one large partition, but can cause problems for those with complicated partitioning schemes. We should include some minimum sizes for partitions such as /opt/ and /var.

Note that rabbitmq & mongodb require certain minimum amounts of free space, or they will not operate correctly.