stackstorm / st2docs Goto Github PK
View Code? Open in Web Editor NEWStackStorm Documentation.
Home Page: https://docs.stackstorm.com/
StackStorm Documentation.
Home Page: https://docs.stackstorm.com/
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
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"
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
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 ,
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.
@DoriftoShoes shows me the commands to fix my needle in the stack error.
/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
/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 :-)
Should we fix this doc to talk about the DatastoreService methods instead? https://docs.stackstorm.com/datastore.html#storing-and-retrieving-from-python-client
Please document somewhere what permissions StackStorm needs in RabbitMQ. Questions to cover:
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.
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.
We need some documentation on how to utilize and work with /v1/stream API endpoint.
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
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.
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.
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
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/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.
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?
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.
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
..
to go up a directoryJust 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.
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:
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.
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
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.
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.
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.
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.
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?
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
In #community newcomers from time to time suffer finding good/easy ChatOps templating examples, something to start with. (remember Google pack not working).
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:
twitter
pack30s
feature demonstrationIt 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.
Steps for "Start Services" & "Register sensors, rules and actions" are listed twice in the doc. Should be needed only once.
Make sure enum
type clearly documented, and explain that it will appear as drop-down box in st2web
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
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"
sudo st2ctl restart
Modify: /opt/stackstorm/st2/lib/python2.7/site-packages/st2common/services/packs.py
`proxies = {
'http': 'http://username:password@proxy:port',
'https': 'http://username:password@proxy:port',
}'
request = requests.get(index_url)
request = requests.get(index_url, proxies=proxies)
sudo st2ctl restart
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.
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.
To Add a note to the installation docs, and to reference/proxy for https://stackstorm.com/2017/02/10/installing-stackstorm-offline-systems/
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:
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.
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
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/sensors.html#debugging-a-sensor-from-a-pack
root@stackstorm:/opt/stackstorm# st2sensorcontainer
st2sensorcontainer: command not found
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.
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:
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.
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 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?
passwd_kv = self.action_service.get_value(name=lookup_key, local=False, decrypt=True)
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.
We should add a troubleshooting doc here https://github.com/StackStorm/st2docs/tree/master/docs/source/troubleshooting
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?
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?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.