diff --git a/.circleci/config.yml b/.circleci/config.yml index 3d012d337..4178db360 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -3,7 +3,7 @@ version: 2 jobs: st2docs: docker: - - image: circleci/python:3.6 + - image: circleci/python:3.10 steps: - checkout - run: @@ -12,10 +12,16 @@ jobs: make st2 - restore_cache: key: v2-dependency-cache-{{ checksum "st2/requirements.txt" }} - - run: sudo apt-get update - - run: sudo apt install python3-dev - - run: sudo apt install libldap2-dev - - run: sudo apt install libsasl2-dev + - run: + name: Install developer packages + command: | + PKGS=( + python3-dev + libldap2-dev + libsasl2-dev + ) + sudo apt-get update + sudo apt install ${PKGS[@]} - run: make docs - run: name: Store HTML docs in workspace dir diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..268d5b789 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,62 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Declare the Python requirements required to build docs +python: + install: + - requirements: requirements.txt + # st2/ is st2.git cloned in post_checkout job + - requirements: st2/requirements.txt + +# Set the version of Python and other tools, and customize the build process +build: + os: ubuntu-22.04 + tools: + python: "3.10" + apt_packages: + - python3-dev + - libldap2-dev + - libsasl2-dev + + # https://docs.readthedocs.io/en/stable/build-customization.html#extend-the-build-process + # NOTE: use " instead of ' for all quoting or RTD gives some weird errors. + jobs: + post_checkout: + - ./scripts/clone-st2.sh + - ./scripts/clone-orquesta.sh + + # We can't control the version of pip installed because it is part of the `install` stage. + #pre_install: + # # switch to version of pip from cloned copy of st2 + # - > + # export PIP_VERSION=$(grep "PIP_VERSION ?= " st2/Makefile | awk "{ print \$3 }"); + # echo PIP_VERSION=${PIP_VERSION}; + # pip install --upgrade "pip==${PIP_VERSION}"; + + # install: see python.install above + + post_install: + - cd ./st2; make virtualenv + - cd ./st2; make requirements + # generate-runner-parameters-documentation.py needs this in the st2 virtualenv + - . st2/virtualenv/bin/activate; pip install pytablewriter + + pre_build: + - . st2/virtualenv/bin/activate; ./scripts/generate-runner-parameters-documentation.py + - . st2/virtualenv/bin/activate; ./scripts/generate-internal-triggers-table.py + - . st2/virtualenv/bin/activate; ./scripts/generate-available-permission-types-table.py + +# Build documentation in the docs/ directory with Sphinx +sphinx: + builder: html + configuration: docs/source/conf.py + fail_on_warning: true + +# If using Sphinx, optionally build your docs in additional formats such as PDF +# formats: +# - pdf + diff --git a/Dockerfile b/Dockerfile index 64105561e..c94bd841b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,9 +1,9 @@ -FROM ubuntu:18.04 +FROM ubuntu:22.04 RUN apt-get -qq update && apt-get -q install -y \ curl git \ libffi-dev libldap2-dev libsasl2-dev libssl-dev \ - python3-dev python3-pip python-virtualenv + python3-dev python3-pip python3-virtualenv python3-venv ADD . /st2docs WORKDIR /st2docs diff --git a/Makefile b/Makefile index 708dda962..0aac133a2 100644 --- a/Makefile +++ b/Makefile @@ -11,7 +11,7 @@ DOC_BUILD_DIR := docs/build BINARIES := bin -PYTHON_VERSION := python3.6 +PYTHON_VERSION := python3.10 # All components are prefixed by st2 COMPONENTS := $(wildcard st2*) @@ -208,7 +208,7 @@ docker-build: @echo @echo "==================== Building st2docs Docker ====================" @echo - docker build -t st2/st2docs -f Dockerfile . + docker build --platform=linux/amd64 -t st2/st2docs -f Dockerfile . .PHONY: docker-run docker-run: diff --git a/docs/source/_static/css/rtd_theme_overrides.css b/docs/source/_static/css/rtd_theme_overrides.css new file mode 100644 index 000000000..8fb7c0c6a --- /dev/null +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -0,0 +1,86 @@ +/* layout changes */ +.wy-nav-content { + max-width: none; /* was 800px */ +} +/* Fix for nav bottom padding with flyout */ +nav.wy-nav-side { + padding-bottom: 3em; +} + +/* $base-font-family: Lato,proxima-nova,Helvetica Neue,Arial,sans-serif; */ +.btn { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +input[type="button"], input[type="reset"], input[type="submit"] { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +input[type="color"], input[type="date"], input[type="datetime-local"], input[type="datetime"], input[type="email"], input[type="month"], input[type="number"], input[type="password"], input[type="search"], input[type="tel"], input[type="text"], input[type="time"], input[type="url"], input[type="week"] { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +textarea { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +body { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-versions { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} + +/* $custom-font-family: Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif */ +.rst-content .toctree-wrapper>p.caption, h1, h2, h3, h4, h5, h6, legend { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-content .sidebar .sidebar-title { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} + +/** + * st2 orange: #fb8225 + * 5% lighter: #fb903e + * 20% darker: #b75103 + * + * st2 gray: #4d585a + * 5% lighter: #596568 + **/ +.wy-menu-vertical li.current a:hover { + color: #b75103; +} +.wy-menu-vertical li a:hover { + color: #fb8225; +} +.wy-menu-vertical li.on a:hover, .wy-menu-vertical li.current > a:hover { + color: #b75103; +} +.wy-menu-vertical li.toctree-l2.current>a { + background-color: #fb8225; + color: #FFF; +} +.wy-side-nav-search { + background-color: #fb8225; +} +.wy-menu-vertical header,.wy-menu-vertical p.caption { + color: #fb903e; +} +.wy-side-nav-search input[type=text] { + border-color: #fcd531; +} + +.wy-menu-vertical a:hover { + background-color: #596568; +} +.wy-nav-top, .wy-nav-side { + background: #4d585a; +} + +.wy-side-nav-search .wy-dropdown>a img.logo, .wy-side-nav-search>a img.logo { + display: block; + width: 160px; + + /* svg defaults to fill: #000 */ + filter: invert(100%); /* effectively - fill: #fff */ +} + +.wy-breadcrumbs li a.icon-home:before { + content: "" /* drop the icon. js will add content */ +} diff --git a/docs/source/_static/css/rtd_theme_overrides.unused.css b/docs/source/_static/css/rtd_theme_overrides.unused.css new file mode 100644 index 000000000..8c26ea6e2 --- /dev/null +++ b/docs/source/_static/css/rtd_theme_overrides.unused.css @@ -0,0 +1,25 @@ +/* $code-font-family: SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace; */ +.rst-content code, .rst-content tt, code { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-content footer span.commit tt, footer span.commit .rst-content tt, footer span.commit code { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-content pre.literal-block { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-content .linenodiv pre { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-content .linenodiv pre, .rst-content div[class^=highlight] pre, .rst-content pre.literal-block { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-content code, .rst-content tt { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-content kbd,.rst-content pre,.rst-content samp { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +html.writer-html4 .rst-content dl:not(.docutils) .descclassname,html.writer-html4 .rst-content dl:not(.docutils) .descname,html.writer-html4 .rst-content dl:not(.docutils) .sig-name,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .sig-name { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/css/theme_overrides.css similarity index 100% rename from docs/source/_static/theme_overrides.css rename to docs/source/_static/css/theme_overrides.css diff --git a/docs/source/_static/images/favicon.ico b/docs/source/_static/images/favicon.ico new file mode 100644 index 000000000..64880c4f5 Binary files /dev/null and b/docs/source/_static/images/favicon.ico differ diff --git a/docs/source/_static/images/logo.svg b/docs/source/_static/images/logo.svg new file mode 100644 index 000000000..a8cca4733 --- /dev/null +++ b/docs/source/_static/images/logo.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + diff --git a/docs/source/_static/js/rtd_theme_overrides.js b/docs/source/_static/js/rtd_theme_overrides.js new file mode 100644 index 000000000..9bd644247 --- /dev/null +++ b/docs/source/_static/js/rtd_theme_overrides.js @@ -0,0 +1,9 @@ +$( document ).ready(function() { + // Open external links in another tab/window + $(".external").attr("target","_blank"); + // List the docs version in breadcrumbs + $(".wy-breadcrumbs li a.icon-home").text( + // DOCUMENTATION_OPTIONS is a sphinx feature + "Docs v" + DOCUMENTATION_OPTIONS.VERSION + ) +}); diff --git a/docs/source/_static/js/versions.js_t b/docs/source/_static/js/versions.js_t new file mode 100644 index 000000000..64b24a082 --- /dev/null +++ b/docs/source/_static/js/versions.js_t @@ -0,0 +1,40 @@ +(function () { + function renderVersionBadge(versions, currentVersion) { + var versionsContainer = $('
Versions
'); + $.each(versions, function (slug, url) { + versionsContainer.append('
' + slug + '
'); + }); + + var otherVersions = $('
').append(versionsContainer); + + var container = $('
'); + container.append('v: ' + currentVersion + ' '); + container.append(otherVersions); + + $('#versions').replaceWith(container); + } + + function showVersionWarning() { + $('#version-warning').show(); + } + + $(document).ready(function () { + var latestVersion = "{{ current_version }}"; + + var versions = { + {%- for slug, url in versions %} + "{{ slug }}": "{{ url }}", + {%- endfor %} + }; + + var currentVersion = latestVersion; + + var match = window.location.pathname.match('^/(\\d+\\.\\d+)'); + if (match) { + currentVersion = match[1]; + showVersionWarning(); + } + + renderVersionBadge(versions, currentVersion); + }); +})() diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html new file mode 100644 index 000000000..9a7ac6fb4 --- /dev/null +++ b/docs/source/_templates/layout.html @@ -0,0 +1,40 @@ +{%- extends "!layout.html" %} + +{#- + +This template exists as a way to implement a version menu in local builds +without changing what normally renders in builds on Read the +Docs. +Based on: +https://github.com/readthedocs/sphinx_rtd_theme/blob/master/docs/_templates/layout.html +https://github.com/readthedocs/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/versions.html + +#} + +{%- block footer %} + {%- if not READTHEDOCS %} +
+ + + v: {{ current_version }} + + +
+
+
{{ _('Versions') }}
+ {% for slug, url in versions %} +
{{ slug }}
+ {% endfor %} +
+ {% if downloads %} +
+
{{ _('Downloads') }}
+ {% for type, url in downloads %} +
{{ type }}
+ {% endfor %} +
+ {% endif %} +
+
+ {%- endif %} +{%- endblock %} diff --git a/docs/source/_themes/sphinx_rtd_theme/__init__.py b/docs/source/_themes/sphinx_rtd_theme/__init__.py index 40411f094..9fbad4d92 100644 --- a/docs/source/_themes/sphinx_rtd_theme/__init__.py +++ b/docs/source/_themes/sphinx_rtd_theme/__init__.py @@ -19,22 +19,25 @@ def setup(app): """Setup connects events to the sitemap builder""" - app.connect('html-page-context', add_html_link) - app.connect('build-finished', create_sitemap) + app.connect("html-page-context", add_html_link) + app.connect("build-finished", create_sitemap) app.sitemap_links = [] def add_html_link(app, pagename, templatename, context, doctree): """As each page is built, collect page names for the sitemap""" - base_url = app.config['html_theme_options'].get('base_url', '') + base_url = app.config["html_theme_options"].get("base_url", "") if base_url: app.sitemap_links.append(base_url + pagename + ".html") def create_sitemap(app, exception): """Generates the sitemap.xml from the collected HTML page links""" - if (not app.config['html_theme_options'].get('base_url', '') or - exception is not None or not app.sitemap_links): + if ( + not app.config["html_theme_options"].get("base_url", "") + or exception is not None + or not app.sitemap_links + ): return filename = app.outdir + "/sitemap.xml" diff --git a/docs/source/actionchain.rst b/docs/source/actionchain.rst index 828f70e48..b67c1b8ee 100644 --- a/docs/source/actionchain.rst +++ b/docs/source/actionchain.rst @@ -106,7 +106,7 @@ ActionChain definition: # ... ``action1_input`` has value ``{{input1}}``. This syntax is variable referencing as supported by -`Jinja templating `__. +`Jinja templating `__. Similar constructs are also used in :doc:`Rule ` criteria and action fields. diff --git a/docs/source/authentication.rst b/docs/source/authentication.rst index 39db1ba82..35e6ba1c3 100644 --- a/docs/source/authentication.rst +++ b/docs/source/authentication.rst @@ -203,7 +203,7 @@ configuration options for the backend: | | | | LDAP server will still be performed when user authenticates to st2auth - authentication information is not cached - only | | | | | user groups are cached. | +-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| cache_user_groups_ttl | no | `120` | How long (in seconds) | +| cache_user_groups_cache_ttl | no | `120` | How long (in seconds) | +-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ .. note:: diff --git a/docs/source/chatops/aliases.rst b/docs/source/chatops/aliases.rst index a94293e9f..8e507c05d 100644 --- a/docs/source/chatops/aliases.rst +++ b/docs/source/chatops/aliases.rst @@ -373,6 +373,26 @@ depending on execution status: To disable the result message, you can use the ``enabled`` flag in the same way as in ``ack``. +Threading Replies (Slack) +^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can configure the hubot ``ack`` and ``result`` messages to be sent as a threaded reply to the invoked command in slack. This defaults to false if not set. + +.. code-block:: yaml + + ack: + extra: + slack: + thread_response: true + format: ":green-check: Querying those items for you..." + append_url: false + result: + extra: + slack: + thread_response: true + format: | + ```{{execution.result.output.results}}``` + Plaintext Messages (Slack) ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/chatops/chatops.rst b/docs/source/chatops/chatops.rst index 56fc76c76..6d544855b 100644 --- a/docs/source/chatops/chatops.rst +++ b/docs/source/chatops/chatops.rst @@ -50,19 +50,18 @@ Officially Supported Chat Providers We officially provide support for the following chat providers with hubot: -* `Slack `_ -* Microsoft Teams (via `BotFramework `_) -* `Mattermost version 5 `_ -* `Rocket.Chat `_ -* `Cisco Spark `_ +* `Slack `_ Officially Unsupported Chat Providers ===================================== -We do not provide support for the following adapters, but they are still bundled in the -st2chatops package, can be configured in ``st2chatops.env``, and still work (as far as we -know). +We do not provide support for the following adapters as of st2chatops 3.9. They are still bundled in the +st2chatops 3.8 package, and can be configured in ``st2chatops.env``, and may still work. +* Microsoft Teams (via `BotFramework `_) See :doc:`3.8 documentation ` +* `Mattermost version 5 `_ +* `Rocket.Chat `_ +* `Cisco Spark `_ * `Flowdock `_ * `XMPP `_ * `IRC `_ @@ -70,13 +69,6 @@ know). Configuration ============= -.. note:: - - Configuring st2chatops with Microsoft Teams is a more involved process. Please see - :doc:`our documentation ` specifically for that chat provider. - All other chat providers can be configured in ``st2chatops.env`` with the instructions - below. - Package-based Install ~~~~~~~~~~~~~~~~~~~~~ @@ -84,37 +76,36 @@ If you installed |st2| following the :doc:`install docs `, the ` package will take care of `almost` everything for you. Hubot with the necessary adapters is already installed, and StackStorm :ref:`API keys ` have been configured. -You just need to tell |st2| which Chat service to use - e.g. Slack, MatterMost, etc. You will also need +You just need to tell |st2| which Chat service to use - e.g. Slack. You will also need to give it credentials. Your Chat service may also need configuration. For example, to configure Slack, -you first need to add a new Hubot integration to Slack. You can do this through Slack's admin interface. -Take note of the ``HUBOT_SLACK_TOKEN`` that Slack provides. +you first need to add a new Hubot integration to Slack. You can do this through Slack's admin interface +using the following `example bot yaml definition `_. +Take note of the ``HUBOT_SLACK_BOT_TOKEN`` and ``HUBOT_SLACK_APP_TOKEN`` that Slack provides. Then edit the file ``/opt/stackstorm/chatops/st2chatops.env``. Edit and uncomment the variables for your adapter. For example, if you are configuring Slack, look for this section: .. code-block:: bash - # Slack settings (https://github.com/slackhq/hubot-slack): - # + # Slack App YAML settings (https://github.com/hubot-friends/hubot-slack?tab=readme-ov-file#sample-yaml) + # Confirm your existing Modern Slack App or a newly created Modern slack app has the above permissions # export HUBOT_ADAPTER=slack - # Obtain the Slack token from your app page at api.slack.com, it's the "Bot - # User OAuth Access Token" in the "OAuth & Permissions" section. - # export HUBOT_SLACK_TOKEN=xoxb-CHANGE-ME-PLEASE - # Uncomment the following line to force hubot to exit if disconnected from slack. - # export HUBOT_SLACK_EXIT_ON_DISCONNECT=1 + # Obtain the Bot user OAuth Token on the Oauth & Permissions section + # export HUBOT_SLACK_BOT_TOKEN=xoxb-CHANGE-ME-PLEASE + # Obtain a App-Level Token on the Basic Information section, scopes required: connections:write + # export HUBOT_SLACK_APP_TOKEN=xapp-CHANGE-ME-PLEASE Edit this file so it looks something like this: .. code-block:: bash - # Slack settings (https://github.com/slackhq/hubot-slack): - # + # Slack App YAML settings (https://github.com/hubot-friends/hubot-slack?tab=readme-ov-file#sample-yaml) + # Confirm your existing Modern Slack App or a newly created Modern slack app has the above permissions export HUBOT_ADAPTER=slack - # Obtain the Slack token from your app page at api.slack.com, it's the "Bot - # User OAuth Access Token" in the "OAuth & Permissions" section. - export HUBOT_SLACK_TOKEN=xoxb-SUPER-SECRET-TOKEN - # Uncomment the following line to force hubot to exit if disconnected from slack. - export HUBOT_SLACK_EXIT_ON_DISCONNECT=1 + # Obtain the Bot user OAuth Token on the Oauth & Permissions section + export HUBOT_SLACK_BOT_TOKEN=xoxb-####-####-#### + # Obtain a App-Level Token on the Basic Information section, scopes required: connections:write + export HUBOT_SLACK_APP_TOKEN=xapp-####-####-#### Your specific Chat service may require different settings. Any environment settings needed can be added to this file. @@ -144,8 +135,8 @@ Restart ``st2chatops`` after creating that file. Using an External Adapter ~~~~~~~~~~~~~~~~~~~~~~~~~ -The ``st2chatops`` package includes adapters for common chat services, but if an -adapter for a service you use isn't bundled there, don't worry: you can install it manually. +The ``st2chatops`` package includes adapters for Slack, but if an +adapter for a service you use isn't bundled there, don't worry: you can install it manually or try st2chatops 3.8. For example, here's how to connect |st2| to Yammer using the ``hubot-yammer`` adapter: @@ -261,5 +252,4 @@ Logging ======= ChatOps logs are written to ``/var/log/st2/st2chatops.log`` on non systemd-based distros. For -systemd-based distros (Ubuntu 18/20, RHEL/RockyLinux/CentOS 7/8), you can access the logs via -``journalctl --unit=st2chatops`` +systemd-based distros, you can access the logs via ``journalctl --unit=st2chatops`` diff --git a/docs/source/chatops/index.rst b/docs/source/chatops/index.rst index 346215e5c..b6888e754 100644 --- a/docs/source/chatops/index.rst +++ b/docs/source/chatops/index.rst @@ -50,7 +50,7 @@ Interested in learning more? Here are some things to get you started on your voy :maxdepth: 1 chatops - Configuration for Microsoft Teams + Configuration for Microsoft Teams (3.8) Action Aliases notifications Pack Deployment diff --git a/docs/source/chatops/msteams.rst b/docs/source/chatops/msteams.rst index 9829598b5..38d25b427 100644 --- a/docs/source/chatops/msteams.rst +++ b/docs/source/chatops/msteams.rst @@ -1,6 +1,10 @@ Using Microsoft Teams (with BotFramework) ========================================= +.. warning:: + + This is documentation assumes you are using st2chatops 3.8. Support for Microsoft Teams was removed in 3.9. + Configurating st2chatops with Microsoft Teams is **much** more involved than configuring other chat providers. diff --git a/docs/source/conf.py b/docs/source/conf.py index 071d2d236..c15bcf273 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,21 +16,23 @@ import os import glob +import sphinx_rtd_theme + BASE_DIR = os.path.dirname(os.path.abspath(__file__)) -ROOT_DIR = os.path.abspath(os.path.join(BASE_DIR, '../../st2')) +ROOT_DIR = os.path.abspath(os.path.join(BASE_DIR, "../../st2")) sys.path.append(BASE_DIR) import info # Include Python modules for all the st2components -st2_components_paths = glob.glob(ROOT_DIR + '/st2*') +st2_components_paths = glob.glob(ROOT_DIR + "/st2*") for module_path in st2_components_paths: sys.path.append(module_path) # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('./_themes')) +# sys.path.insert(0, os.path.abspath('./path/to/extension')) from st2common import __version__ @@ -43,23 +45,24 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.intersphinx', - 'sphinx.ext.coverage', - 'sphinx.ext.ifconfig', - 'sphinx.ext.viewcode', - 'sphinx.ext.todo', - 'sphinx.ext.extlinks', - - # Add theme as extension so sitemap.xml is generated - 'sphinx_rtd_theme' + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", + "sphinx.ext.coverage", + "sphinx.ext.ifconfig", + "sphinx.ext.viewcode", + "sphinx.ext.todo", + "sphinx.ext.extlinks", + # theme is provided as an extension + "sphinx_rtd_theme", + # this generates sitemap.xml + "sphinx_sitemap", ] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] # The suffix of source filenames. -source_suffix = '.rst' +source_suffix = ".rst" # The encoding of source files. # source_encoding = 'utf-8-sig' @@ -75,20 +78,52 @@ # # the __version__ is 0.8.1 or 0.9dev # the version is short 0.8 version, to refer docs. -version = '.'.join(__version__.split('.')[:2]) +version = ".".join(__version__.split(".")[:2]) # The full version, including alpha/beta/rc tags. release = __version__ # The complete list of current StackStorm versions. -release_versions = ['3.7', '3.6', '3.5', '3.4', '3.3', '3.2', '3.1', '3.0', '2.10', '2.9', '2.8', '2.7', '2.6', '2.5', '2.4', '2.3', '2.2', '2.1', '2.0', '1.6', '1.5', '1.4', '1.3', '1.2', '1.1', '0.13', '0.12', '0.11', '0.9', '0.8'] +release_versions = ['3.9', + "3.8", + "3.7", + "3.6", + "3.5", + "3.4", + "3.3", + "3.2", + "3.1", + "3.0", + "2.10", + "2.9", + "2.8", + "2.7", + "2.6", + "2.5", + "2.4", + "2.3", + "2.2", + "2.1", + "2.0", + "1.6", + "1.5", + "1.4", + "1.3", + "1.2", + "1.1", + "0.13", + "0.12", + "0.11", + "0.9", + "0.8", +] # Some loveliness that we have to do to make this work. Otherwise it defaults to contents.rst master_doc = info.master_doc def previous_version(ver): - if ver.endswith('dev'): + if ver.endswith("dev"): return release_versions[0] - major_minor = '.'.join(ver.split('.')[:2]) + major_minor = ".".join(ver.split(".")[:2]) if major_minor in release_versions: idx = release_versions.index(major_minor) if idx + 1 < len(release_versions): @@ -96,35 +131,38 @@ def previous_version(ver): # Better than broken return some value. Control flow should not reach this point. return "unknown" + # The short versions of two previous releases, e.g. 0.8 and 0.7 version_minus_1 = previous_version(version) version_minus_2 = previous_version(version_minus_1) +version_minus_3 = previous_version(version_minus_2) # extlink configurator sphinx.ext.extlinks extlinks = { - 'github_st2': ('https://github.com/StackStorm/st2/tree/master/%s', None), - 'github_exchange': - ('https://github.com/StackStorm-Exchange/%s', None), - 'web_exchange': - ('https://exchange.stackstorm.org/#%s', None), + "github_st2": ("https://github.com/StackStorm/st2/tree/master/%s", None), + "github_exchange": ("https://github.com/StackStorm-Exchange/%s", None), + "web_exchange": ("https://exchange.stackstorm.org/#%s", None), } # Inserted at the bottom of all rst files. # Use for variables substitutions -if tags.has('enterprise'): +if tags.has("enterprise"): print("Building EWC docs") product_replace = "\n.. |st2| replace:: EWC\n.. |fullname| replace:: Extreme Workflow Composer" else: print("Building StackStorm docs") product_replace = "\n.. |st2| replace:: StackStorm\n.. |fullname| replace:: StackStorm" -rst_epilog = """ +rst_epilog = ( + """ %s .. _exchange: https://exchange.stackstorm.org/ .. |ewc| replace:: Extreme Workflow Composer .. |ipf| replace:: IP Fabric Automation Suite -""" % product_replace +""" + % product_replace +) # Show or hide TODOs. See http://sphinx-doc.org/ext/todo.html todo_include_todos = True @@ -143,12 +181,12 @@ def previous_version(ver): # directories to ignore when looking for source files. # dzimine: '**/._*' exclues files my Sublime creates on NFS mount. exclude_patterns = [ - '**/._*', - '**/__*', '__*', # Naming convension for include files - '_includes/*', # includes files - 'todo.rst', - 'known_security_issues.rst', - + "**/._*", + "**/__*", + "__*", # Naming convension for include files + "_includes/*", # includes files + "todo.rst", + "known_security_issues.rst", ] # The reST default role (used for this markup: `text`) to use for all @@ -167,7 +205,7 @@ def previous_version(ver): # show_authors = False # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = "sphinx" # A list of ignored prefixes for module index sorting. # modindex_common_prefix = [] @@ -182,9 +220,10 @@ def previous_version(ver): # XXX: temp fix before we figure how to make autodocs work nitpick_ignore = [ - ('py:class', 'st2actions.runners.pythonrunner.Action'), - ('py:class', 'st2common.runners.base_action.Action'), - ('py:class', 'KeyValuePair')] + ("py:class", "st2actions.runners.pythonrunner.Action"), + ("py:class", "st2common.runners.base_action.Action"), + ("py:class", "KeyValuePair"), +] # -- Options for HTML output ---------------------------------------------- @@ -197,13 +236,45 @@ def previous_version(ver): # further. For a list of options available for each theme, see the # documentation. html_theme_options = { - 'base_url': info.theme_base_url, - 'canonical_url': info.theme_base_url + # see: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html + # "style_nav_header_background": "#fb8225", # covered by rtd_theme_overrides.css + "logo_only": True, + # display_version puts rtd slug/version at top of sidebar, but we use breadcrumbs instead +# "display_version": False, # invalid theme, commented out. + "style_external_links": True, + "vcs_pageview_mode": "blob", # blob, edit, raw } +# These paths are either relative to html_static_path +# or fully qualified paths (eg. https://...) +html_css_files = [ + "css/theme_overrides.css", + "css/rtd_theme_overrides.css", + "https://fonts.googleapis.com/css?family=Open+Sans:400,300,300italic,400italic,600,600italic,700,700italic|Inconsolata:400,700", +] +html_js_files = [ + "js/rtd_theme_overrides.js", +] + +# set the canonical url to our custom domain (required for sitemap generation) +html_baseurl = info.base_url +sitemap_filename = "sitemap.xml" +if "READTHEDOCS" in os.environ: + if "dev" in version and os.environ["READTHEDOCS_VERSION_TYPE"] != "external": + # use latest/ instead of 3.8dev/ unless this is external (ie a PR) + _sitemap_version = os.environ["READTHEDOCS_VERSION"] + "/" + else: + # prefer 3.7/ over stable/ in sitemap + _sitemap_version = "{version}" + sitemap_url_scheme = "{lang}" + _sitemap_version + "{link}" +elif "dev" in version: + # use latest/ instead of 3.8dev/ + sitemap_url_scheme = "latest/{link}" +else: + sitemap_url_scheme = "{version}{link}" + # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] -html_theme_path = ["_themes", ] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -214,23 +285,23 @@ def previous_version(ver): # The name of an image file (relative to this directory) to place at the top # of the sidebar. -# html_logo = None +html_logo = "_static/images/logo.svg" # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -# html_favicon = "favicon.ico" +html_favicon = "_static/images/favicon.ico" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ["_static"] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied # directly to the root of the documentation. # html_extra_path = [] -html_extra_path = ['_redirects'] +html_extra_path = ["_redirects"] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. @@ -278,43 +349,62 @@ def previous_version(ver): # Variables to be used by templates html_context = { - 'github_user': info.github_user, - 'github_repo': info.github_repo, - 'github_version': info.github_version, - 'conf_py_path': '/docs/source/', - 'display_github': True, - 'source_suffix': source_suffix, - 'versions': [ - ('latest', '%slatest' % info.base_url), - (version, '%s%s' % (info.base_url, version)), - (version_minus_1, '%s%s' % (info.base_url, version_minus_1)), - (version_minus_2, '%s%s' % (info.base_url, version_minus_2)), - ], - 'current_version': version, - 'css_files': [ - '_static/theme_overrides.css', - ], + # The github settings configure the "Edit on GitHub" link + "display_github": True, + "github_user": info.github_user, + "github_repo": info.github_repo, + "github_version": info.github_version, + "conf_py_path": "/docs/source/", + "source_suffix": source_suffix, } +if "READTHEDOCS" not in os.environ: + # This is for local and GHA builds. Otherwise READTHEDOCS handles versions. + # the versions menu should always be: dev, stable, stable-1, stable-2 + versions = [] + if "dev" in version: + # show the "3.9dev" in the menu, even though "latest" is in the URL. + versions.append((version, "%slatest" % info.base_url)) + else: + _version = version.split(".") + dev_version = "%s.%sdev" % (_version[0], int(_version[1]) + 1) + versions.extend( + [ + (dev_version, "%slatest" % info.base_url), + # this is the stable version + (version, "%s%s" % (info.base_url, version)), + ] + ) + + versions.extend( + [ + (version_minus_1, "%s%s" % (info.base_url, version_minus_1)), + (version_minus_2, "%s%s" % (info.base_url, version_minus_2)), + ] + ) + + if "dev" in version: + # this is the stable-2 version + versions.append((version_minus_3, "%s%s" % (info.base_url, version_minus_3))) + html_context["versions"] = versions + html_context["current_version"] = version + # -- Options for LaTeX output --------------------------------------------- latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples @@ -385,6 +475,6 @@ def previous_version(ver): # texinfo_no_detailmenu = False # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/2': None} +intersphinx_mapping = {"python": ('https://docs.python.org/3', None)} -autoclass_content = 'both' +autoclass_content = "both" diff --git a/docs/source/development/pack_testing.rst b/docs/source/development/pack_testing.rst index 0d681ba08..ee086c7ba 100644 --- a/docs/source/development/pack_testing.rst +++ b/docs/source/development/pack_testing.rst @@ -227,13 +227,13 @@ If you only want to run a specific test file or a method in a test method, you c # class name with the "test_poll" method. # Run all the tests inside that test file / module - st2-run-pack-tests -p /data/packs/docker/ -f test_sensor_docker_sensor + st2-run-pack-tests -p /data/packs/docker/ -f test_sensor_docker_sensor.py # Run all tests in a specific test class - st2-run-pack-tests -p /data/packs/docker/ -f test_sensor_docker_sensor:DockerSensorTestCase + st2-run-pack-tests -p /data/packs/docker/ -f test_sensor_docker_sensor.py::DockerSensorTestCase # Run a single test method from a specific test file - st2-run-pack-tests -p /data/packs/docker/ -f test_sensor_docker_sensor:DockerSensorTestCase.test_poll + st2-run-pack-tests -p /data/packs/docker/ -f test_sensor_docker_sensor.py::DockerSensorTestCase::test_poll As more tests are developed it is always a good idea to determine how much code has been covered by the tests and how much remains un-tested. Calculated test coverage can be printed out using the diff --git a/docs/source/development/sources.rst b/docs/source/development/sources.rst index 7d436654b..7ea8a4994 100644 --- a/docs/source/development/sources.rst +++ b/docs/source/development/sources.rst @@ -1,68 +1,68 @@ :orphan: Run From Sources -================= +======================================================================== Environment Prerequisites -~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Requirements: - git -- python3.6 for Ubuntu 18.04 and CentOS/RHEL 7 -- python3.8 for Ubuntu 20.04 and RockyLinux/CentOS/RHEL 8 +- tig(optional interactive tui for git commits) +- python3.8 for Ubuntu 20.04 and RockyLinux/RHEL 8 +- python3.9 for RockyLinux/RHEL 9 +- python3.10 for Ubuntu 22.04 - pip, virtualenv, tox -- MongoDB (http://docs.mongodb.org/manual/installation) -- RabbitMQ (http://www.rabbitmq.com/download.html) -- screen +- MongoDB + - Ubuntu (https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-ubuntu/) + - RHEL (https://www.mongodb.com/docs/v4.4/tutorial/install-mongodb-on-red-hat/) +- RabbitMQ / Erlang 26.x + - Ubuntu (https://www.rabbitmq.com/docs/install-debian) + - RHEL (https://www.rabbitmq.com/docs/install-rpm) +- Redis Stack (https://redis.io/docs/install/install-stack/linux/) +- tmux Ubuntu ------- - -.. note:: - For Ubuntu 20.04 replace with python3.8 equivalents +------------------------------------------------------------------------ +Install required packages for python development. .. code-block:: bash - apt-get install python-pip python-virtualenv gcc git make realpath screen libffi-dev libssl-dev python3.6-dev libldap2-dev libsasl2-dev - apt-get install mongodb mongodb-server - apt-get install rabbitmq-server + apt-get install python3-pip python3-venv gcc git make tmux libffi-dev libssl-dev python3-dev libldap2-dev libsasl2-dev -RockyLinux/CentOS/RHEL ----------------------- -.. note:: - For RHEL 7.x you may need to enable the optional server rpms repository to be able to install the python3-devel RPM +Install a supported version of MongoDB, RabbitMQ / Erlang and Redis. +`Ubuntu 20.04 Focal ` +`Ubuntu 22.04 Jammy ` + + +Rocky Linux / RedHat Enterprise Linux +------------------------------------------------------------------------ .. code-block:: bash - OSRELEASE_VERSION=`lsb_release -s -r | cut -d'.' -f 1` + dnf install python-pip gcc-c++ git-all tmux icu libicu libicu-devel openssl-devel openldap-devel python3-devel - yum install python-pip python-virtualenv python-tox gcc-c++ git-all screen icu libicu libicu-devel openssl-devel openldap-devel python3-devel + OSRELEASE_VERSION=$(source /etc/os-release; echo ${VERSION_ID%.*}) + dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-${OSRELEASE_VERSION}.noarch.rpm - yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-${OSRELEASE_VERSION}.noarch.rpm +.. note:: - # Add key and repo for the latest stable MongoDB (4.0) - rpm --import https://www.mongodb.org/static/pgp/server-4.0.asc - sh -c "cat < /etc/yum.repos.d/mongodb-org-4.repo - [mongodb-org-4] - name=MongoDB Repository - baseurl=https://repo.mongodb.org/yum/redhat/${OSRELEASE_VERSION}/mongodb-org/4.0/x86_64/ - gpgcheck=1 - enabled=1 - gpgkey=https://www.mongodb.org/static/pgp/server-4.0.asc - EOT" + virtualenv is not available on Rocky9 and by extension the python-tox package can't be installed. Use venv module instead. + screen has been removed from Rocky9 so developer tooling uses tmux instead. + + +Install a supported version of MongoDB, RabbitMQ / Erlang and Redis. + +`Red Hat Enterprise Linux 8 and compatible distributions ` +`Red Hat Enterprise Linux 9 and compatible distributions ` - yum install crudini - yum install mongodb-org - yum install rabbitmq-server - systemctl start mongod rabbitmq-server - systemctl enable mongod rabbitmq-server Project Requirements -~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Once the environment is setup, clone the git repo, and make the project. This will create the Python virtual environment under StackStorm, download and install required dependencies, and run @@ -78,7 +78,7 @@ tests: make requirements Configure System User -~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Create a system user for executing SSH actions: @@ -89,7 +89,7 @@ Create a system user for executing SSH actions: ssh-keygen -f /home/stanley/.ssh/stanley_rsa -t rsa -b 4096 -C "stanley@stackstorm.com" -N '' exit -Specify a user for running local and remote SSH actions. See :ref:`config-configure-ssh`. In +Specify a user for running local and remote SSH actions. See :ref:`config-configure-ssh`. In ``st2/conf/st2.dev.conf``, change ``ssh_key_file`` to point to the user's key file: .. code-block:: ini @@ -99,7 +99,7 @@ Specify a user for running local and remote SSH actions. See :ref:`config-config ssh_key_file = /home/[current user]/.ssh/stanley_rsa Running -~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Activate the virtualenv before starting the services: @@ -113,46 +113,54 @@ Run the following to start |st2|: ./tools/launchdev.sh start -It will start |st2| components in ``screen`` sessions. +It will start |st2| components in ``tmux`` sessions. Additional commands: .. code-block:: bash - source virtualenv/bin/activate # Activates the Python virtual environment + source virtualenv/bin/activate # Activates the Python virtual environment tools/launchdev.sh startclean # Reset and launches all StackStorm services in screen sessions tools/launchdev.sh start # Launches all StackStorm services in screen sessions tools/launchdev.sh stop # Stops all StackStorm screen sessions and services -If the services are started successfully, you will see the following -output: +If the services are started successfully, you will see the following output: .. code-block:: bash - Starting all st2 servers... - Changing working directory to /home/vagrant/st2/./tools/..... - Using st2 config file: /home/vagrant/st2/./tools/../conf/st2.dev.conf - Using content packs base dir: /opt/stackstorm/packs - No Sockets found in /var/run/screen/S-vagrant. - - Starting screen session st2-api... - Starting screen session st2-actionrunner... - starting runner 1 ... - No screen session found. - Starting screen session st2-sensorcontainer - Starting screen session st2-rulesengine... - Starting screen session st2-resultstracker... - Starting screen session st2-notifier... - - Registering sensors, actions, rules and aliases... - ... + ./tools/launchdev.sh start + Initialising system variables ... + Current user:group = root:root + Using virtualenv: /root/workspace/st2/virtualenv + Using python: /root/workspace/st2/virtualenv/bin/python (Python 3.10.12) + Log file location: /root/workspace/st2/./tools/../logs + Using st2 config file: /root/workspace/st2/conf/st2.dev.conf + Starting all st2 servers ... + Changing working directory to /root/workspace/st2/./tools/.. + Using config base dir: /opt/stackstorm/configs + Using content packs base dir: /opt/stackstorm/packs + Starting st2-api using gunicorn ... + Starting st2-stream using gunicorn ... + Starting st2-workflow engine(s): + st2-workflow-1 ... + Starting st2-actionrunner(s): + st2-actionrunner-1 ... + Starting st2-garbagecollector ... + Starting st2-scheduler(s): + st2-scheduler-1 ... + Starting st2-sensorcontainer ... + Starting st2-rulesengine ... + Starting st2-timersengine ... + Starting st2-notifier ... + Starting st2-auth using gunicorn ... + ... |st2| can now be operated using the REST API, |st2| CLI, and the st2client Python client library. .. _setup-st2-cli: Install |st2| CLI -~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The |st2| CLI client needs to be installed. It is not necessary to install this into the virtualenv. However, the client may need to be installed with sudo if not in the virtualenv: @@ -163,7 +171,7 @@ virtualenv. However, the client may need to be installed with sudo if not in the python3 setup.py develop Verify Installation -~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To make sure all the components are installed correctly: @@ -175,7 +183,7 @@ To make sure all the components are installed correctly: st2 run core.local uname Additional Makefile targets -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ``make all`` creates virtualenv, installs dependencies, and runs tests - ``make tests`` runs all the tests @@ -188,7 +196,7 @@ Additional Makefile targets Install |st2| Web UI -~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Installing the st2 Web UI. @@ -210,7 +218,7 @@ Installing the st2 Web UI. Default Credentials to Login -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -218,7 +226,7 @@ Default Credentials to Login password: testp Manual Testing -~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you only need to test a specific module, it might be reasonable to call ``nosetests`` directly. Make sure your virtualenv is active then run: diff --git a/docs/source/info.py b/docs/source/info.py index 28f47aac5..f487100b1 100644 --- a/docs/source/info.py +++ b/docs/source/info.py @@ -9,11 +9,11 @@ master_doc = 'index' -project = u'StackStorm' -copyright = u'2014 - %s, StackStorm' % (datetime.now().strftime("%Y")) -author = u'Extreme Networks, Inc' +project = "StackStorm" +copyright = "2014 - %s, StackStorm" % (datetime.now().strftime("%Y")) +author = "The StackStorm Authors" -base_url = u'https://docs.stackstorm.com/' +base_url = "https://docs.stackstorm.com/" htmlhelp_basename = 'StackStormDoc' man_pages = [ @@ -30,8 +30,6 @@ 'Miscellaneous'), ] -github_user = 'StackStorm' -github_repo = 'st2docs' -github_version = 'master' - -theme_base_url = u'https://docs.stackstorm.com/' +github_user = "StackStorm" +github_repo = "st2docs" +github_version = "master" diff --git a/docs/source/install/common/configure_chatops.rst b/docs/source/install/common/configure_chatops.rst index 4cafa73a0..3b47f30c1 100644 --- a/docs/source/install/common/configure_chatops.rst +++ b/docs/source/install/common/configure_chatops.rst @@ -5,14 +5,5 @@ update the ``ST2_API`` and ``ST2_AUTH_URL`` variables or just point to the correct host with ``ST2_HOSTNAME``. - The example configuration uses Slack. To set this up, go to the Slack web admin interface, create - a Bot, and copy the authentication token into ``HUBOT_SLACK_TOKEN``. - - If you are using a different Chat Service, set the corresponding environment variables under the - ``Chat service adapter settings`` section in ``st2chatops.env``: - `Slack `_, - `Flowdock `_, - `IRC `_ , - `Mattermost `_, - `RocketChat `_, - `XMPP `_. + The example configuration uses Slack. To see the full list of supported Chat Services and environmental + variables to configure see :ref:`chatops-configuration`. \ No newline at end of file diff --git a/docs/source/install/index.rst b/docs/source/install/index.rst index 042535047..aeebf0863 100644 --- a/docs/source/install/index.rst +++ b/docs/source/install/index.rst @@ -7,6 +7,14 @@ Ready to install |st2|? Here's an overview of how to get your system up and runn images. You can either use a script to automatically install and configure all components on a single system, or you can follow the manual instructions for your OS. +.. warning:: + + StackStorm is developed and tested against the x86_64 architecture on the GNU/Linux platform using **Ubuntu** and **Rocky/CentOS**. + + We would like to be able to support alternative architectures (arm, risc-v, mips etc.), platforms (Microsoft Windows, Apple OSX, FreeBSD) + and distributions (SUSE, Arch, Gentoo, etc), however we have a finite set of resources which prevents us from doing so. If you build and operate + StackStorm using these alternatives, you accept the responsibility of addressing any issues encountered yourself and understand no official support is available. + Here's an overview of the options: * **One-line Install:** Run our installation script for an opinionated install of all components @@ -14,11 +22,11 @@ Here's an overview of the options: ` section below for details. * **Manual Installation:** Have custom needs? Maybe no Internet access from your servers? Or just don't like using scripted installs? Read the manual installation instructions for your OS - (:doc:`Ubuntu 18 `, :doc:`Ubuntu 20 `, - :doc:`RHEL/CentOS 7 `, :doc:`RHEL/RockyLinux/CentOS 8 `) and adapt them to + (:doc:`Ubuntu 20 Focal `, :doc:`Ubuntu 22 Jammy `, + :doc:`Red Hat Enterprise Linux 8 and compatible distributions `, :doc:`Red Hat Enterprise Linux 9 and compatible distributions `) and adapt them to your needs. Here's some `additional guidance `_ for setting up an - internal mirror for the |st2| repos. + internal mirror for the |st2| repos. * **Vagrant / Virtual Appliance:** Vagrant / OVA is a quick and easy way to try StackStorm. It's already pre-installed, tested and shipped as a virtual image and so saves your time going through time-consuming installation and configuration steps. Works best as a testing, @@ -38,11 +46,6 @@ Here's an overview of the options: Choose the option that best suits your needs. -Upgrading to |ewc|? This is installed as a set of additional packages on top of StackStorm. You -can either install StackStorm + |ewc| in one go, or add the |ewc| packages to an existing -StackStorm system. If you are using |ewc|, you can also add Network Automation Suites. -Read the :doc:`/install/ewc` documentation for more. - .. _ref-one-line-install: .. rubric:: Quick Install @@ -57,7 +60,7 @@ on Ubuntu, or ``sudo yum install curl nss`` on RHEL/RockyLinux/CentOS. Then run This is an opinionated installation of |st2|. It will download and install all components, as per the :doc:`single host reference deployment <./overview>`. It assumes that you have a clean, basic -installation of Ubuntu or RHEL/RockyLinux/CentOS. +installation of Ubuntu or RHEL/RockyLinux/CentOS. If you are trying to install |st2| on a server with other applications, or local customisations, you may run into problems. In that case, you should use one of the manual installation methods. @@ -76,9 +79,7 @@ If you're installing behind a proxy, just export the proxy ENV variables In case of MITM proxy, you may need to export additional ``proxy_ca_bundle_path``, see :ref:`packs-behind-proxy`. - -If you have problems accessing the Web UI on a RHEL 7/CentOS 7 system, check the -:ref:`system firewall settings `. +If you have problems accessing the Web UI, check the system firewall settings. .. include:: __installer_passwords.rst @@ -91,10 +92,10 @@ For more details on reference deployments, or OS-specific installation instructi Reference Deployment Overview system_requirements - Ubuntu 18.04 Ubuntu 20.04 - RHEL 7 / CentOS 7 - RHEL 8 / RockyLinux 8 / CentOS 8 + Ubuntu 22.04 + RHEL 8 and binary compatible clones + RHEL 9 and binary compatible clones Vagrant / OVA Docker Ansible Playbooks diff --git a/docs/source/install/rhel8.rst b/docs/source/install/rhel8.rst index 0e1cd85b6..da5314ffd 100644 --- a/docs/source/install/rhel8.rst +++ b/docs/source/install/rhel8.rst @@ -1,5 +1,5 @@ -RHEL 8/CentOS 8 -=============== +RHEL 8/RockyLinux 8 +======================================================================== .. include:: common/intro.rst @@ -7,24 +7,18 @@ RHEL 8/CentOS 8 :local: System Requirements -------------------- +------------------------------------------------------------------------ Please check the :doc:`supported versions and system requirements `. -.. note:: - - |st2| on RHEL 8/RockyLinux/CentOS 8 runs all services, actions and sensors using Python 3 **only**. It - does not support Python 2 actions. `More info about python in RHEL 8 and CentOS 8. - `_ - .. note:: |st2| is verified on RHEL/RockyLinux ``8.x`` distributions, but our RPMs should be compatible with other RHEL``8.x`` derivatives, e.g. CentOS 8 Stream. Minimal Installation --------------------- +------------------------------------------------------------------------ Adjust SELinux Policies -~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If your system has SELinux in Enforcing mode, please follow these instructions to adjust SELinux policies. This is needed for successful installation. If you are not happy with these policies, @@ -55,7 +49,7 @@ you may want to tweak them according to your security practices. adjust policy configurations when SELinux is disabled. You can ignore this error. Install Dependencies -~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. include:: __mongodb_note.rst @@ -65,37 +59,28 @@ Install MongoDB, RabbitMQ, and Redis: sudo yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm - # Add key and repo for the latest stable MongoDB (4.0) - sudo rpm --import https://www.mongodb.org/static/pgp/server-4.0.asc - sudo sh -c "cat < /etc/yum.repos.d/mongodb-org-4.repo - [mongodb-org-4] + # Add key and repo for the latest stable MongoDB (7.0) + tee <`_ is used to serve WebUI static files, redirect HTTP to HTTPS, provide SSL termination, and reverse-proxy st2auth and st2api API endpoints. To set it up: install the @@ -221,7 +206,7 @@ survive reboot. .. include:: common/api_access.rst Setup ChatOps -------------- +------------------------------------------------------------------------ If you already run a Hubot instance, you can install the `hubot-stackstorm plugin `_ and configure |st2| environment variables, as @@ -237,11 +222,13 @@ is to use the `st2chatops `_ package. # Create notification rule if not yet enabled st2 rule get chatops.notify || st2 rule create /opt/stackstorm/packs/chatops/rules/notify_hubot.yaml -* Add `NodeJS v14 repository `_: +* Add `NodeJS v20 repository `_: .. code-block:: bash - curl -sL https://rpm.nodesource.com/setup_14.x | sudo -E bash - + curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash + source ~/.bashrc + nvm install 20 * Install the ``st2chatops`` package: @@ -269,15 +256,10 @@ is to use the `st2chatops `_ package. * That's it! Go to your Chat room and begin ChatOps-ing. Read more in the :doc:`/chatops/index` section. A Note on Security ------------------- +------------------------------------------------------------------------ .. include:: common/security_notes.rst -Upgrade to |ewc| ----------------- - -.. include:: common/ewc_intro.rst - .. rubric:: What's Next? * Check out the :doc:`/start` Guide to build a simple automation. diff --git a/docs/source/install/rhel7.rst b/docs/source/install/rhel9.rst similarity index 75% rename from docs/source/install/rhel7.rst rename to docs/source/install/rhel9.rst index 94de13cc1..8fb562861 100644 --- a/docs/source/install/rhel7.rst +++ b/docs/source/install/rhel9.rst @@ -1,5 +1,5 @@ -RHEL 7/CentOS 7 -=============== +RHEL 9/Rocky 9 +======================================================================== .. include:: common/intro.rst @@ -7,17 +7,15 @@ RHEL 7/CentOS 7 :local: System Requirements -------------------- +------------------------------------------------------------------------ Please check the :doc:`supported versions and system requirements `. .. note:: - - |st2| on RHEL 7/CentOS 7 runs all services, actions and sensors using Python 3 **only**. It - does not support Python 2 actions. + |st2| is verified on RHEL/RockyLinux ``9.x`` distributions, but our RPMs should be compatible with other RHEL``9.x`` derivatives, e.g. CentOS 9 Stream. Minimal Installation --------------------- +------------------------------------------------------------------------ Adjust SELinux Policies ~~~~~~~~~~~~~~~~~~~~~~~ @@ -37,7 +35,7 @@ you may want to tweak them according to your security practices. .. code-block:: bash # SELINUX management tools, not available for some minimal installations - sudo yum install -y policycoreutils-python + sudo yum install -y policycoreutils-python-utils # Allow network access for nginx sudo setsebool -P httpd_can_network_connect 1 @@ -55,56 +53,31 @@ Install Dependencies .. include:: __mongodb_note.rst -Install MongoDB, RabbitMQ, and Redis +Install MongoDB, RabbitMQ, and Redis: .. code-block:: bash - sudo yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm + sudo dnf -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm - # Add key and repo for the latest stable MongoDB (4.0) - sudo rpm --import https://www.mongodb.org/static/pgp/server-4.0.asc - sudo sh -c "cat < /etc/yum.repos.d/mongodb-org-4.repo - [mongodb-org-4] + # Add key and repo for the latest stable MongoDB (7.0) + tee < Setup Repositories ~~~~~~~~~~~~~~~~~~ @@ -146,7 +119,7 @@ Verify .. include:: common/verify.rst Configure Authentication ------------------------- +------------------------------------------------------------------------ The reference deployment uses a file-based authentication provider for simplicity. Refer to :doc:`/authentication` to configure and use PAM or LDAP authentication backends. @@ -165,7 +138,7 @@ To set up authentication with file-based provider: .. include:: common/configure_authentication.rst Install WebUI and Setup SSL Termination ---------------------------------------- +------------------------------------------------------------------------ `NGINX `_ is used to serve WebUI static files, redirect HTTP to HTTPS, provide SSL termination, and reverse-proxy st2auth and st2api API endpoints. To set it up: install the @@ -217,8 +190,6 @@ the st2web configuration at ``/opt/stackstorm/static/webui/config.js``. Use your browser to connect to ``https://${ST2_HOSTNAME}`` and login to the WebUI. -.. _ref-rhel7-firewall: - If you are unable to connect to the web browser, you may need to change the default firewall settings. You can do this with these commands: @@ -233,7 +204,7 @@ survive reboot. .. include:: common/api_access.rst Setup ChatOps -------------- +------------------------------------------------------------------------ If you already run a Hubot instance, you can install the `hubot-stackstorm plugin `_ and configure |st2| environment variables, as @@ -249,11 +220,13 @@ is to use the `st2chatops `_ package. # Create notification rule if not yet enabled st2 rule get chatops.notify || st2 rule create /opt/stackstorm/packs/chatops/rules/notify_hubot.yaml -* Add `NodeJS v14 repository `_: +* Add `NodeJS v20 repository `_: .. code-block:: bash - curl -sL https://rpm.nodesource.com/setup_14.x | sudo -E bash - + curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash + source ~/.bashrc + nvm install 20 * Install the ``st2chatops`` package: @@ -281,15 +254,10 @@ is to use the `st2chatops `_ package. * That's it! Go to your Chat room and begin ChatOps-ing. Read more in the :doc:`/chatops/index` section. A Note on Security ------------------- +------------------------------------------------------------------------ .. include:: common/security_notes.rst -Upgrade to |ewc| ----------------- - -.. include:: common/ewc_intro.rst - .. rubric:: What's Next? * Check out the :doc:`/start` Guide to build a simple automation. diff --git a/docs/source/install/system_requirements.rst b/docs/source/install/system_requirements.rst index e54dd2c1c..33ef9f73f 100644 --- a/docs/source/install/system_requirements.rst +++ b/docs/source/install/system_requirements.rst @@ -1,7 +1,7 @@ System Requirements =================== -|st2| requires Ubuntu, RHEL, RockyLinux or CentOS Linux. It is not supported on any other Linux distributions. +|st2| requires Ubuntu, RHEL or RockyLinux Linux. It is not supported on any other Linux distributions. The table below lists the supported Linux versions, along with the Vagrant Boxes and Amazon AWS instances we use for testing. See :ref:`below ` for more details about our Linux distribution support policy. @@ -15,19 +15,19 @@ be automatically added when you install |st2|. Please note that only 64-bit architecture is supported. -+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Linux (64-bit) | Vagrant Box | Amazon AWS AMI | -+=======================================================================================================+================================================================================+===================================================================================================================================================================+ -| `Ubuntu 18.04 `_ | `bento/ubuntu-18.04 `_ | `Ubuntu Server 18.04 LTS Bionic `_ | -+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `Ubuntu 20.04 `_ | `bento/ubuntu-20.04 `_ | `Ubuntu Server 20.04 LTS Focal `_ | -+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `RHEL 8 `_ / | `bento/rockylinux-8.5 `_ | `Red Hat Enterprise Linux (RHEL) 8 (HVM) `_ | -| `RockyLinux 8 `_ | | | -+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `RHEL 7 `_ / | `bento/centos-7.4 `_ | `Red Hat Enterprise Linux (RHEL) 7.2 (HVM) `_ | -| `CentOS 7 `_ | | | -+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++-----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+ +| Linux (64-bit) | Vagrant Box | Amazon AWS AMI | ++===========================================================================================================+===========================================================================================+===============================================================================================================+ +| `Ubuntu 20.04 `_ | `ubuntu/focal64 `_ | `Ubuntu Server 20.04 LTS Focal `_ | ++-----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+ +| `Ubuntu 22.04 `_ | `ubuntu/jammy64 `_ | `Ubuntu 22.04 LTS - Jammy `_ | ++-----------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| `RHEL 8 `_ / | `rockylinux/8 `_ | `Red Hat Enterprise Linux (RHEL) 8 (HVM) `_ | +| `RockyLinux 8 `_ | | | ++-----------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ +| `RHEL 9 `_ / | `rockylinux/9 `_ | `Red Hat Enterprise Linux 9 (HVM) `_ | +| `RockyLinux 9 `_ | | | ++-----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------+ This is the recommended minimum sizing for testing and deploying |st2|: @@ -70,13 +70,8 @@ Linux Distribution Support Policy StackStorm only support Ubuntu and RHEL/RockyLinux/CentOS Linux distributions. In general, it is supported on the two most recent major supported releases for those distributions. Specifically: -* **Ubuntu**: Current LTS releases are supported. Today this is ``18.04`` and ``20.04``. +* **Ubuntu**: Current LTS releases are supported. Today this is ``20.04`` and ``22.04``. -* **RHEL/CentOS**: We currently support RHEL/CentOS ``7.x`` and RHEL/RockyLinux ``8.x``. In general, we recommend using +* **RHEL/Rocky**: We currently support RHEL/RockyLinux ``8.x`` and RHEL/RockyLinux ``9.x``. In general, we recommend using the most recent version in that series, but any version may be used. - |st2| is verified on RHEL/RockyLinux ``8.x`` distributions, but our RPMs should be compatible with other RHEL``8.x`` derivatives, e.g. CentOS 8 Stream. - - Support for RHEL/CentOS ``6.x`` has been removed. |st2| 3.2 is the last release that supported RHEL/CentOS ``6.x``. - - Support for Ubuntu ``16.04`` has been removed. |st2| 3.4 is the last release that supported RHEL/CentOS ``16.04``. - + |st2| is verified on RHEL/RockyLinux distributions, but our RPMs should be compatible with other binary compatible derivatives, e.g. CentOS 8 Stream. diff --git a/docs/source/install/u20.rst b/docs/source/install/u20.rst index e87cb0a13..85b86581f 100644 --- a/docs/source/install/u20.rst +++ b/docs/source/install/u20.rst @@ -27,46 +27,29 @@ Install MongoDB, RabbitMQ, and Redis: sudo apt-get update sudo apt-get install -y curl + export OS_CODENAME=$(source /etc/os-release && echo $VERSION_CODENAME) - # Add key and repo for MongoDB (4.4) - wget -qO - https://www.mongodb.org/static/pgp/server-4.4.asc | sudo apt-key add - - sudo sh -c "cat < /etc/apt/sources.list.d/mongodb-org-4.4.list - deb http://repo.mongodb.org/apt/ubuntu $(lsb_release -c | awk '{print $2}')/mongodb-org/4.4 multiverse - EOT" - sudo apt-get update + # Add MongoDB (7.0) repository signing key and apt repository + curl -1sLf https://pgp.mongodb.com/server-7.0.asc | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/mongodb-org-7.0.gpg + echo "deb http://repo.mongodb.org/apt/ubuntu ${OS_CODENAME}/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list - # Add keys latest RabbitMQ and RabbitMQ-erlang - # Team RabbitMQ's main signing key - curl -1sLf "https://keys.openpgp.org/vks/v1/by-fingerprint/0A9AF2115F4687BD29803A206B73A36E6026DFCA" | sudo gpg --dearmor | sudo tee /usr/share/keyrings/com.rabbitmq.team.gpg > /dev/null - # CloudSmith PPA that provides modern Erlang releases - curl -1sLf "https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key" | sudo gpg --dearmor | sudo tee /usr/share/keyrings/io.cloudsmith.dl.rabbitmq.erlang.gpg > /dev/null - # CloudSmith RabbitMQ repository - curl -1sLf "https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key" | sudo gpg --dearmor | sudo tee /usr/share/keyrings/io.cloudsmith.dl.rabbitmq.gpg > /dev/null + # Add RabbitMQ (3.11), RabbitMQ-erlang (25.3) and RabbitMQ's main signing key and associated repositories + curl -1sLf "https://keys.openpgp.org/vks/v1/by-fingerprint/0A9AF2115F4687BD29803A206B73A36E6026DFCA" | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/com.rabbitmq.team.gpg + curl -1sLf "https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key" | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/io.cloudsmith.dl.rabbitmq.erlang.gpg + curl -1sLf "https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key" | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/io.cloudsmith.dl.rabbitmq.gpg - # Add apt repositories maintained by Team RabbitMQ sudo tee /etc/apt/sources.list.d/rabbitmq.list <`_ package. # Create notification rule if not yet enabled st2 rule get chatops.notify || st2 rule create /opt/stackstorm/packs/chatops/rules/notify_hubot.yaml -* Add `NodeJS v14 repository `_: +* Add `NodeJS v20 repository `_: .. code-block:: bash - curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash - + curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash + source ~/.bashrc + nvm install 20 * Install the ``st2chatops`` package: @@ -234,11 +213,6 @@ A Note on Security .. include:: common/security_notes.rst -Upgrade to |ewc| ----------------- - -.. include:: common/ewc_intro.rst - .. rubric:: What's Next? * Check out the :doc:`/start` Guide to build a simple automation. diff --git a/docs/source/install/u18.rst b/docs/source/install/u22.rst similarity index 62% rename from docs/source/install/u18.rst rename to docs/source/install/u22.rst index e379710a1..608e1c29a 100644 --- a/docs/source/install/u18.rst +++ b/docs/source/install/u22.rst @@ -1,4 +1,4 @@ -Ubuntu Bionic (18.04) +Ubuntu Jammy (22.04) ===================== .. include:: common/intro.rst @@ -8,8 +8,7 @@ Ubuntu Bionic (18.04) .. note:: - |st2| on Ubuntu ``18.04`` runs all services, actions and sensors using Python 3 **only**. It - does not support Python2 actions. + |st2| on Ubuntu ``22.04`` runs all services, actions and sensors using Python 3. System Requirements ------------------- @@ -24,73 +23,43 @@ Install Dependencies Install MongoDB, RabbitMQ, and Redis: +.. note:: + + apt ``2.4.9`` discourages use of ``apt-key`` and the previous gpg file format. The below instructions place the gpg key in the location and format expected by apt. + .. code-block:: bash sudo apt-get update sudo apt-get install -y curl + export OS_CODENAME=$(source /etc/os-release && echo $VERSION_CODENAME) - # Add key and repo for MongoDB (4.0) - wget -qO - https://www.mongodb.org/static/pgp/server-4.0.asc | sudo apt-key add - - sudo sh -c "cat < /etc/apt/sources.list.d/mongodb-org-4.0.list - deb http://repo.mongodb.org/apt/ubuntu $(lsb_release -c | awk '{print $2}')/mongodb-org/4.0 multiverse - EOT" - sudo apt-get update + # Add MongoDB (7.0) repository signing key and apt repository + curl -1sLf https://pgp.mongodb.com/server-7.0.asc | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/mongodb-org-7.0.gpg + echo "deb http://repo.mongodb.org/apt/ubuntu ${OS_CODENAME}/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list - # Add keys latest RabbitMQ and RabbitMQ-erlang - # Team RabbitMQ's main signing key - curl -1sLf "https://keys.openpgp.org/vks/v1/by-fingerprint/0A9AF2115F4687BD29803A206B73A36E6026DFCA" | sudo gpg --dearmor | sudo tee /usr/share/keyrings/com.rabbitmq.team.gpg > /dev/null - # CloudSmith PPA that provides modern Erlang releases - curl -1sLf "https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key" | sudo gpg --dearmor | sudo tee /usr/share/keyrings/io.cloudsmith.dl.rabbitmq.erlang.gpg > /dev/null - # CloudSmith RabbitMQ repository - curl -1sLf "https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key" | sudo gpg --dearmor | sudo tee /usr/share/keyrings/io.cloudsmith.dl.rabbitmq.gpg > /dev/null + # Add RabbitMQ (3.11), RabbitMQ-erlang (25.3) and RabbitMQ's main signing key and associated repositories + curl -1sLf "https://keys.openpgp.org/vks/v1/by-fingerprint/0A9AF2115F4687BD29803A206B73A36E6026DFCA" | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/com.rabbitmq.team.gpg + curl -1sLf "https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/gpg.E495BB49CC4BBE5B.key" | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/io.cloudsmith.dl.rabbitmq.erlang.gpg + curl -1sLf "https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/gpg.9F4587F226208342.key" | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/io.cloudsmith.dl.rabbitmq.gpg - # Add apt repositories maintained by Team RabbitMQ sudo tee /etc/apt/sources.list.d/rabbitmq.list <`_ is used to serve WebUI static files, redirect HTTP to HTTPS, provide -SSL termination, and reverse-proxy st2auth and st2api API endpoints. To set it up: install the +SSL termination, and reverse-proxy st2auth, st2api and st2stream API endpoints. To set it up: install the ``st2web`` and ``nginx`` packages, generate certificates or place your existing certificates under ``/etc/ssl/st2``, and configure nginx with |st2|'s supplied :github_st2:`site config file st2.conf `. @@ -178,7 +145,7 @@ SSL termination, and reverse-proxy st2auth and st2api API endpoints. To set it u # Remove default site, if present sudo rm /etc/nginx/conf.d/default.conf - # Check for a default site on sites-enabled to avoid a duplicate default server error + # Check for a default site on sites-enabled to avoid a duplicate default server error sudo rm -f /etc/nginx/sites-enabled/default # Copy and enable the supplied nginx config file sudo cp /usr/share/doc/st2/conf/nginx/st2.conf /etc/nginx/conf.d/ @@ -211,11 +178,13 @@ is to use the `st2chatops `_ package. # Create notification rule if not yet enabled st2 rule get chatops.notify || st2 rule create /opt/stackstorm/packs/chatops/rules/notify_hubot.yaml -* Add `NodeJS v14 repository `_: +* Add `NodeJS v20 repository `_: .. code-block:: bash - curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash - + curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash + source ~/.bashrc + nvm install 20 * Install the ``st2chatops`` package: @@ -244,10 +213,6 @@ A Note on Security .. include:: common/security_notes.rst -Upgrade to |ewc| ----------------- - -.. include:: common/ewc_intro.rst .. rubric:: What's Next? diff --git a/docs/source/install/uninstall.rst b/docs/source/install/uninstall.rst index 6e73620ea..8a27cffbe 100644 --- a/docs/source/install/uninstall.rst +++ b/docs/source/install/uninstall.rst @@ -40,7 +40,7 @@ below. Only execute the instructions for your distribution. 1. Stop Services ---------------- -* Ubuntu 18.04/20.04: +* Ubuntu: .. sourcecode:: bash @@ -69,7 +69,7 @@ below. Only execute the instructions for your distribution. 2. Remove Packages ------------------ -* Ubuntu 18.04/20.04: +* Ubuntu: If you are using StackStorm only: diff --git a/docs/source/orquesta/start.rst b/docs/source/orquesta/start.rst index 2e5697dec..6116d6b64 100644 --- a/docs/source/orquesta/start.rst +++ b/docs/source/orquesta/start.rst @@ -199,6 +199,6 @@ Additional Tools and Resources * `YAQL documentation `_ and `YAQL online evaluator `_ -* `Jinja2 template engine documentation `_ and `Jinja2 online evaluator +* `Jinja2 template engine documentation `_ and `Jinja2 online evaluator `_ * `Workflow visualization tool `_ diff --git a/docs/source/reference/jinja.rst b/docs/source/reference/jinja.rst index c049e62cb..7d29f8f97 100644 --- a/docs/source/reference/jinja.rst +++ b/docs/source/reference/jinja.rst @@ -1,7 +1,7 @@ Jinja ===== -|st2| uses `Jinja `_ extensively for templating. Jinja allows you to +|st2| uses `Jinja `_ extensively for templating. Jinja allows you to manipulate parameter values in |st2| by allowing you to refer to other parameters, applying filters or refer to system specific constructs (like datastore access). This document is here to help you with Jinja in the context of |st2|. Please refer to the `Jinja docs diff --git a/docs/source/reference/monitoring.rst b/docs/source/reference/monitoring.rst index 1311065b4..9c1af561c 100644 --- a/docs/source/reference/monitoring.rst +++ b/docs/source/reference/monitoring.rst @@ -29,7 +29,7 @@ checking the response: {"status": "requested", "start_timestamp": "2016-10-10T01:37:45.937153Z", "log": [{"status": "requested", "timestamp": "2016-10-10T01:37:45.950751Z"}], "parameters": {"cmd": "date -R"}, "runner": {"runner_module": "st2actions.runners.localrunner", "uid": "runner_type:local-shell-cmd", "description": "A runner to execute local actions as a fixed user.", "enabled": true, "runner_parameters": {"sudo": {"default": false, "type": "boolean", "description": "The command will be executed with sudo."}, "env": {"type": "object", "description": "Environment variables which will be available to the command(e.g. key1=val1,key2=val2)"}, "cmd": {"type": "string", "description": "Arbitrary Linux command to be executed on the host."}, "kwarg_op": {"default": "--", "type": "string", "description": "Operator to use in front of keyword args i.e. \"--\" or \"-\"."}, "timeout": {"default": 60, "type": "integer", "description": "Action timeout in seconds. Action will get killed if it doesn't finish in timeout seconds."}, "cwd": {"type": "string", "description": "Working directory where the command will be executed in"}}, "id": "57fa74ad1d41c8249e5664f4", "name": "local-shell-cmd"}, "web_url": "https://ubuntu/#/history/57faf0e91d41c805055a1110/general", "context": {"user": "st2admin"}, "action": {"description": "Action that executes an arbitrary Linux command on the localhost.", "runner_type": "local-shell-cmd", "tags": [], "enabled": true, "pack": "core", "entry_point": "", "notify": {}, "uid": "action:core:local", "parameters": {"cmd": {"required": true, "type": "string", "description": "Arbitrary Linux command to be executed on the remote host(s)."}, "sudo": {"immutable": true}}, "ref": "core.local", "id": "57fa74ae1d41c8249e566509", "name": "local"}, "liveaction": {"runner_info": {}, "parameters": {"cmd": "date -R"}, "action_is_workflow": false, "callback": {}, "action": "core.local", "id": "57faf0e91d41c805055a110f"}, "id": "57faf0e91d41c805055a1110"} ## Check the execution status using the id from above: - $ curl -X GET -H St2-Api-Key: my_api_key' -k https://192.0.2.1/api/v1/executions/57faf0e91d41c805055a1110 + $ curl -X GET -H 'St2-Api-Key: my_api_key' -k https://192.0.2.1/api/v1/executions/57faf0e91d41c805055a1110 {"status": "succeeded", "start_timestamp": "2016-10-10T01:37:45.937153Z", "log": [{"status": "requested", "timestamp": "2016-10-10T01:37:45.950000Z"}, {"status": "scheduled", "timestamp": "2016-10-10T01:37:46.039000Z"}, {"status": "running", "timestamp": "2016-10-10T01:37:46.157000Z"}, {"status": "succeeded", "timestamp": "2016-10-10T01:37:46.305000Z"}], "parameters": {"cmd": "date -R"}, "runner": {"runner_module": "st2actions.runners.localrunner", "uid": "runner_type:local-shell-cmd", "enabled": true, "name": "local-shell-cmd", "runner_parameters": {"sudo": {"default": false, "type": "boolean", "description": "The command will be executed with sudo."}, "env": {"type": "object", "description": "Environment variables which will be available to the command(e.g. key1=val1,key2=val2)"}, "cmd": {"type": "string", "description": "Arbitrary Linux command to be executed on the host."}, "kwarg_op": {"default": "--", "type": "string", "description": "Operator to use in front of keyword args i.e. \"--\" or \"-\"."}, "timeout": {"default": 60, "type": "integer", "description": "Action timeout in seconds. Action will get killed if it doesn't finish in timeout seconds."}, "cwd": {"type": "string", "description": "Working directory where the command will be executed in"}}, "id": "57fa74ad1d41c8249e5664f4", "description": "A runner to execute local actions as a fixed user."}, "elapsed_seconds": 0.339103, "web_url": "https://ubuntu/#/history/57faf0e91d41c805055a1110/general", "result": {"failed": false, "stderr": "", "return_code": 0, "succeeded": true, "stdout": "Sun, 09 Oct 2016 18:37:46 -0700"}, "context": {"user": "st2admin"}, "action": {"runner_type": "local-shell-cmd", "name": "local", "parameters": {"cmd": {"required": true, "type": "string", "description": "Arbitrary Linux command to be executed on the remote host(s)."}, "sudo": {"immutable": true}}, "tags": [], "enabled": true, "entry_point": "", "notify": {}, "uid": "action:core:local", "pack": "core", "ref": "core.local", "id": "57fa74ae1d41c8249e566509", "description": "Action that executes an arbitrary Linux command on the localhost."}, "liveaction": {"runner_info": {"hostname": "ubuntu", "pid": 1014}, "parameters": {"cmd": "date -R"}, "action_is_workflow": false, "callback": {}, "action": "core.local", "id": "57faf0e91d41c805055a110f"}, "id": "57faf0e91d41c805055a1110", "end_timestamp": "2016-10-10T01:37:46.276256Z"} Look for ``failed: false`` in the result above. This process will exercise the core parts of |st2|. diff --git a/docs/source/roadmap.rst b/docs/source/roadmap.rst index 1d5efc0c8..1036420f5 100644 --- a/docs/source/roadmap.rst +++ b/docs/source/roadmap.rst @@ -16,10 +16,12 @@ contributions. Here's our plans for the next releases. the feature. Pull Requests are open to anyone. -3.8 +3.10 --- -* **Output Schema:** Allow action/runner output schemas to cover all output types, not just JSON objects. +* **SSO:** Support SSO with SAML2 for |ewc| web UI (beta). +* **Python ChatOps:** Convert ChatOps backend to Python + * More will be added to the roadmap for ``3.8``. So, stay tuned! Monitor the `master branch `_ to see how we're progressing. @@ -29,12 +31,10 @@ Backlog Here's some more nice things on our list that we haven't scheduled yet: -* **Python ChatOps:** Convert ChatOps backend to Python * **ChatOps:** Support RBAC. * **K8s/HA:** Graduate `K8s Helm chart `_ from beta to stable. * **Workflow runtime graph:** Runtime view of workflow execution in st2flow for |ewc|. * **Workflow dry run:** Ability to run unit tests on orquesta workflows for |ewc|. -* **SSO:** Support SSO with SAML2 for |ewc| web UI (beta). * **Job Scheduling:** Job scheduling for ad-hoc jobs. * **Datastore viewer/editor:** Datastore viewer/editor at web UI. * **History and Audit service:** History view with advanced search over years worth of execution @@ -59,6 +59,17 @@ Submit a PR! Release History --------------- +.. rubric:: Done in v3.9 + +* **MongoDB compatibility:** Support for versions greater than v4.x add with v7.x being actively tested. +* **RHEL/RockyLinux 9:** is now supported which has replaced RHEL7 in the supported OS matrix. +* **Ubuntu Jammy 22.04:** is now supported and has replaced Ubuntu Bionic 18.04 +* **Python 3.9, 3.10 & 3.11:** st2 is now tested against supported version of Python. Python 3.6 support has been removed. + +.. rubric:: Done in v3.8 + +* **Output Schema:** Allow action/runner output schemas to cover all output types, not just JSON objects. + .. rubric:: Done in v3.7 * **RHEL/RockyLinux 8:** EL8 support continues, despite the deprecation of CentOS 8. We now use RockyLinux 8 to build for and test on EL8. diff --git a/docs/source/rules.rst b/docs/source/rules.rst index 01a21a13f..403c4b305 100644 --- a/docs/source/rules.rst +++ b/docs/source/rules.rst @@ -577,7 +577,7 @@ Variable Interpolation Occasionally, it will be necessary to pass along context of a trigger to an action when a rule is \ matched. The rules engine is able to interpolate variables by leveraging `Jinja templating syntax -`__. +`__. .. code-block:: yaml diff --git a/docs/source/sensors.rst b/docs/source/sensors.rst index 911702354..88840bb68 100644 --- a/docs/source/sensors.rst +++ b/docs/source/sensors.rst @@ -31,6 +31,26 @@ A list of available triggers for each resource is included below: .. _ref-sensors-authoring-a-sensor: +An example rule to use ``core.st2.key_value_pair.*`` triggers is included below: + +.. code-block:: yaml + + trigger: + type: "core.st2.key_value_pair.create" + + criteria: + trigger.object.name: + type: "eq" + pattern: "x" + + action: + ref: "core.local" + parameters: + cmd: "echo {{ trigger.object }}" + +Above rule will execute whenever a new key-value pair with name ``x`` is created in the +datastore. The action will print the details of the created key-value pair. + Creating a Sensor ----------------- diff --git a/docs/source/troubleshooting/purging_old_data.rst b/docs/source/troubleshooting/purging_old_data.rst index 4b46e4620..8ac40a8c0 100644 --- a/docs/source/troubleshooting/purging_old_data.rst +++ b/docs/source/troubleshooting/purging_old_data.rst @@ -44,7 +44,7 @@ In this case, the following objects will be automatically deleted: * workflow task execution objects older than 19 days * token objects whose expiry was older than 21 days -The lowest supported TTL is 7 days. If you need to delete old data more frequently, check the +The lowest supported TTL is 1 day. If you need to delete old data more frequently, check the manual purge scripts below. The garbage collector service also cleans up old Inquiries by marking them as "timed out". diff --git a/docs/source/upgrade_notes.rst b/docs/source/upgrade_notes.rst index 171b51255..834e6eba5 100644 --- a/docs/source/upgrade_notes.rst +++ b/docs/source/upgrade_notes.rst @@ -3,6 +3,75 @@ Upgrade Notes ============= +.. _ref-upgrade-notes-v3-9: + +|st2| v3.9 +---------- + + * Compatibility updates. + + * Linux distribution support for Ubuntu 22.04 Jammy and RockyLinux 9 (RHEL9 compatible) has been added. Support for Ubuntu 18.04 Focal and CentOS 7 has been removed. + * Python versions from ``3.8`` to ``3.11`` are supported along with the removal of ``3.6`` support. + * MongoDB compatibility ranges from ``4.x`` to ``v7.x`` for the official MongoDB database. + + * Configuration updates required in ``st2.conf``. + + Several ``st2.conf`` database options have been renamed or deprecated. Most of the options will continue to work using their old name. + However, if you use `[database].ssl_keyfile` and/or `[database].ssl_certfile`, you MUST migrate to `[database].tls_certificate_key_file`. + This new option expects the key and certificate in the same file. Use something like the following to create that file from your old files: + + .. code-block:: + + cat path/to/ssl_keyfile path/to/ssl_certfile > path/to/tls_certificate_key_file + + + Other options that were renamed under ``[database]`` are (more details available in ``st2.conf.sample``): + + * ``ssl`` -> ``tls`` + * ``ssl_cert_reqs`` -> ``tls_allow_invalid_certificates`` (opt type change: string -> boolean) + * ``ssl_ca_certs`` -> ``tls_ca_file`` + * ``ssl_match_hostnames`` -> ``tls_allow_invalid_hostnames`` (meaning is inverted: the new option is the opposite of the old) + +* YAQL `format` fucntion removed. + + Due to security concerns related to potential unauthorised data access the `str().format()` function was removed. Upstream developers + recommend to replace the use of `format` with string concatentation. Users can replace the ``format`` function by the ``+`` operator and the ``str`` YAQL function. + + ``format("{0}-{1}", a b)`` rewirtten as ``str(a) + '-' + str(b)`` + Further details can be seen in the security issue https://bugs.launchpad.net/murano/+bug/2048114 + + In cases where the string is not controlled by the workflow directly, the `replace` function can be used. + + *Workflow Context* + + .. code-block:: yaml + + { + "name": "hostname1", + "status": "Online", + "string_keywords": "Server {name} is {status}.", + "string_positional": "Server {0} is {1}." + } + + *String using keyword* + + .. code-block:: + + <% ctx(string_keywords).replace("{name}", ctx(name)).replace("{status}", ctx(status)) %> + + *String using positional arguments* + + .. code-block:: + + <% ctx(string_positional).replace("{0}", ctx(name)).replace("{1}", ctx(status)) %> + + *Output* + :: + + 'Server hostname1 is Online.' + + Use Jinja in cases where `replace` isn't optimal. + .. _ref-upgrade-notes-v3-8: |st2| v3.8 @@ -50,6 +119,16 @@ Upgrade Notes You can also install pack updates during an upgrade, while StackStorm is not running, by using the ``st2-pack-install`` utility: ``st2-pack-install ``. +* As part of extending RBAC support to include protecting access to datastore operations, if + you have RBAC enabled and any workflows access the datastore, then any user with execute + permissions for those workflows will need to be assigned an RBAC role with the appropriate + key_value_pair permissions. + Further information can be found in the :doc:`RBAC documentation `. + +* Additional garbage collection options are available to automatically delete old tokens. + See :doc:`purging old data documentation ` for further + information. + .. _ref-upgrade-notes-v3-7: |st2| v3.7 @@ -92,7 +171,7 @@ Upgrade Notes * As part of extending RBAC support to include protecting access to datastore operations, if you have RBAC enabled and any sensors access the datastore, then the ``sensor_service`` user will - need to be assigned an RBAC role with the appropriate key_value_pair permissions. + need to be assigned an RBAC role with the appropriate key_value_pair permissions. Further information can be found in the :doc:`RBAC documentation `. .. _ref-upgrade-notes-v3-6: @@ -146,10 +225,10 @@ Upgrade Notes * ``%`` interpolation in st2 configuration parameters is no longer supported. Update your configuration parameters to fix strings if you use ``%`` interpolation to lookup keys as part of your parameter. - + Now ``%`` is a valid character in parameter values. - - This increases security because passwords with a ``%`` in it do no longer result into an error. + + This increases security because passwords with a ``%`` in it do no longer result into an error. * The underlying database field type for storing large values such as action execution result has changed for various database models (ActionExecutionDB, LiveActionDB, WorkflowExecutionDB, @@ -278,11 +357,11 @@ Upgrade Notes the ``/opt/stackstorm/st2`` virtualenv. This is caused by the fact that the core ``st2`` package no longer bundles in the ``pyasn1`` module, so it will be absent post-upgrade. Running following command will be necessary for ``st2auth`` to function again: - + .. code-block:: bash /opt/stackstorm/st2/bin/pip install pyasn1 - + .. _ref-upgrade-notes-v3-0: @@ -395,7 +474,7 @@ Upgrade Notes ``sudo st2ctl reload --register-runners`` command. Keep in mind that all the runners which are installed inside |st2| virtual environment are now - automatically loaded and registered on each |st2| service start up. You only need to run + automatically loaded and registered on each |st2| service start up. You only need to run ``sudo st2ctl reload --register-runners`` if you are using runner outside the service context or if you didn't restart the services. diff --git a/requirements.txt b/requirements.txt index 12e30d913..4a1c0fac0 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,7 @@ -docutils==0.16.0 -sphinx>=2.4.4,<3.0 +docutils==0.21.2 +sphinx==8.1.3 sphinx-autobuild -sphinx-sitemap==2.1.0 +# py3.10 with sphinx-sitemap>2.3.0 fail with exception: [Errno 11] Resource temporarily unavailable +sphinx-sitemap<=2.3.0 +sphinx-rtd-theme +jinja2 diff --git a/version.txt b/version.txt index 2090923ec..f4a91a70c 100644 --- a/version.txt +++ b/version.txt @@ -1 +1 @@ -3.8dev +3.10dev