Git Product home page Git Product logo

st2docs's Introduction

StackStorm

StackStorm is a platform for integration and automation across services and tools, taking actions in response to events. Learn more at www.stackstorm.com.

Build Status

Writing the Docs

Product documentation for StackStorm is maintained in this repository. These docs are built using Sphinx.

Contributing

  • Fork this repo on GitHub (https://help.github.com/articles/fork-a-repo/).
  • Make changes to the docs using your favorite editor.
  • To update docs for the latest - i.e. unstable - release of StackStorm, base your changes off the master branch.
  • To update docs for a released version of StackStorm pick the appropriate version branch (v1.2 etc) and make changes.
  • Push changes to your fork.
  • Create a pull request (https://help.github.com/articles/creating-a-pull-request/) against StackStorm/st2docs repository to upstream the changes.
  • Wait for Travis to complete and one of the StackStorm team shall merge the change.

Build and Run the Docs.

Build locally on Linux

Follows these steps to build the docs locally:

Install the dependencies:

For Debian/Ubuntu: sudo apt-get install python-dev libssl-dev libldap2-dev libsasl2-dev ldap-utils

For RHEL/CentOS: sudo dnf install python2-devel python3-devel openldap-devel

git clone https://github.com/StackStorm/st2docs.git
cd st2docs
make docs

Keep in mind that the initial make docs run will take a while because it needs to install all the Python dependencies which are needed to build the docs.

make livedocs builds the docs and runs the doc site live at http://localhost:8000 to validate changes locally prior to committing any code.

Run with Docker

make docker-build
make docker-run

This will build a docker image and run it in a container, serving docs live at http://localhost:8000. Edit the sources and enjoy live updates.

Before pushing the PR, it's good idea to run a full build and catch any warnings which will fail the official build. Here is how:

run --rm -it -v "$PWD"/docs/source:/st2docs/docs/source st2/st2docs /bin/bash -c "make .cleandocs ; make .docs"

Running docs only

To make docs changes, without installing full development environment (e.g., on Mac or Windows):

git clone [email protected]:StackStorm/st2docs.git
cd st2docs
make docs
# make docs will fail; ignore the failure:
# it will get st2 and set up virtualenv with sphinx/shinx-autobuild
. virtualenv/bin/activate
sphinx-autobuild -H 0.0.0.0 -b html ./docs/source/ ./docs/build/html

Edit, enjoy live updates.

For Windows users:

  1. Install Docker

  2. Run Docker QuickStart Terminal.This way these instructions work as-is (otherwise you will need to convert these instructions to work with a Windows command prompt)

  3. cd to docs directory, e.g.:

    cd /c/Users/stanley/st2docs
  4. activate virtualenv:

    . virtualenv/scripts/activate
  5. Run

    sphinx-autobuild -H 127.0.0.1 -b html ./docs/source/ ./docs/build/html
  6. Connect to http://localhost:8000 Edit files. Watch live updates. Enjoy.

Sphinx Tricks

  • TODO (Use http://localhost:8000/todo.html for full TODO list (must be empty when we ship):

    .. todo:: Here is a TODO
  • Code fragment:

    .. code-block:: bash
    
        # List all available triggers
        st2 trigger list
  • Reference the document

    :doc:`/start`
    :doc:`in the Rules doc </rules>`
  • Referencing an arbitrary section: for instance, there's examples section in sensors.rst. Define a reference on examples section in sensors.rst:

    .. _sensors-examples:

    and point to it as from this, or from other documents as:

    :ref:`sensors-examples`
    :ref:`My examples <sensors-examples>`

    Note that the leading _ underscore is gone, and the reference is quoted.

    Name convention for references is _filename-refname (because they are unique across the docs). Note that there is no way to reference just a point in the docs. See http://sphinx-doc.org/markup/inline.html#cross-referencing-syntax

  • External links:

    `External link <http://webchat.freenode.net/?channels=stackstorm>`_
  • Include a document, full body:

    .. include:: /engage.rst
  • Link to GitHub st2 repo

    :github_st2:`st2/st2common/st2common/operators.py </st2common/st2common/operators.py>`
  • Link to Github StackStorm-Exchange org:

    :github_exchange:`Link to a sensu pack repo inside Exchange<stackstorm-sensu>`
  • Link to StackStorm Exchange website with a filter query:

    :web_exchange:`Sensu<sensu>`
  • Link to the Exchange website on Github (using a global we set up in source/conf.py)

    `exchange`_
  • The pattern to include an example from /st2/contrib/examples: make example file name a reference on github. May say that it is deployed to /usr/share/doc/st2/examples/, and auto-include the file:

    Sample rule: :github_st2:`sample-rule-with-webhook.yaml
    </contrib/examples/rules/sample-rule-with-webhook.yaml>` :
    
    .. literalinclude:: /../../st2/contrib/examples/rules/sample_rule_with_webhook.yaml
        :language: json

Pandoc - convert md <-> rst and more

pandoc - a super-tool to convert between formats. Sample for markdown conversion:

sudo apt-get install pandoc
pandoc --from=markdown --to=rst --output=README.rst README.md

Misc

It's ironic that I use Markdown to write about rST tricks.

st2docs's People

Contributors

amanda11 avatar andrew-regan avatar anirudhbagri avatar arm4b avatar armab avatar bigmstone avatar blag avatar cmd-not-found avatar cognifloyd avatar emedvedev avatar enykeev avatar humblearner avatar jjm avatar kami avatar lakshmi-kannan avatar lindsayhill avatar m4dcoder avatar mahesh-orch avatar mamercad avatar manasdk avatar mdsarmie avatar mierdin avatar nmaludy avatar nzlosh avatar punkrokk avatar samirsss avatar sidkrishna avatar userlocalhost avatar warrenvw avatar winem avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

st2docs's Issues

Travis build fails

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

apt-get install st2 fails troubleshooting docs

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

Modernize Docs Theme

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:

screen shot 2017-07-28 at 10 43 13 am

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:

CentOS installation notes should include firewall rule requirements

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.

Error on QuickStart examples page on stackstorm website

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 ,

Better docs on "infrastructure as code" and VCS and migrations?

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.

Issue with, "st2 pack" commands through proxy

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

Reference actual system role values

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.

Document RabbitMQ vhost/permissions requirements.

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.

stackstorm and chatops behind a proxy

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:

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.

Control search engine indexing

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

Clarify how to get vars from nested chains

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"

ChatOps Tips/Tricks Page

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:

Migrate from Travis to CircleCI

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.

Clarify datastore requirements

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.

Developer environment setup may need some tweaks

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?

Installation docs should stress requirement for CLEAN system for one-line install

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?

Documentation improvements for the new packages

  • 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.)

Document enum type

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

ST2 installation doc change to reduce confusion with Automation Suites

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

Document pre-canned parameters for runner types

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.

Add 'openssl-devel' as requirement for Fedora when running from source

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.

Use quotes everywhere where passwords are used/generated

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.

System requirements should clarify partition sizing requirements

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.

Structuring Python Actions of Med/High Complexity

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.

Explain use case for directly using execution API

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)

Adding Documentation about the gunicorn_peacan and the usage to debug parts of st2

@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 :-)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.