From 27a1619db0ab8fa003dfde3d1a038d51cfbc4490 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 22:19:31 -0500 Subject: [PATCH 01/67] move _static/*.css -> _static/css/ --- docs/source/_static/{ => css}/theme_overrides.css | 0 docs/source/conf.py | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/source/_static/{ => css}/theme_overrides.css (100%) 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/conf.py b/docs/source/conf.py index 071d2d236..21a2c8695 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -292,7 +292,7 @@ def previous_version(ver): ], 'current_version': version, 'css_files': [ - '_static/theme_overrides.css', + '_static/css/theme_overrides.css', ], } From ad9999045deba7239adc94bfee6a7f518466bf7b Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 22:23:56 -0500 Subject: [PATCH 02/67] switch from old forked in-repo theme to upstream 1.0.0 --- docs/source/conf.py | 5 +++-- requirements.txt | 1 + 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 21a2c8695..896c1cff4 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,6 +16,8 @@ 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')) @@ -30,7 +32,7 @@ # 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__ @@ -203,7 +205,6 @@ def previous_version(ver): # 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". diff --git a/requirements.txt b/requirements.txt index 12e30d913..a2b3eb1d7 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,3 +2,4 @@ docutils==0.16.0 sphinx>=2.4.4,<3.0 sphinx-autobuild sphinx-sitemap==2.1.0 +sphinx-rtd-theme==1.0.0 From 019ef1465f2f3fd63eaca5448e289ac7d8ec8130 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 22:38:36 -0500 Subject: [PATCH 03/67] switch to standard sphinx var for html_base_url rtd-sphinx-theme says that the "canonical_url" setting is deprecated in favor of the standard sphinx "html_base_url". see: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#confval-canonical_url see: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl --- docs/source/conf.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 896c1cff4..8ceb86f5a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -198,10 +198,11 @@ def previous_version(ver): # Theme options are theme-specific and customize the look and feel of a theme # 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 -} +html_theme_options = {} + +if "READTHEDOCS" not in os.environ: + # set the canonical url to our custom domain unless testing on RTD + html_base_url = info.theme_base_url # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] From 3b552ba96105dd98ef8d269fdbd8d4ccf34ebf82 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 22:42:25 -0500 Subject: [PATCH 04/67] port logo and favicon to new theme these were embedded in the old forked theme. --- .../source/_static/css/rtd_theme_overrides.css | 7 +++++++ docs/source/_static/images/favicon.ico | Bin 0 -> 1150 bytes docs/source/_static/images/logo.svg | 17 +++++++++++++++++ docs/source/conf.py | 17 +++++++++++------ 4 files changed, 35 insertions(+), 6 deletions(-) create mode 100644 docs/source/_static/css/rtd_theme_overrides.css create mode 100644 docs/source/_static/images/favicon.ico create mode 100644 docs/source/_static/images/logo.svg 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..cce4f3bc9 --- /dev/null +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -0,0 +1,7 @@ +.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 */ +} diff --git a/docs/source/_static/images/favicon.ico b/docs/source/_static/images/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..64880c4f5c938cadae229c70f9c29ad1cf47cd75 GIT binary patch literal 1150 zcmb`FF;2rk5Je{<5<)bFf;x1RIZ8?*nv|3|f)gm{as(fNBRDyMkH8Upg2=qT@mQm1 z0V7ECyz8BLIAkINQGWHpH@f72@e^{n@?$lcTtvk + + + + + + + + + + + + + + + + diff --git a/docs/source/conf.py b/docs/source/conf.py index 8ceb86f5a..1fe29b801 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -198,7 +198,15 @@ def previous_version(ver): # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -html_theme_options = {} +html_theme_options = { + # see: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html + "logo_only": True, +} + +html_css_files = [ + "css/theme_overrides.css", + "css/rtd_theme_overrides.css", +] if "READTHEDOCS" not in os.environ: # set the canonical url to our custom domain unless testing on RTD @@ -216,12 +224,12 @@ 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, @@ -293,9 +301,6 @@ def previous_version(ver): (version_minus_2, '%s%s' % (info.base_url, version_minus_2)), ], 'current_version': version, - 'css_files': [ - '_static/css/theme_overrides.css', - ], } From 3bf401ba59aed6ddf00f495e0b5f9f53812c9f3e Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:00:14 -0500 Subject: [PATCH 05/67] port external link handling to new theme --- docs/source/_static/js/rtd_theme_overrides.js | 4 ++++ docs/source/conf.py | 4 ++++ 2 files changed, 8 insertions(+) create mode 100644 docs/source/_static/js/rtd_theme_overrides.js 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..ad9df4b3b --- /dev/null +++ b/docs/source/_static/js/rtd_theme_overrides.js @@ -0,0 +1,4 @@ +$( document ).ready(function() { + // Open external links in another tab/window + $(".external").attr("target","_blank"); +}); diff --git a/docs/source/conf.py b/docs/source/conf.py index 1fe29b801..2cf49ee3e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -201,12 +201,16 @@ def previous_version(ver): html_theme_options = { # see: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html "logo_only": True, + "style_external_links": True, } html_css_files = [ "css/theme_overrides.css", "css/rtd_theme_overrides.css", ] +html_js_files = [ + "js/rtd_theme_overrides.js", +] if "READTHEDOCS" not in os.environ: # set the canonical url to our custom domain unless testing on RTD From 7b3f34ac46fdaa0173cc45ef3ae9da9b2975a90c Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:01:55 -0500 Subject: [PATCH 06/67] port version-in-breadcrumb to new theme --- docs/source/_static/css/rtd_theme_overrides.css | 4 ++++ docs/source/_static/js/rtd_theme_overrides.js | 5 +++++ docs/source/conf.py | 2 ++ 3 files changed, 11 insertions(+) diff --git a/docs/source/_static/css/rtd_theme_overrides.css b/docs/source/_static/css/rtd_theme_overrides.css index cce4f3bc9..2c72e4eaa 100644 --- a/docs/source/_static/css/rtd_theme_overrides.css +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -5,3 +5,7 @@ /* 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/js/rtd_theme_overrides.js b/docs/source/_static/js/rtd_theme_overrides.js index ad9df4b3b..9bd644247 100644 --- a/docs/source/_static/js/rtd_theme_overrides.js +++ b/docs/source/_static/js/rtd_theme_overrides.js @@ -1,4 +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/conf.py b/docs/source/conf.py index 2cf49ee3e..436d1d789 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -201,6 +201,8 @@ def previous_version(ver): html_theme_options = { # see: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html "logo_only": True, + # display_version puts rtd slug/version at top of sidebar, but we use breadcrumbs instead + "display_version": False, "style_external_links": True, } From 752bd7ac6a969f6bbe0f7bde80efadb59819e3a4 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:04:44 -0500 Subject: [PATCH 07/67] port colors (with tweaks) to new theme --- .../_static/css/rtd_theme_overrides.css | 38 +++++++++++++++++++ docs/source/conf.py | 1 + 2 files changed, 39 insertions(+) diff --git a/docs/source/_static/css/rtd_theme_overrides.css b/docs/source/_static/css/rtd_theme_overrides.css index 2c72e4eaa..2df786e55 100644 --- a/docs/source/_static/css/rtd_theme_overrides.css +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -1,3 +1,41 @@ +/** + * 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; diff --git a/docs/source/conf.py b/docs/source/conf.py index 436d1d789..34a6a8c36 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -200,6 +200,7 @@ def previous_version(ver): # documentation. html_theme_options = { # 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, From ba08b2b37e437f977f281454a50eba57d5149f4c Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:11:15 -0500 Subject: [PATCH 08/67] port fonts to new theme only missing the link that was in the old theme layout: https://github.com/StackStorm/st2docs/blob/828b2a2a7b3e24630aee816303cb0cad50115bf3/docs/source/_themes/sphinx_rtd_theme/layout.html#L35 --- .../_static/css/rtd_theme_overrides.css | 30 ++++++++++++++++++- .../css/rtd_theme_overrides.unused.css | 25 ++++++++++++++++ 2 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 docs/source/_static/css/rtd_theme_overrides.unused.css diff --git a/docs/source/_static/css/rtd_theme_overrides.css b/docs/source/_static/css/rtd_theme_overrides.css index 2df786e55..048552195 100644 --- a/docs/source/_static/css/rtd_theme_overrides.css +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -1,3 +1,31 @@ +/* $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 @@ -39,7 +67,7 @@ .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 */ } 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; +} From 75823a5d0d7494a7787f9cd243bdecf6a2415031 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:13:13 -0500 Subject: [PATCH 09/67] remove max-width on new theme --- docs/source/_static/css/rtd_theme_overrides.css | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/source/_static/css/rtd_theme_overrides.css b/docs/source/_static/css/rtd_theme_overrides.css index 048552195..0c6ec0a62 100644 --- a/docs/source/_static/css/rtd_theme_overrides.css +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -1,3 +1,8 @@ +/* layout changes */ +.wy-nav-content { + max-width: none; /* was 800px */ +} + /* $base-font-family: Lato,proxima-nova,Helvetica Neue,Arial,sans-serif; */ .btn { font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; From 7a6af12df46244b6dfa2def8e4e1b37e4a129e9c Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:23:51 -0500 Subject: [PATCH 10/67] configure the vcs link bits of the theme --- docs/source/conf.py | 10 ++++++---- docs/source/info.py | 6 +++--- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 34a6a8c36..70c61d29d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -205,6 +205,7 @@ def previous_version(ver): # display_version puts rtd slug/version at top of sidebar, but we use breadcrumbs instead "display_version": False, "style_external_links": True, + "vcs_pageview_mode": "blob", # blob, edit, raw } html_css_files = [ @@ -295,11 +296,12 @@ 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, + # 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/', - 'display_github': True, 'source_suffix': source_suffix, 'versions': [ ('latest', '%slatest' % info.base_url), diff --git a/docs/source/info.py b/docs/source/info.py index 28f47aac5..fc49663d7 100644 --- a/docs/source/info.py +++ b/docs/source/info.py @@ -30,8 +30,8 @@ 'Miscellaneous'), ] -github_user = 'StackStorm' -github_repo = 'st2docs' -github_version = 'master' +github_user = "StackStorm" +github_repo = "st2docs" +github_version = "master" theme_base_url = u'https://docs.stackstorm.com/' From 93568fef1fcd408c3791beb1142dfedbe78aa5c7 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:25:46 -0500 Subject: [PATCH 11/67] cleanup author info --- docs/source/info.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/info.py b/docs/source/info.py index fc49663d7..dec802a00 100644 --- a/docs/source/info.py +++ b/docs/source/info.py @@ -9,9 +9,9 @@ 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/' htmlhelp_basename = 'StackStormDoc' From e59c7237fd0822ceb51cc9824f4fc5f70c90604c Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:26:50 -0500 Subject: [PATCH 12/67] drop duplicate config for base_url --- docs/source/conf.py | 2 +- docs/source/info.py | 4 +--- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 70c61d29d..1f9bb902a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -218,7 +218,7 @@ def previous_version(ver): if "READTHEDOCS" not in os.environ: # set the canonical url to our custom domain unless testing on RTD - html_base_url = info.theme_base_url + html_base_url = info.base_url # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] diff --git a/docs/source/info.py b/docs/source/info.py index dec802a00..f487100b1 100644 --- a/docs/source/info.py +++ b/docs/source/info.py @@ -13,7 +13,7 @@ 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 = [ @@ -33,5 +33,3 @@ github_user = "StackStorm" github_repo = "st2docs" github_version = "master" - -theme_base_url = u'https://docs.stackstorm.com/' From 86f1db3c239b8d7305621a44637abc1ec7c7d561 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sun, 24 Jul 2022 00:53:11 -0500 Subject: [PATCH 13/67] add versions bit --- docs/source/conf.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 1f9bb902a..2fd354463 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -303,14 +303,17 @@ def previous_version(ver): "github_version": info.github_version, 'conf_py_path': '/docs/source/', 'source_suffix': source_suffix, - 'versions': [ +} + +if "READTHEDOCS" not in os.environ: + # READTHEDOCS handles versions for us. TODO: is this needed locally with the new theme? + html_context['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, -} + ] + html_context['current_version'] = version # -- Options for LaTeX output --------------------------------------------- From 06bb91c585f69e30b04ce7d59d2c29ff5799b00f Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 30 Jul 2022 16:43:09 -0500 Subject: [PATCH 14/67] correct html_baseurl var name --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 2fd354463..8a60030f5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -218,7 +218,7 @@ def previous_version(ver): if "READTHEDOCS" not in os.environ: # set the canonical url to our custom domain unless testing on RTD - html_base_url = info.base_url + html_baseurl = info.base_url # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] From 9b4f909da76cc829cceb56f23e3a9c12510f5e2b Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sun, 31 Jul 2022 01:18:19 -0500 Subject: [PATCH 15/67] add font css --- docs/source/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 8a60030f5..e3fd9864a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -208,9 +208,12 @@ def previous_version(ver): "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", From 8de55ed94b59df26b9e910b28f084c5d142ed343 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sun, 31 Jul 2022 11:54:46 -0500 Subject: [PATCH 16/67] add versions menu --- docs/source/_templates/version_menu.html | 38 ++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/source/_templates/version_menu.html diff --git a/docs/source/_templates/version_menu.html b/docs/source/_templates/version_menu.html new file mode 100644 index 000000000..33ee64144 --- /dev/null +++ b/docs/source/_templates/version_menu.html @@ -0,0 +1,38 @@ +{%- 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 %} +
+ + Read the Docs + v: {{ current_version }} + + +
+
+
{{ _('Versions') }}
+ {% for slug, url in versions %} +
{{ slug }}
+ {% endfor %} +
+
+
{{ _('Downloads') }}
+ {% for type, url in downloads %} +
{{ type }}
+ {% endfor %} +
+
+
+ {%- endif %} +{%- endblock %} From fe6e72cc378748a03b789c675b8a220c4a5d342c Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sun, 31 Jul 2022 22:08:33 -0500 Subject: [PATCH 17/67] add versions.js for backwards compat w/ previous docs versions --- docs/source/_static/js/versions.js_t | 40 ++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/source/_static/js/versions.js_t 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); + }); +})() From a907868ad9007775b726352e155ab7066e1dc088 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sun, 31 Jul 2022 22:37:40 -0500 Subject: [PATCH 18/67] add sitemap to new theme --- docs/source/conf.py | 14 +++++++++----- requirements.txt | 2 +- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index e3fd9864a..5fd51b9d5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -53,8 +53,10 @@ 'sphinx.ext.todo', 'sphinx.ext.extlinks', - # Add theme as extension so sitemap.xml is generated - 'sphinx_rtd_theme' + # 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. @@ -219,9 +221,11 @@ def previous_version(ver): "js/rtd_theme_overrides.js", ] -if "READTHEDOCS" not in os.environ: - # set the canonical url to our custom domain unless testing on RTD - html_baseurl = info.base_url +# set the canonical url to our custom domain (required for sitemap generation) +html_baseurl = info.base_url +sitemap_filename = "sitemap.xml" +# sitemap_url_scheme = "{lang}{version}{link}" +sitemap_url_scheme = "{version}{link}" # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] diff --git a/requirements.txt b/requirements.txt index a2b3eb1d7..00e36d6fb 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,5 @@ docutils==0.16.0 sphinx>=2.4.4,<3.0 sphinx-autobuild -sphinx-sitemap==2.1.0 +sphinx-sitemap==2.2.0 sphinx-rtd-theme==1.0.0 From 8fc5df33271aab46171ef1cea52c246991f0c91b Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Tue, 2 Aug 2022 22:13:38 -0500 Subject: [PATCH 19/67] fix template --- docs/source/_templates/{version_menu.html => layout.html} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/source/_templates/{version_menu.html => layout.html} (100%) diff --git a/docs/source/_templates/version_menu.html b/docs/source/_templates/layout.html similarity index 100% rename from docs/source/_templates/version_menu.html rename to docs/source/_templates/layout.html From 7bf423fb94d15f030415991c03953f689682869f Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Tue, 2 Aug 2022 22:34:57 -0500 Subject: [PATCH 20/67] better sitemap --- docs/source/conf.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 5fd51b9d5..701d311e6 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -224,8 +224,10 @@ def previous_version(ver): # set the canonical url to our custom domain (required for sitemap generation) html_baseurl = info.base_url sitemap_filename = "sitemap.xml" -# sitemap_url_scheme = "{lang}{version}{link}" -sitemap_url_scheme = "{version}{link}" +if "READTHEDOCS" in os.environ: + sitemap_url_scheme = "{lang}{version}{link}" +else: + sitemap_url_scheme = "{version}{link}" # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] From 8ef2d157db66944170e24c56fb1f839c6c5c1453 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Wed, 3 Aug 2022 12:47:36 -0500 Subject: [PATCH 21/67] fix locally rendered versions menu --- docs/source/_static/css/rtd_theme_overrides.css | 3 +++ docs/source/_templates/layout.html | 4 +++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/source/_static/css/rtd_theme_overrides.css b/docs/source/_static/css/rtd_theme_overrides.css index 0c6ec0a62..697e6b88f 100644 --- a/docs/source/_static/css/rtd_theme_overrides.css +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -2,6 +2,9 @@ .wy-nav-content { max-width: none; /* was 800px */ } +.wy-nav-side { + padding-bottom: 2.75em; +} /* $base-font-family: Lato,proxima-nova,Helvetica Neue,Arial,sans-serif; */ .btn { diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html index 33ee64144..9a7ac6fb4 100644 --- a/docs/source/_templates/layout.html +++ b/docs/source/_templates/layout.html @@ -15,7 +15,7 @@ {%- if not READTHEDOCS %}
- Read the Docs + v: {{ current_version }} @@ -26,12 +26,14 @@
{{ slug }}
{% endfor %} + {% if downloads %}
{{ _('Downloads') }}
{% for type, url in downloads %}
{{ type }}
{% endfor %}
+ {% endif %}
{%- endif %} From 9a5344cf6d676d5b2a44459936d2bff164c0e9c5 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Wed, 3 Aug 2022 13:13:58 -0500 Subject: [PATCH 22/67] fix latest/ sitemap --- docs/source/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 701d311e6..f97b30531 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -226,6 +226,9 @@ def previous_version(ver): sitemap_filename = "sitemap.xml" if "READTHEDOCS" in os.environ: sitemap_url_scheme = "{lang}{version}{link}" +elif "dev" in version: + # use latest/ instead of 3.8dev/ + sitemap_url_scheme = "latest/{link}" else: sitemap_url_scheme = "{version}{link}" From e1ab2247a9a2310074e0674086743a09301bbe54 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Wed, 3 Aug 2022 15:14:46 -0500 Subject: [PATCH 23/67] copy RTD override for menu flyout --- docs/source/_static/css/rtd_theme_overrides.css | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/source/_static/css/rtd_theme_overrides.css b/docs/source/_static/css/rtd_theme_overrides.css index 697e6b88f..8fb7c0c6a 100644 --- a/docs/source/_static/css/rtd_theme_overrides.css +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -2,8 +2,9 @@ .wy-nav-content { max-width: none; /* was 800px */ } -.wy-nav-side { - padding-bottom: 2.75em; +/* 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; */ From 09f07a7935b49db731c90d9220f5398c378b481a Mon Sep 17 00:00:00 2001 From: Carlos Date: Wed, 14 Sep 2022 18:10:12 +0200 Subject: [PATCH 24/67] Fix Ubuntu OS codename in rabbitmq installation examples. --- docs/source/install/u18.rst | 8 ++++---- docs/source/install/u20.rst | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/source/install/u18.rst b/docs/source/install/u18.rst index e379710a1..1abac6686 100644 --- a/docs/source/install/u18.rst +++ b/docs/source/install/u18.rst @@ -49,13 +49,13 @@ Install MongoDB, RabbitMQ, and Redis: ## Provides modern Erlang/OTP releases ## - deb [signed-by=/usr/share/keyrings/io.cloudsmith.dl.rabbitmq.erlang.gpg] http://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu ${SUBTYPE} main - deb-src [signed-by=/usr/share/keyrings/io.cloudsmith.dl.rabbitmq.erlang.gpg] http://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu ${SUBTYPE} main + deb [signed-by=/usr/share/keyrings/io.cloudsmith.dl.rabbitmq.erlang.gpg] http://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu bionic main + deb-src [signed-by=/usr/share/keyrings/io.cloudsmith.dl.rabbitmq.erlang.gpg] http://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/deb/ubuntu bionic main ## Provides RabbitMQ ## - deb [signed-by=/usr/share/keyrings/io.cloudsmith.dl.rabbitmq.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/ubuntu/ ${SUBTYPE} main - deb-src [signed-by=/usr/share/keyrings/io.cloudsmith.dl.rabbitmq.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/ubuntu/ ${SUBTYPE} main + deb [signed-by=/usr/share/keyrings/io.cloudsmith.dl.rabbitmq.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/ubuntu/ bionic main + deb-src [signed-by=/usr/share/keyrings/io.cloudsmith.dl.rabbitmq.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/ubuntu/ bionic main EOF sudo tee /etc/apt/preferences.d/erlang < Date: Thu, 29 Sep 2022 15:23:32 +0100 Subject: [PATCH 25/67] Update to use latest erlang (i.e. 25) --- docs/source/install/rhel8.rst | 8 +------- docs/source/install/u18.rst | 11 ----------- docs/source/install/u20.rst | 11 ----------- 3 files changed, 1 insertion(+), 29 deletions(-) diff --git a/docs/source/install/rhel8.rst b/docs/source/install/rhel8.rst index 0e1cd85b6..d8cddad26 100644 --- a/docs/source/install/rhel8.rst +++ b/docs/source/install/rhel8.rst @@ -81,18 +81,12 @@ Install MongoDB, RabbitMQ, and Redis: curl -sL https://packagecloud.io/install/repositories/rabbitmq/erlang/script.rpm.sh | sudo bash curl -sL https://packagecloud.io/install/repositories/rabbitmq/rabbitmq-server/script.rpm.sh | sudo bash sudo yum makecache -y --disablerepo='*' --enablerepo='rabbitmq_rabbitmq-server' - sudo yum -y install erlang-24* + sudo yum -y install erlang-* sudo yum -y install rabbitmq-server sudo yum -y install redis sudo systemctl start mongod rabbitmq-server redis sudo systemctl enable mongod rabbitmq-server redis -.. note:: - - RabbitMQ currently only has preview support for Erlang 25, however it is available in the - RabbitMQ-Erlang repository. Whilst Erlang 25 support is in preview (https://www.rabbitmq.com/which-erlang.html) - it is advised to install the latest Erlang 24 version instead. - Setup Repositories ~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/install/u18.rst b/docs/source/install/u18.rst index e379710a1..0a935ae6c 100644 --- a/docs/source/install/u18.rst +++ b/docs/source/install/u18.rst @@ -59,11 +59,6 @@ Install MongoDB, RabbitMQ, and Redis: EOF sudo tee /etc/apt/preferences.d/erlang < Date: Thu, 29 Sep 2022 16:26:27 +0200 Subject: [PATCH 26/67] Pin jinja2 as per https://github.com/sphinx-doc/sphinx/issues/10291 --- requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements.txt b/requirements.txt index 12e30d913..99b729ac4 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,3 +2,4 @@ docutils==0.16.0 sphinx>=2.4.4,<3.0 sphinx-autobuild sphinx-sitemap==2.1.0 +jinja2<3.1 From b2e8d57c5a62361057279990059cc9ccd43fdd60 Mon Sep 17 00:00:00 2001 From: Anurag Harsh Date: Sat, 22 Oct 2022 19:00:35 +0530 Subject: [PATCH 27/67] Fix curl request in Service Testing st2docs --- docs/source/reference/monitoring.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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|. From 0b6b08d7436c31af17e0f68d50e07ac469c7608f Mon Sep 17 00:00:00 2001 From: amanda Date: Fri, 28 Oct 2022 14:57:26 +0100 Subject: [PATCH 28/67] Add warning about workflows using key/value pairs --- docs/source/upgrade_notes.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/source/upgrade_notes.rst b/docs/source/upgrade_notes.rst index 171b51255..d72b5356f 100644 --- a/docs/source/upgrade_notes.rst +++ b/docs/source/upgrade_notes.rst @@ -50,6 +50,12 @@ 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 `. + .. _ref-upgrade-notes-v3-7: |st2| v3.7 From 544e21e96c27228f11e49660ed5783884eea053e Mon Sep 17 00:00:00 2001 From: Carlos Date: Wed, 26 Oct 2022 12:04:31 +0200 Subject: [PATCH 29/67] Add warning for unsupported architecture, platform and distribution. --- docs/source/install/index.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/source/install/index.rst b/docs/source/install/index.rst index 042535047..40d6004a6 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 @@ -18,7 +26,7 @@ Here's an overview of the options: :doc:`RHEL/CentOS 7 `, :doc:`RHEL/RockyLinux/CentOS 8 `) 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, @@ -57,7 +65,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. From 5530606749e182efabcfdc4054914ccb1f7b2c35 Mon Sep 17 00:00:00 2001 From: amanda Date: Mon, 7 Nov 2022 15:45:37 +0000 Subject: [PATCH 30/67] Minor doc changes related to garbage collection --- docs/source/troubleshooting/purging_old_data.rst | 2 +- docs/source/upgrade_notes.rst | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) 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 d72b5356f..b41ed12b2 100644 --- a/docs/source/upgrade_notes.rst +++ b/docs/source/upgrade_notes.rst @@ -56,6 +56,10 @@ Upgrade Notes 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 From 2b2637b1f4d56e6f3685989bf69f62383686e7f6 Mon Sep 17 00:00:00 2001 From: Eugen Cusmaunsa <1533818+armab@users.noreply.github.com> Date: Thu, 10 Nov 2022 11:18:24 +0000 Subject: [PATCH 31/67] Update index.rst --- docs/source/install/index.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/source/install/index.rst b/docs/source/install/index.rst index 40d6004a6..94507d34e 100644 --- a/docs/source/install/index.rst +++ b/docs/source/install/index.rst @@ -46,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 From c7b208fa26cc00b1ce65282f943fb4fb09727813 Mon Sep 17 00:00:00 2001 From: stanley Date: Fri, 18 Nov 2022 06:58:00 +0000 Subject: [PATCH 32/67] Update version info for release - 3.8.0 --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 071d2d236..b774253f0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -79,7 +79,7 @@ # 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.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 From d95d7fa9822e5858141f30457b58e616cb40eafc Mon Sep 17 00:00:00 2001 From: stanley Date: Mon, 28 Nov 2022 21:34:38 +0000 Subject: [PATCH 33/67] Update version to 3.9dev --- version.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/version.txt b/version.txt index 2090923ec..83c5bc505 100644 --- a/version.txt +++ b/version.txt @@ -1 +1 @@ -3.8dev +3.9dev From 696becfdbf382468f040a03724f4d656f987251f Mon Sep 17 00:00:00 2001 From: litew <2027169+litew@users.noreply.github.com> Date: Mon, 5 Dec 2022 18:52:51 +0300 Subject: [PATCH 34/67] Update authentication.rst Fix option name for ldap groups TTL --- docs/source/authentication.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/authentication.rst b/docs/source/authentication.rst index 39db1ba82..6ceceab41 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:: From 0a0331d2eb1585f8b125052cf8bde5ee09bf1121 Mon Sep 17 00:00:00 2001 From: litew <2027169+litew@users.noreply.github.com> Date: Mon, 5 Dec 2022 19:46:43 +0300 Subject: [PATCH 35/67] Update authentication.rst Fix whitespace issue --- docs/source/authentication.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/authentication.rst b/docs/source/authentication.rst index 6ceceab41..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_cache_ttl | no | `120` | How long (in seconds) | +| cache_user_groups_cache_ttl | no | `120` | How long (in seconds) | +-----------------------------+----------+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+ .. note:: From 7722f174008a9f77945e854df68a66371e5c7286 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Tue, 7 Feb 2023 15:13:30 -0600 Subject: [PATCH 36/67] Fix broken "3.9dev" link in versions menu Always use "3.9dev" instead of latest in the menu. --- docs/source/conf.py | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 929837508..b6daa9cd1 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -103,6 +103,7 @@ def previous_version(ver): # 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 = { @@ -318,13 +319,30 @@ def previous_version(ver): } if "READTHEDOCS" not in os.environ: - # READTHEDOCS handles versions for us. TODO: is this needed locally with the new theme? - html_context['versions'] = [ - ('latest', '%slatest' % info.base_url), - (version, '%s%s' % (info.base_url, version)), + # 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 From 3d129b722b09708edb11d56d8e88dd294cf19cc6 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Tue, 7 Feb 2023 15:51:51 -0600 Subject: [PATCH 37/67] Add support for building docs on ReadTheDocs This is basically a squashed commit of what was left from the rtd branch --- .readthedocs.yaml | 63 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..a64c6e8d5 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,63 @@ +# .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-20.04 + tools: + # python: "3.6" + python: "3.8" + 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 + From e4b144b809c7f5939271d1313b0ae057c6ae1572 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Wed, 3 Aug 2022 15:32:22 -0500 Subject: [PATCH 38/67] improve RTD sitemap --- docs/source/conf.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 929837508..a5f805cca 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -225,7 +225,13 @@ def previous_version(ver): html_baseurl = info.base_url sitemap_filename = "sitemap.xml" if "READTHEDOCS" in os.environ: - sitemap_url_scheme = "{lang}{version}{link}" + 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}" From 78050b4cbd2a77641e87a7c049e8837c371eafd5 Mon Sep 17 00:00:00 2001 From: tomaz-suller Date: Fri, 23 Jun 2023 09:24:28 -0300 Subject: [PATCH 39/67] Fix broken references to Jinja docs #1130 missed some of the old references. This commit updates each one remaining to the new Jinja 2.11.x docs. --- docs/source/actionchain.rst | 2 +- docs/source/orquesta/start.rst | 2 +- docs/source/reference/jinja.rst | 2 +- docs/source/rules.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) 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/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/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 From c577aefe5a5a41a6df52b23e55e96b8ee2732969 Mon Sep 17 00:00:00 2001 From: Carlos Date: Tue, 19 Nov 2024 18:07:10 +0100 Subject: [PATCH 40/67] Add Ubuntu 22.04 Jammy installation --- docs/source/install/u22.rst | 221 ++++++++++++++++++++++++++++++++++++ 1 file changed, 221 insertions(+) create mode 100644 docs/source/install/u22.rst diff --git a/docs/source/install/u22.rst b/docs/source/install/u22.rst new file mode 100644 index 000000000..3f1f8b5d1 --- /dev/null +++ b/docs/source/install/u22.rst @@ -0,0 +1,221 @@ +Ubuntu Jammy (22.04) +===================== + +.. include:: common/intro.rst + +.. contents:: Contents + :local: + +.. note:: + + |st2| on Ubuntu ``22.04`` runs all services, actions and sensors using Python 3. + +System Requirements +------------------- + +Please check the :doc:`supported versions and system requirements `. + +Minimal Installation +-------------------- + +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 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 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 + + 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, 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 +`. + +.. code-block:: bash + + # Install st2web and nginx + sudo apt-get install -y st2web nginx + + # Generate self-signed certificate or place your existing certificate under /etc/ssl/st2 + sudo mkdir -p /etc/ssl/st2 + sudo openssl req -x509 -newkey rsa:2048 -keyout /etc/ssl/st2/st2.key -out /etc/ssl/st2/st2.crt \ + -days XXX -nodes -subj "/C=US/ST=California/L=Palo Alto/O=StackStorm/OU=Information \ + Technology/CN=$(hostname)" + + # 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 + 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/ + + sudo service nginx restart + +If you modify ports, or url paths in the nginx configuration, make the corresponding changes in +the st2web configuration at ``/opt/stackstorm/static/webui/config.js``. + +Use your browser to connect to ``https://${ST2_HOSTNAME}`` and login to the WebUI. + +.. 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 +described below. Otherwise, the easiest way to enable :doc:`StackStorm ChatOps ` +is to use the `st2chatops `_ package. + +* Validate that the ``chatops`` pack is installed, and a notification rule is enabled: + + .. code-block:: bash + + # Ensure chatops pack is in place + ls /opt/stackstorm/packs/chatops + # 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 v20 repository `_: + + .. code-block:: bash + + curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash + nvm install 20 + +* Install the ``st2chatops`` package: + + .. code-block:: bash + + sudo apt-get install -y st2chatops + +.. include:: common/configure_chatops.rst + +* Start the service: + + .. code-block:: bash + + sudo service st2chatops start + +* Reload st2 packs to make sure ``chatops.notify`` rule is registered: + + .. code-block:: bash + + sudo st2ctl reload --register-all + +* 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 + + +.. rubric:: What's Next? + +* Check out the :doc:`/start` Guide to build a simple automation. +* Get more actions, triggers, rules: + + + * Install integration packs from `StackStorm Exchange `__ - follow the :doc:`/packs` guide. + * :ref:`Convert your scripts into StackStorm actions. ` + * Learn how to :ref:`write custom actions `. + +* Use workflows to stitch actions into higher level automations - :doc:`/workflows`. +* Check out `tutorials on stackstorm.com `__ From eb22757c0b6a7f52b69a0379ed2d319fb8085296 Mon Sep 17 00:00:00 2001 From: Carlos Date: Tue, 19 Nov 2024 18:07:32 +0100 Subject: [PATCH 41/67] Add RHEL 9 installation --- docs/source/install/rhel9.rst | 276 ++++++++++++++++++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 docs/source/install/rhel9.rst diff --git a/docs/source/install/rhel9.rst b/docs/source/install/rhel9.rst new file mode 100644 index 000000000..b2fd439ca --- /dev/null +++ b/docs/source/install/rhel9.rst @@ -0,0 +1,276 @@ +RHEL 9/Rocky 9 +======================================================================== + +.. include:: common/intro.rst + +.. contents:: Contents + :local: + +System Requirements +------------------------------------------------------------------------ + +Please check the :doc:`supported versions and system requirements `. + +.. note:: + |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 +~~~~~~~~~~~~~~~~~~~~~~~ + +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, +you may want to tweak them according to your security practices. + +* First check if SELinux is in Enforcing mode: + + .. code-block:: bash + + getenforce + +* If the previous command returns 'Enforcing', then run the following commands: + + .. code-block:: bash + + # SELINUX management tools, not available for some minimal installations + sudo yum install -y policycoreutils-python-utils + + # Allow network access for nginx + sudo setsebool -P httpd_can_network_connect 1 + + # Allow RabbitMQ to use port '25672', otherwise it will fail to start + sudo semanage port --list | grep -q 25672 || sudo semanage port -a -t amqp_port_t -p tcp 25672 + +.. note:: + + If you see messages like "SELinux: Could not downgrade policy file", it means you are trying to + adjust policy configurations when SELinux is disabled. You can ignore this error. + +Install Dependencies +~~~~~~~~~~~~~~~~~~~~ + +.. include:: __mongodb_note.rst + +Install MongoDB, RabbitMQ, and Redis: + +.. code-block:: bash + + 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] + name=MongoDB Repository + baseurl=https://repo.mongodb.org/yum/redhat/8/mongodb-org/4.0/x86_64/ + gpgcheck=1 + enabled=1 + gpgkey=https://www.mongodb.org/static/pgp/server-4.0.asc + EOT" + + sudo yum -y install crudini + sudo yum -y install mongodb-org + curl -sL https://packagecloud.io/install/repositories/rabbitmq/erlang/script.rpm.sh | sudo bash + curl -sL https://packagecloud.io/install/repositories/rabbitmq/rabbitmq-server/script.rpm.sh | sudo bash + sudo yum makecache -y --disablerepo='*' --enablerepo='rabbitmq_rabbitmq-server' + sudo yum -y install erlang-* + sudo yum -y install rabbitmq-server + sudo yum -y install redis + sudo systemctl start mongod rabbitmq-server redis + sudo systemctl enable mongod rabbitmq-server redis + + +Setup Repositories +~~~~~~~~~~~~~~~~~~ + +The following script will detect your platform and architecture and setup the appropriate |st2| +repository. It will also add the the GPG key used for package signing. + +.. code-block:: bash + + curl -s https://packagecloud.io/install/repositories/StackStorm/stable/script.rpm.sh | sudo bash + +Install |st2| Components +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + sudo yum install -y st2 + +.. include:: common/configure_components.rst + +Setup Datastore Encryption +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: common/datastore_crypto_key.rst + +Configure SSH and SUDO +~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: common/configure_ssh_and_sudo.rst + +Start Services +~~~~~~~~~~~~~~ + +.. include:: common/start_services.rst + +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. + +To set up authentication with file-based provider: + +* Create a user with a password: + + .. code-block:: bash + + # Install htpasswd utility if you don't have it + sudo yum -y install httpd-tools + # Create a user record in a password file. + echo 'Ch@ngeMe' | sudo htpasswd -i /etc/st2/htpasswd st2admin + +.. 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 +``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 +`. + +|st2| depends on Nginx version >=1.7.5. RHEL has an older version in the package repositories, so +you will need to add the official Nginx repository: + +.. code-block:: bash + + # Add key and repo for the latest stable nginx + sudo rpm --import http://nginx.org/keys/nginx_signing.key + sudo sh -c "cat < /etc/yum.repos.d/nginx.repo + [nginx] + name=nginx repo + baseurl=http://nginx.org/packages/rhel/\\\$releasever/x86_64/ + gpgcheck=1 + enabled=1 + EOT" + + # Ensure that EPEL repo is not used for nginx + sudo sed -i 's/^\(enabled=1\)$/exclude=nginx\n\1/g' /etc/yum.repos.d/epel.repo + + # Install nginx + sudo yum install -y nginx + + # Install st2web + sudo yum install -y st2web + + # Generate a self-signed certificate or place your existing certificate under /etc/ssl/st2 + sudo mkdir -p /etc/ssl/st2 + sudo openssl req -x509 -newkey rsa:2048 -keyout /etc/ssl/st2/st2.key -out /etc/ssl/st2/st2.crt \ + -days 365 -nodes -subj "/C=US/ST=California/L=Palo Alto/O=StackStorm/OU=Information \ + Technology/CN=$(hostname)" + + # Copy and enable the supplied nginx config file + sudo cp /usr/share/doc/st2/conf/nginx/st2.conf /etc/nginx/conf.d/ + + # Disable default_server configuration in existing /etc/nginx/nginx.conf + sudo sed -i 's/default_server//g' /etc/nginx/nginx.conf + + sudo systemctl restart nginx + sudo systemctl enable nginx + +If you modify ports, or url paths in the nginx configuration, make the corresponding changes in +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-rhel8-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: + +.. code-block:: bash + + firewall-cmd --zone=public --add-service=http --add-service=https + firewall-cmd --zone=public --permanent --add-service=http --add-service=https + +This will allow inbound HTTP (port 80) and HTTPS (port 443) traffic, and make those changes +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 +described below. Otherwise, the easiest way to enable :doc:`StackStorm ChatOps ` +is to use the `st2chatops `_ package. + +* Validate that the ``chatops`` pack is installed, and a notification rule is enabled: + + .. code-block:: bash + + # Ensure chatops pack is in place + ls /opt/stackstorm/packs/chatops + # 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 v20 repository `_: + + .. code-block:: bash + + curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash + nvm install 20 + +* Install the ``st2chatops`` package: + + .. code-block:: bash + + sudo yum install -y st2chatops + +.. include:: common/configure_chatops.rst + +* Start the service: + + .. code-block:: bash + + sudo systemctl start st2chatops + + # Start st2chatops on boot + sudo systemctl enable st2chatops + +* Reload st2 packs to make sure the ``chatops.notify`` rule is registered: + + .. code-block:: bash + + sudo st2ctl reload --register-all + +* 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 + +.. rubric:: What's Next? + +* Check out the :doc:`/start` Guide to build a simple automation. +* Get more actions, triggers, rules: + + + * Install integration packs from `StackStorm Exchange `__ - follow the :doc:`/packs` guide. + * :ref:`Convert your scripts into StackStorm actions. ` + * Learn how to :ref:`write custom actions `. + +* Use workflows to stitch actions into higher level automations - :doc:`/workflows`. +* Check out `tutorials on stackstorm.com `__ From 81d579d62447b95d993f667d12c8701fba4b2aed Mon Sep 17 00:00:00 2001 From: Carlos Date: Tue, 19 Nov 2024 18:07:59 +0100 Subject: [PATCH 42/67] Drop RHEL7 installation --- docs/source/install/rhel7.rst | 304 ---------------------------------- 1 file changed, 304 deletions(-) delete mode 100644 docs/source/install/rhel7.rst diff --git a/docs/source/install/rhel7.rst b/docs/source/install/rhel7.rst deleted file mode 100644 index 94de13cc1..000000000 --- a/docs/source/install/rhel7.rst +++ /dev/null @@ -1,304 +0,0 @@ -RHEL 7/CentOS 7 -=============== - -.. include:: common/intro.rst - -.. contents:: Contents - :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. - -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, -you may want to tweak them according to your security practices. - -* First check if SELinux is in Enforcing mode: - - .. code-block:: bash - - getenforce - -* If the previous command returns 'Enforcing', then run the following commands: - - .. code-block:: bash - - # SELINUX management tools, not available for some minimal installations - sudo yum install -y policycoreutils-python - - # Allow network access for nginx - sudo setsebool -P httpd_can_network_connect 1 - - # Allow RabbitMQ to use port '25672', otherwise it will fail to start - sudo semanage port --list | grep -q 25672 || sudo semanage port -a -t amqp_port_t -p tcp 25672 - -.. note:: - - If you see messages like "SELinux: Could not downgrade policy file", it means you are trying to - adjust policy configurations when SELinux is disabled. You can ignore this error. - -Install Dependencies -~~~~~~~~~~~~~~~~~~~~ - -.. include:: __mongodb_note.rst - -Install MongoDB, RabbitMQ, and Redis - -.. code-block:: bash - - sudo yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.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] - name=MongoDB Repository - baseurl=https://repo.mongodb.org/yum/redhat/7/mongodb-org/4.0/x86_64/ - gpgcheck=1 - enabled=1 - gpgkey=https://www.mongodb.org/static/pgp/server-4.0.asc - EOT" - - sudo yum -y install crudini - sudo yum -y install mongodb-org - - curl -sL https://packagecloud.io/install/repositories/rabbitmq/erlang/script.rpm.sh | sudo bash - curl -sL https://packagecloud.io/install/repositories/rabbitmq/rabbitmq-server/script.rpm.sh | sudo bash - sudo yum makecache -y --disablerepo='*' --enablerepo='rabbitmq_rabbitmq-server' - sudo yum -y install erlang - sudo yum -y install rabbitmq-server - sudo yum -y install redis - sudo systemctl start mongod rabbitmq-server redis - sudo systemctl enable mongod rabbitmq-server redis - -The default python on CentOS/RHEL 7.x is python 2, |st2| uses python3 and requires the python3-devel package. The installation of the st2 package will automatically install python3-devel if it is available in an enabled repository. On CentOS distributions the relevant repository is typically enabled however on RHEL distributions it is provided by the rhel-7-server-optional-rpms repository (repository name dependant on RHEL distribution). - -The following steps in this section are only required on RHEL 7.x systems. On CentOS 7.x systems these steps can be ignored, and you can proceed to Setup Repositories. - -Use the following command to verify that the python3-devel package is available in an enabled repository: - -.. code-block:: bash - - sudo yum info python3-devel - -If it is not available, locate the repository that contains the RPM. On RHEL 7.x it is located in the optional server RPMs repository (the name of that repository differs between RHEL distributions): - -.. code-block:: bash - - sudo yum repolist disabled | grep optional | grep server - -Then either enable the optional repository using subscription-manager or yum-config-manager, or install python3-devel with a temporary repository enablement, e.g.: - -.. code-block:: bash - - sudo yum install python3-devel --enablerepo - -Setup Repositories -~~~~~~~~~~~~~~~~~~ - -The following script will detect your platform and architecture and setup the appropriate |st2| -repository. It will also add the the GPG key used for package signing. - -.. code-block:: bash - - curl -s https://packagecloud.io/install/repositories/StackStorm/stable/script.rpm.sh | sudo bash - -Install |st2| Components -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: bash - - sudo yum install -y st2 - -.. include:: common/configure_components.rst - -Setup Datastore Encryption -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: common/datastore_crypto_key.rst - -Configure SSH and SUDO -~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: common/configure_ssh_and_sudo.rst - -Start Services -~~~~~~~~~~~~~~ - -.. include:: common/start_services.rst - -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. - -To set up authentication with file-based provider: - -* Create a user with a password: - - .. code-block:: bash - - # Install htpasswd utility if you don't have it - sudo yum -y install httpd-tools - # Create a user record in a password file. - echo 'Ch@ngeMe' | sudo htpasswd -i /etc/st2/htpasswd st2admin - -.. 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 -``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 -`. - -|st2| depends on Nginx version >=1.7.5. RHEL has an older version in the package repositories, so -you will need to add the official Nginx repository: - -.. code-block:: bash - - # Add key and repo for the latest stable nginx - sudo rpm --import http://nginx.org/keys/nginx_signing.key - sudo sh -c "cat < /etc/yum.repos.d/nginx.repo - [nginx] - name=nginx repo - baseurl=http://nginx.org/packages/rhel/\\\$releasever/x86_64/ - gpgcheck=1 - enabled=1 - EOT" - - # Ensure that EPEL repo is not used for nginx - sudo sed -i 's/^\(enabled=1\)$/exclude=nginx\n\1/g' /etc/yum.repos.d/epel.repo - - # Install nginx - sudo yum install -y nginx - - # Install st2web - sudo yum install -y st2web - - # Generate a self-signed certificate or place your existing certificate under /etc/ssl/st2 - sudo mkdir -p /etc/ssl/st2 - sudo openssl req -x509 -newkey rsa:2048 -keyout /etc/ssl/st2/st2.key -out /etc/ssl/st2/st2.crt \ - -days 365 -nodes -subj "/C=US/ST=California/L=Palo Alto/O=StackStorm/OU=Information \ - Technology/CN=$(hostname)" - - # Copy and enable the supplied nginx config file - sudo cp /usr/share/doc/st2/conf/nginx/st2.conf /etc/nginx/conf.d/ - - # Disable default_server configuration in existing /etc/nginx/nginx.conf - sudo sed -i 's/default_server//g' /etc/nginx/nginx.conf - - sudo systemctl restart nginx - sudo systemctl enable nginx - -If you modify ports, or url paths in the nginx configuration, make the corresponding changes in -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: - -.. code-block:: bash - - firewall-cmd --zone=public --add-service=http --add-service=https - firewall-cmd --zone=public --permanent --add-service=http --add-service=https - -This will allow inbound HTTP (port 80) and HTTPS (port 443) traffic, and make those changes -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 -described below. Otherwise, the easiest way to enable :doc:`StackStorm ChatOps ` -is to use the `st2chatops `_ package. - -* Validate that the ``chatops`` pack is installed, and a notification rule is enabled: - - .. code-block:: bash - - # Ensure chatops pack is in place - ls /opt/stackstorm/packs/chatops - # 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 `_: - - .. code-block:: bash - - curl -sL https://rpm.nodesource.com/setup_14.x | sudo -E bash - - -* Install the ``st2chatops`` package: - - .. code-block:: bash - - sudo yum install -y st2chatops - -.. include:: common/configure_chatops.rst - -* Start the service: - - .. code-block:: bash - - sudo systemctl start st2chatops - - # Start st2chatops on boot - sudo systemctl enable st2chatops - -* Reload st2 packs to make sure the ``chatops.notify`` rule is registered: - - .. code-block:: bash - - sudo st2ctl reload --register-all - -* 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. -* Get more actions, triggers, rules: - - - * Install integration packs from `StackStorm Exchange `__ - follow the :doc:`/packs` guide. - * :ref:`Convert your scripts into StackStorm actions. ` - * Learn how to :ref:`write custom actions `. - -* Use workflows to stitch actions into higher level automations - :doc:`/workflows`. -* Check out `tutorials on stackstorm.com `__ From eebde5eab266e72e429bb713b896640d79af873c Mon Sep 17 00:00:00 2001 From: Carlos Date: Tue, 19 Nov 2024 18:08:28 +0100 Subject: [PATCH 43/67] Drop Ubuntu 18.04 installation --- docs/source/install/u18.rst | 252 ------------------------------------ 1 file changed, 252 deletions(-) delete mode 100644 docs/source/install/u18.rst diff --git a/docs/source/install/u18.rst b/docs/source/install/u18.rst deleted file mode 100644 index 7d2d310cb..000000000 --- a/docs/source/install/u18.rst +++ /dev/null @@ -1,252 +0,0 @@ -Ubuntu Bionic (18.04) -===================== - -.. include:: common/intro.rst - -.. contents:: Contents - :local: - -.. note:: - - |st2| on Ubuntu ``18.04`` runs all services, actions and sensors using Python 3 **only**. It - does not support Python2 actions. - -System Requirements -------------------- - -Please check the :doc:`supported versions and system requirements `. - -Minimal Installation --------------------- - -Install Dependencies -~~~~~~~~~~~~~~~~~~~~ - -Install MongoDB, RabbitMQ, and Redis: - -.. code-block:: bash - - sudo apt-get update - sudo apt-get install -y curl - - # 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 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 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 -``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 -`. - -.. code-block:: bash - - # Install st2web and nginx - sudo apt-get install -y st2web nginx - - # Generate self-signed certificate or place your existing certificate under /etc/ssl/st2 - sudo mkdir -p /etc/ssl/st2 - sudo openssl req -x509 -newkey rsa:2048 -keyout /etc/ssl/st2/st2.key -out /etc/ssl/st2/st2.crt \ - -days XXX -nodes -subj "/C=US/ST=California/L=Palo Alto/O=StackStorm/OU=Information \ - Technology/CN=$(hostname)" - - # 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 - 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/ - - sudo service nginx restart - -If you modify ports, or url paths in the nginx configuration, make the corresponding changes in -the st2web configuration at ``/opt/stackstorm/static/webui/config.js``. - -Use your browser to connect to ``https://${ST2_HOSTNAME}`` and login to the WebUI. - -.. include:: common/api_access.rst - -.. _ref-setup-chatops-deb: - -Setup ChatOps -------------- - -If you already run a Hubot instance, you can install the `hubot-stackstorm plugin -`_ and configure |st2| environment variables, as -described below. Otherwise, the easiest way to enable :doc:`StackStorm ChatOps ` -is to use the `st2chatops `_ package. - -* Validate that the ``chatops`` pack is installed, and a notification rule is enabled: - - .. code-block:: bash - - # Ensure chatops pack is in place - ls /opt/stackstorm/packs/chatops - # 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 `_: - - .. code-block:: bash - - curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash - - -* Install the ``st2chatops`` package: - - .. code-block:: bash - - sudo apt-get install -y st2chatops - -.. include:: common/configure_chatops.rst - -* Start the service: - - .. code-block:: bash - - sudo service st2chatops start - -* Reload st2 packs to make sure ``chatops.notify`` rule is registered: - - .. code-block:: bash - - sudo st2ctl reload --register-all - -* 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. -* Get more actions, triggers, rules: - - - * Install integration packs from `StackStorm Exchange `__ - follow the :doc:`/packs` guide. - * :ref:`Convert your scripts into StackStorm actions. ` - * Learn how to :ref:`write custom actions `. - -* Use workflows to stitch actions into higher level automations - :doc:`/workflows`. -* Check out `tutorials on stackstorm.com `__ From 354c4fda1780fbf5c59ccb8c848194cef0f303e6 Mon Sep 17 00:00:00 2001 From: Carlos Date: Tue, 19 Nov 2024 18:09:35 +0100 Subject: [PATCH 44/67] Update RHEL8 and Ubuntu 20.04 to install nodejs 20 for chatops. --- docs/source/install/rhel8.rst | 10 +++------- docs/source/install/u20.rst | 12 +++--------- 2 files changed, 6 insertions(+), 16 deletions(-) diff --git a/docs/source/install/rhel8.rst b/docs/source/install/rhel8.rst index d8cddad26..6382124b4 100644 --- a/docs/source/install/rhel8.rst +++ b/docs/source/install/rhel8.rst @@ -231,11 +231,12 @@ 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 + nvm install 20 * Install the ``st2chatops`` package: @@ -267,11 +268,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/u20.rst b/docs/source/install/u20.rst index feb51b1c7..09e3255fb 100644 --- a/docs/source/install/u20.rst +++ b/docs/source/install/u20.rst @@ -56,8 +56,6 @@ Install MongoDB, RabbitMQ, and Redis: deb-src [signed-by=/usr/share/keyrings/io.cloudsmith.dl.rabbitmq.gpg] https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/deb/ubuntu/ focal main EOF - sudo tee /etc/apt/preferences.d/erlang <`_ 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 + nvm install 20 * Install the ``st2chatops`` package: @@ -223,11 +222,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. From e09345acb4b03f9b859fe9dbe7ac928a7b1f6692 Mon Sep 17 00:00:00 2001 From: Carlos Date: Tue, 19 Nov 2024 18:10:22 +0100 Subject: [PATCH 45/67] Update system requirements for Ubuntu 20.04/22.04 and RHEL8/9 --- docs/source/install/system_requirements.rst | 39 +++++++++------------ 1 file changed, 17 insertions(+), 22 deletions(-) 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. From 6ebf321d0bd09f45a9ae8e6dab5bfe4f22c9ceae Mon Sep 17 00:00:00 2001 From: Carlos Date: Tue, 19 Nov 2024 18:11:05 +0100 Subject: [PATCH 46/67] Update developer installation documenation --- docs/source/development/sources.rst | 296 ++++++++++++++++++++++++---- 1 file changed, 253 insertions(+), 43 deletions(-) diff --git a/docs/source/development/sources.rst b/docs/source/development/sources.rst index 7d436654b..1e48ddd7a 100644 --- a/docs/source/development/sources.rst +++ b/docs/source/development/sources.rst @@ -1,68 +1,278 @@ :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 ------- +------------------------------------------------------------------------ + +Install required packages for python development. + +.. code-block:: bash + + apt-get install python3-pip python3-venv gcc git make tmux libffi-dev libssl-dev python3-dev libldap2-dev libsasl2-dev + + +Install a supported version of MongoDB. .. note:: - For Ubuntu 20.04 replace with python3.8 equivalents + Mongo provides packages for Ubuntu 22.04 LTS ("Jammy") starting from MongoDB 6.0.4. Adapt installation instructions according. + +.. code-block:: bash + apt-get install gnupg curl + curl -fsSL https://www.mongodb.org/static/pgp/server-4.4.asc | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/mongodb-server-4.4.gpg + sudo chmod 644 /etc/apt/trusted.gpg.d/mongodb-server-4.4.gpg + + export VERSION_CODENAME=$(source /etc/os-release; echo $VERSION_CODENAME) + export DISTRO_ID=$(source /etc/os-release; echo $ID) + sudo cat </etc/apt/sources.list.d/mongodb-org-4.4.list + deb [ arch=amd64 ] https://repo.mongodb.org/apt/${DISTRO_ID} ${VERSION_CODENAME}/mongodb-org/4.4 multiverse + EOF + cat /etc/apt/sources.list.d/mongodb-org-4.4.list + + sudo apt update + sudo apt-get install -y mongodb-org-server mongodb-org-shell mongodb-org-tools + +Install a supported version of RabbitMQ / Erlang .. 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 + # configure repository + # install package -RockyLinux/CentOS/RHEL ----------------------- +Install a supported version of Redis + +.. code-block:: bash + + apt-get install gnupg curl + curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/redis-archive-keyring.gpg + sudo chmod 644 /etc/apt/trusted.gpg.d/redis-archive-keyring.gpg + export VERSION_CODENAME=$(source /etc/os-release; echo $VERSION_CODENAME) + sudo cat </etc/apt/sources.list.d/redis.list + deb [ arch=amd64 ] https://packages.redis.io/deb $VERSION_CODENAME main + EOF + cat /etc/apt/sources.list.d/redis.list + sudo apt-get update + sudo apt-get install redis-stack-server + + systemctl enable redis-stack-server + systemctl start redis-stack-server -.. note:: - For RHEL 7.x you may need to enable the optional server rpms repository to be able to install the python3-devel RPM +RockyLinux/RHEL +------------------------------------------------------------------------ .. 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:: + + 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 and tmux is the recommended replacement. + + +Install a supported version of MongoDB. - # 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" +.. code-block:: bash + +OSRELEASE_VERSION=$(source /etc/os-release; echo ${VERSION_ID%.*}) +cat </etc/yum.repos.d/mongodb-org-4.4.repo +[mongodb-org-4.4] +name=MongoDB Repository +baseurl=https://repo.mongodb.org/yum/redhat/${OSRELEASE_VERSION}/mongodb-org/4.4/x86_64/ +gpgcheck=1 +enabled=1 +gpgkey=https://pgp.mongodb.com/server-4.4.asc +EOF yum install crudini - yum install mongodb-org - yum install rabbitmq-server - systemctl start mongod rabbitmq-server - systemctl enable mongod rabbitmq-server + systemctl start mongod + systemctl enable mongod + +Install a supported version of RabbitMQ / Erlang + +.. code-block:: bash + + rpm --import 'https://github.com/rabbitmq/signing-keys/releases/download/3.0/rabbitmq-release-signing-key.asc' + rpm --import 'https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-erlang.E495BB49CC4BBE5B.key' + rpm --import 'https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-server.9F4587F226208342.key' + + cat </etc/yum.repos.d/rabbitmq.repo + ## + ## Zero dependency Erlang RPM + ## + + [modern-erlang] + name=modern-erlang-el9 + # uses a Cloudsmith mirror @ yum.novemberain.com. + # Unlike Cloudsmith, it does not have any traffic quotas + baseurl=https://yum1.novemberain.com/erlang/el/9/\$basearch + https://yum2.novemberain.com/erlang/el/9/\$basearch + https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/rpm/el/9/\$basearch + repo_gpgcheck=1 + enabled=1 + gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-erlang.E495BB49CC4BBE5B.key + gpgcheck=1 + sslverify=1 + sslcacert=/etc/pki/tls/certs/ca-bundle.crt + metadata_expire=300 + pkg_gpgcheck=1 + autorefresh=1 + type=rpm-md + + [modern-erlang-noarch] + name=modern-erlang-el9-noarch + # uses a Cloudsmith mirror @ yum.novemberain.com. + # Unlike Cloudsmith, it does not have any traffic quotas + baseurl=https://yum1.novemberain.com/erlang/el/9/noarch + https://yum2.novemberain.com/erlang/el/9/noarch + https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/rpm/el/9/noarch + repo_gpgcheck=1 + enabled=1 + gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-erlang.E495BB49CC4BBE5B.key + https://github.com/rabbitmq/signing-keys/releases/download/3.0/rabbitmq-release-signing-key.asc + gpgcheck=1 + sslverify=1 + sslcacert=/etc/pki/tls/certs/ca-bundle.crt + metadata_expire=300 + pkg_gpgcheck=1 + autorefresh=1 + type=rpm-md + + [modern-erlang-source] + name=modern-erlang-el9-source + # uses a Cloudsmith mirror @ yum.novemberain.com. + # Unlike Cloudsmith, it does not have any traffic quotas + baseurl=https://yum1.novemberain.com/erlang/el/9/SRPMS + https://yum2.novemberain.com/erlang/el/9/SRPMS + https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/rpm/el/9/SRPMS + repo_gpgcheck=1 + enabled=1 + gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-erlang.E495BB49CC4BBE5B.key + https://github.com/rabbitmq/signing-keys/releases/download/3.0/rabbitmq-release-signing-key.asc + gpgcheck=1 + sslverify=1 + sslcacert=/etc/pki/tls/certs/ca-bundle.crt + metadata_expire=300 + pkg_gpgcheck=1 + autorefresh=1 + + + ## + ## RabbitMQ Server + ## + + [rabbitmq-el9] + name=rabbitmq-el9 + baseurl=https://yum2.novemberain.com/rabbitmq/el/9/\$basearch + https://yum1.novemberain.com/rabbitmq/el/9/\$basearch + https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/rpm/el/9/\$basearch + repo_gpgcheck=1 + enabled=1 + # Cloudsmith's repository key and RabbitMQ package signing key + gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-server.9F4587F226208342.key + https://github.com/rabbitmq/signing-keys/releases/download/3.0/rabbitmq-release-signing-key.asc + gpgcheck=1 + sslverify=1 + sslcacert=/etc/pki/tls/certs/ca-bundle.crt + metadata_expire=300 + pkg_gpgcheck=1 + autorefresh=1 + type=rpm-md + + [rabbitmq-el9-noarch] + name=rabbitmq-el9-noarch + baseurl=https://yum2.novemberain.com/rabbitmq/el/9/noarch + https://yum1.novemberain.com/rabbitmq/el/9/noarch + https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/rpm/el/9/noarch + repo_gpgcheck=1 + enabled=1 + # Cloudsmith's repository key and RabbitMQ package signing key + gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-server.9F4587F226208342.key + https://github.com/rabbitmq/signing-keys/releases/download/3.0/rabbitmq-release-signing-key.asc + gpgcheck=1 + sslverify=1 + sslcacert=/etc/pki/tls/certs/ca-bundle.crt + metadata_expire=300 + pkg_gpgcheck=1 + autorefresh=1 + type=rpm-md + + [rabbitmq-el9-source] + name=rabbitmq-el9-source + baseurl=https://yum2.novemberain.com/rabbitmq/el/9/SRPMS + https://yum1.novemberain.com/rabbitmq/el/9/SRPMS + https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/rpm/el/9/SRPMS + repo_gpgcheck=1 + enabled=1 + gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-server.9F4587F226208342.key + gpgcheck=0 + sslverify=1 + sslcacert=/etc/pki/tls/certs/ca-bundle.crt + metadata_expire=300 + pkg_gpgcheck=1 + autorefresh=1 + type=rpm-md + EOF + cat /etc/yum.repos.d/rabbitmq.repo + + dnf update -y + + dnf install socat logrotate -y + dnf install -y erlang rabbitmq-server + + systemctl start rabbitmq-server + systemctl enable rabbitmq-server + + +Install a supported version of Redis + +.. code-block:: bash + + cat </etc/yum.repos.d/redis.repo + [Redis] + name=Redis + baseurl=http://packages.redis.io/rpm/rhel7 + enabled=1 + gpgcheck=1 + EOF + + curl -fsSL https://packages.redis.io/gpg > /tmp/redis.key + sudo rpm --import /tmp/redis.key + sudo yum install epel-release + sudo yum install redis-stack-server + + systemctl enable redis-stack-server + systemctl start redis-stack-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 +288,7 @@ tests: make requirements Configure System User -~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Create a system user for executing SSH actions: @@ -89,7 +299,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 +309,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: @@ -152,7 +362,7 @@ output: .. _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 +373,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 +385,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 +398,7 @@ Additional Makefile targets Install |st2| Web UI -~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Installing the st2 Web UI. @@ -210,7 +420,7 @@ Installing the st2 Web UI. Default Credentials to Login -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -218,7 +428,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: From cb8070167fd6558638274676b911e6400c47a382 Mon Sep 17 00:00:00 2001 From: Carlos Date: Tue, 19 Nov 2024 18:11:35 +0100 Subject: [PATCH 47/67] Update distribution references --- docs/source/install/index.rst | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/source/install/index.rst b/docs/source/install/index.rst index 94507d34e..aeebf0863 100644 --- a/docs/source/install/index.rst +++ b/docs/source/install/index.rst @@ -12,7 +12,7 @@ single system, or you can follow the manual instructions for your OS. 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 + 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: @@ -22,8 +22,8 @@ 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. @@ -79,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 @@ -94,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 From d3e6ee1af8b9916ead2eaac44cc86f8eaab93ca9 Mon Sep 17 00:00:00 2001 From: Carlos Date: Tue, 19 Nov 2024 18:22:19 +0100 Subject: [PATCH 48/67] Bump documentation build to use python 3.10 --- .circleci/config.yml | 2 +- .readthedocs.yaml | 4 ++-- Makefile | 2 +- docs/source/conf.py | 2 +- requirements.txt | 10 +++++----- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 3d012d337..dca5ba056 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: diff --git a/.readthedocs.yaml b/.readthedocs.yaml index a64c6e8d5..fcd293878 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -14,10 +14,10 @@ python: # Set the version of Python and other tools, and customize the build process build: - os: ubuntu-20.04 + os: ubuntu-22.04 tools: # python: "3.6" - python: "3.8" + python: "3.10" apt_packages: - python3-dev - libldap2-dev diff --git a/Makefile b/Makefile index 708dda962..83c978386 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*) diff --git a/docs/source/conf.py b/docs/source/conf.py index 2a97a135a..bf786bf0f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -440,6 +440,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 = {'https://docs.python.org/2': None} autoclass_content = 'both' diff --git a/requirements.txt b/requirements.txt index 57410f63b..8190cd243 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,6 @@ -docutils==0.16.0 -sphinx>=2.4.4,<3.0 +docutils==0.21.2 +sphinx==8.1.3 sphinx-autobuild -sphinx-sitemap==2.2.0 -sphinx-rtd-theme==1.0.0 -jinja2<3.1 +sphinx-sitemap==2.6.0 +sphinx-rtd-theme==3.0.2 +jinja2 From 49e1037328d528dd56ad928bfd20d2ba795c8926 Mon Sep 17 00:00:00 2001 From: Carlos Date: Fri, 22 Nov 2024 07:53:48 +0100 Subject: [PATCH 49/67] Condense developer pack installation steps. --- .circleci/config.yml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index dca5ba056..32e28f4f4 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -12,10 +12,11 @@ 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: | + sudo apt-get update + sudo apt install python3-dev libldap2-dev libsasl2-dev - run: make docs - run: name: Store HTML docs in workspace dir From f44fa09eae6ca1744077dfe56331fc94c6300f70 Mon Sep 17 00:00:00 2001 From: Carlos Date: Fri, 22 Nov 2024 07:56:21 +0100 Subject: [PATCH 50/67] Relax constraints on shinx extensions --- requirements.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/requirements.txt b/requirements.txt index 8190cd243..0a7e68343 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,6 @@ docutils==0.21.2 sphinx==8.1.3 sphinx-autobuild -sphinx-sitemap==2.6.0 -sphinx-rtd-theme==3.0.2 +sphinx-sitemap +sphinx-rtd-theme jinja2 From bbe36271a027041aa01493874c2930f42307d162 Mon Sep 17 00:00:00 2001 From: Carlos Date: Fri, 22 Nov 2024 07:57:00 +0100 Subject: [PATCH 51/67] Add missing HA references from u18 to u22 --- docs/source/install/u22.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/source/install/u22.rst b/docs/source/install/u22.rst index 3f1f8b5d1..2a4968c20 100644 --- a/docs/source/install/u22.rst +++ b/docs/source/install/u22.rst @@ -100,6 +100,8 @@ Verify .. include:: common/verify.rst +.. _ref-config-auth-deb: + Configure Authentication ------------------------ @@ -119,6 +121,8 @@ To set up authentication with file-based provider: .. include:: common/configure_authentication.rst +.. _ref-install-webui-ssl-deb: + Install WebUI and Setup SSL Termination --------------------------------------- @@ -155,6 +159,8 @@ Use your browser to connect to ``https://${ST2_HOSTNAME}`` and login to the WebU .. include:: common/api_access.rst +.. _ref-setup-chatops-deb: + Setup ChatOps ------------- From 160e2a0e86723e5329014dd47dc8c2eae1f3e7d1 Mon Sep 17 00:00:00 2001 From: Carlos Date: Fri, 22 Nov 2024 08:22:00 +0100 Subject: [PATCH 52/67] Black formatting --- docs/source/_themes/sphinx_rtd_theme/__init__.py | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) 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" From b45d5cf55bb523409bd87350bef26f2e5f05eb91 Mon Sep 17 00:00:00 2001 From: Carlos Date: Fri, 22 Nov 2024 08:22:42 +0100 Subject: [PATCH 53/67] Fix list indentation --- docs/source/development/sources.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/development/sources.rst b/docs/source/development/sources.rst index 1e48ddd7a..8ace5980a 100644 --- a/docs/source/development/sources.rst +++ b/docs/source/development/sources.rst @@ -15,11 +15,11 @@ Requirements: - python3.10 for Ubuntu 22.04 - pip, virtualenv, tox - 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/) + - 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) + - 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 From 4368a666aa8e70e6af8d3c0077adf03b4ea244f2 Mon Sep 17 00:00:00 2001 From: Carlos Date: Fri, 22 Nov 2024 08:25:35 +0100 Subject: [PATCH 54/67] Black formatting, disabled site version and temporarily disabled sitemap generation. --- docs/source/conf.py | 177 ++++++++++++++++++++++++++------------------ 1 file changed, 106 insertions(+), 71 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index bf786bf0f..a7dca33a7 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -19,13 +19,13 @@ 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) @@ -45,25 +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', - + "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", +# "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' @@ -79,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.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'] +release_versions = [ + "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): @@ -100,6 +131,7 @@ 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) @@ -107,29 +139,30 @@ def previous_version(ver): # 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 @@ -148,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 @@ -172,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 = [] @@ -187,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 ---------------------------------------------- @@ -206,7 +240,7 @@ def previous_version(ver): # "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, +# "display_version": False, # invalid theme, commented out. "style_external_links": True, "vcs_pageview_mode": "blob", # blob, edit, raw } @@ -261,13 +295,13 @@ def previous_version(ver): # 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. @@ -320,8 +354,8 @@ def previous_version(ver): "github_user": info.github_user, "github_repo": info.github_repo, "github_version": info.github_version, - 'conf_py_path': '/docs/source/', - 'source_suffix': source_suffix, + "conf_py_path": "/docs/source/", + "source_suffix": source_suffix, } if "READTHEDOCS" not in os.environ: @@ -330,46 +364,47 @@ def previous_version(ver): 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)) + 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)), - ]) + 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 + 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 @@ -440,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" From 77269f41c5eeaa5628b219ae12f3d36e1ceb35da Mon Sep 17 00:00:00 2001 From: Carlos Date: Fri, 22 Nov 2024 22:41:34 +0100 Subject: [PATCH 55/67] Pin sphinx-sitemap to <=2.3.0 and re-enable sitemap creation. --- .readthedocs.yaml | 1 - docs/source/conf.py | 2 +- requirements.txt | 3 ++- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index fcd293878..268d5b789 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -16,7 +16,6 @@ python: build: os: ubuntu-22.04 tools: - # python: "3.6" python: "3.10" apt_packages: - python3-dev diff --git a/docs/source/conf.py b/docs/source/conf.py index a7dca33a7..907306f81 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -55,7 +55,7 @@ # theme is provided as an extension "sphinx_rtd_theme", # this generates sitemap.xml -# "sphinx_sitemap", + "sphinx_sitemap", ] # Add any paths that contain templates here, relative to this directory. diff --git a/requirements.txt b/requirements.txt index 0a7e68343..4a1c0fac0 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,7 @@ docutils==0.21.2 sphinx==8.1.3 sphinx-autobuild -sphinx-sitemap +# 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 From ea498c9f9a31ba7fb14b9faf30a3ebd88e786a06 Mon Sep 17 00:00:00 2001 From: Carlos Date: Fri, 22 Nov 2024 22:42:19 +0100 Subject: [PATCH 56/67] Make packages to be installed a list for better readability. --- .circleci/config.yml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 32e28f4f4..4178db360 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -15,8 +15,13 @@ jobs: - run: name: Install developer packages command: | + PKGS=( + python3-dev + libldap2-dev + libsasl2-dev + ) sudo apt-get update - sudo apt install python3-dev libldap2-dev libsasl2-dev + sudo apt install ${PKGS[@]} - run: make docs - run: name: Store HTML docs in workspace dir From 68ee1c5c71bfe2d3a1bb0126a2f464ca2510e4cb Mon Sep 17 00:00:00 2001 From: Carlos Date: Mon, 2 Dec 2024 19:22:15 +0100 Subject: [PATCH 57/67] Mongo 7.0 documentation --- docs/source/development/sources.rst | 282 ++++------------------------ docs/source/install/rhel8.rst | 24 ++- docs/source/install/rhel9.rst | 28 ++- docs/source/install/u20.rst | 47 ++--- docs/source/install/u22.rst | 1 + 5 files changed, 83 insertions(+), 299 deletions(-) diff --git a/docs/source/development/sources.rst b/docs/source/development/sources.rst index 8ace5980a..7ea8a4994 100644 --- a/docs/source/development/sources.rst +++ b/docs/source/development/sources.rst @@ -33,54 +33,13 @@ Install required packages for python development. apt-get install python3-pip python3-venv gcc git make tmux libffi-dev libssl-dev python3-dev libldap2-dev libsasl2-dev -Install a supported version of MongoDB. +Install a supported version of MongoDB, RabbitMQ / Erlang and Redis. -.. note:: - Mongo provides packages for Ubuntu 22.04 LTS ("Jammy") starting from MongoDB 6.0.4. Adapt installation instructions according. - -.. code-block:: bash - - apt-get install gnupg curl - curl -fsSL https://www.mongodb.org/static/pgp/server-4.4.asc | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/mongodb-server-4.4.gpg - sudo chmod 644 /etc/apt/trusted.gpg.d/mongodb-server-4.4.gpg - - export VERSION_CODENAME=$(source /etc/os-release; echo $VERSION_CODENAME) - export DISTRO_ID=$(source /etc/os-release; echo $ID) - sudo cat </etc/apt/sources.list.d/mongodb-org-4.4.list - deb [ arch=amd64 ] https://repo.mongodb.org/apt/${DISTRO_ID} ${VERSION_CODENAME}/mongodb-org/4.4 multiverse - EOF - cat /etc/apt/sources.list.d/mongodb-org-4.4.list - - sudo apt update - sudo apt-get install -y mongodb-org-server mongodb-org-shell mongodb-org-tools - -Install a supported version of RabbitMQ / Erlang - -.. code-block:: bash - - # configure repository - # install package - -Install a supported version of Redis - -.. code-block:: bash - - apt-get install gnupg curl - curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/redis-archive-keyring.gpg - sudo chmod 644 /etc/apt/trusted.gpg.d/redis-archive-keyring.gpg - export VERSION_CODENAME=$(source /etc/os-release; echo $VERSION_CODENAME) - sudo cat </etc/apt/sources.list.d/redis.list - deb [ arch=amd64 ] https://packages.redis.io/deb $VERSION_CODENAME main - EOF - cat /etc/apt/sources.list.d/redis.list - sudo apt-get update - sudo apt-get install redis-stack-server - - systemctl enable redis-stack-server - systemctl start redis-stack-server +`Ubuntu 20.04 Focal ` +`Ubuntu 22.04 Jammy ` -RockyLinux/RHEL +Rocky Linux / RedHat Enterprise Linux ------------------------------------------------------------------------ .. code-block:: bash @@ -93,182 +52,13 @@ RockyLinux/RHEL .. note:: 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 and tmux is the recommended replacement. + screen has been removed from Rocky9 so developer tooling uses tmux instead. -Install a supported version of MongoDB. +Install a supported version of MongoDB, RabbitMQ / Erlang and Redis. -.. code-block:: bash - -OSRELEASE_VERSION=$(source /etc/os-release; echo ${VERSION_ID%.*}) -cat </etc/yum.repos.d/mongodb-org-4.4.repo -[mongodb-org-4.4] -name=MongoDB Repository -baseurl=https://repo.mongodb.org/yum/redhat/${OSRELEASE_VERSION}/mongodb-org/4.4/x86_64/ -gpgcheck=1 -enabled=1 -gpgkey=https://pgp.mongodb.com/server-4.4.asc -EOF - - yum install crudini - systemctl start mongod - systemctl enable mongod - -Install a supported version of RabbitMQ / Erlang - -.. code-block:: bash - - rpm --import 'https://github.com/rabbitmq/signing-keys/releases/download/3.0/rabbitmq-release-signing-key.asc' - rpm --import 'https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-erlang.E495BB49CC4BBE5B.key' - rpm --import 'https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-server.9F4587F226208342.key' - - cat </etc/yum.repos.d/rabbitmq.repo - ## - ## Zero dependency Erlang RPM - ## - - [modern-erlang] - name=modern-erlang-el9 - # uses a Cloudsmith mirror @ yum.novemberain.com. - # Unlike Cloudsmith, it does not have any traffic quotas - baseurl=https://yum1.novemberain.com/erlang/el/9/\$basearch - https://yum2.novemberain.com/erlang/el/9/\$basearch - https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/rpm/el/9/\$basearch - repo_gpgcheck=1 - enabled=1 - gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-erlang.E495BB49CC4BBE5B.key - gpgcheck=1 - sslverify=1 - sslcacert=/etc/pki/tls/certs/ca-bundle.crt - metadata_expire=300 - pkg_gpgcheck=1 - autorefresh=1 - type=rpm-md - - [modern-erlang-noarch] - name=modern-erlang-el9-noarch - # uses a Cloudsmith mirror @ yum.novemberain.com. - # Unlike Cloudsmith, it does not have any traffic quotas - baseurl=https://yum1.novemberain.com/erlang/el/9/noarch - https://yum2.novemberain.com/erlang/el/9/noarch - https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/rpm/el/9/noarch - repo_gpgcheck=1 - enabled=1 - gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-erlang.E495BB49CC4BBE5B.key - https://github.com/rabbitmq/signing-keys/releases/download/3.0/rabbitmq-release-signing-key.asc - gpgcheck=1 - sslverify=1 - sslcacert=/etc/pki/tls/certs/ca-bundle.crt - metadata_expire=300 - pkg_gpgcheck=1 - autorefresh=1 - type=rpm-md - - [modern-erlang-source] - name=modern-erlang-el9-source - # uses a Cloudsmith mirror @ yum.novemberain.com. - # Unlike Cloudsmith, it does not have any traffic quotas - baseurl=https://yum1.novemberain.com/erlang/el/9/SRPMS - https://yum2.novemberain.com/erlang/el/9/SRPMS - https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-erlang/rpm/el/9/SRPMS - repo_gpgcheck=1 - enabled=1 - gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-erlang.E495BB49CC4BBE5B.key - https://github.com/rabbitmq/signing-keys/releases/download/3.0/rabbitmq-release-signing-key.asc - gpgcheck=1 - sslverify=1 - sslcacert=/etc/pki/tls/certs/ca-bundle.crt - metadata_expire=300 - pkg_gpgcheck=1 - autorefresh=1 - - - ## - ## RabbitMQ Server - ## - - [rabbitmq-el9] - name=rabbitmq-el9 - baseurl=https://yum2.novemberain.com/rabbitmq/el/9/\$basearch - https://yum1.novemberain.com/rabbitmq/el/9/\$basearch - https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/rpm/el/9/\$basearch - repo_gpgcheck=1 - enabled=1 - # Cloudsmith's repository key and RabbitMQ package signing key - gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-server.9F4587F226208342.key - https://github.com/rabbitmq/signing-keys/releases/download/3.0/rabbitmq-release-signing-key.asc - gpgcheck=1 - sslverify=1 - sslcacert=/etc/pki/tls/certs/ca-bundle.crt - metadata_expire=300 - pkg_gpgcheck=1 - autorefresh=1 - type=rpm-md - - [rabbitmq-el9-noarch] - name=rabbitmq-el9-noarch - baseurl=https://yum2.novemberain.com/rabbitmq/el/9/noarch - https://yum1.novemberain.com/rabbitmq/el/9/noarch - https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/rpm/el/9/noarch - repo_gpgcheck=1 - enabled=1 - # Cloudsmith's repository key and RabbitMQ package signing key - gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-server.9F4587F226208342.key - https://github.com/rabbitmq/signing-keys/releases/download/3.0/rabbitmq-release-signing-key.asc - gpgcheck=1 - sslverify=1 - sslcacert=/etc/pki/tls/certs/ca-bundle.crt - metadata_expire=300 - pkg_gpgcheck=1 - autorefresh=1 - type=rpm-md - - [rabbitmq-el9-source] - name=rabbitmq-el9-source - baseurl=https://yum2.novemberain.com/rabbitmq/el/9/SRPMS - https://yum1.novemberain.com/rabbitmq/el/9/SRPMS - https://dl.cloudsmith.io/public/rabbitmq/rabbitmq-server/rpm/el/9/SRPMS - repo_gpgcheck=1 - enabled=1 - gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-server.9F4587F226208342.key - gpgcheck=0 - sslverify=1 - sslcacert=/etc/pki/tls/certs/ca-bundle.crt - metadata_expire=300 - pkg_gpgcheck=1 - autorefresh=1 - type=rpm-md - EOF - cat /etc/yum.repos.d/rabbitmq.repo - - dnf update -y - - dnf install socat logrotate -y - dnf install -y erlang rabbitmq-server - - systemctl start rabbitmq-server - systemctl enable rabbitmq-server - - -Install a supported version of Redis - -.. code-block:: bash - - cat </etc/yum.repos.d/redis.repo - [Redis] - name=Redis - baseurl=http://packages.redis.io/rpm/rhel7 - enabled=1 - gpgcheck=1 - EOF - - curl -fsSL https://packages.redis.io/gpg > /tmp/redis.key - sudo rpm --import /tmp/redis.key - sudo yum install epel-release - sudo yum install redis-stack-server - - systemctl enable redis-stack-server - systemctl start redis-stack-server +`Red Hat Enterprise Linux 8 and compatible distributions ` +`Red Hat Enterprise Linux 9 and compatible distributions ` Project Requirements @@ -323,39 +113,47 @@ 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: - -.. 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... - ... +If the services are started successfully, you will see the following output: + +.. code-block:: bash + + ./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. diff --git a/docs/source/install/rhel8.rst b/docs/source/install/rhel8.rst index 6382124b4..52f107777 100644 --- a/docs/source/install/rhel8.rst +++ b/docs/source/install/rhel8.rst @@ -65,27 +65,24 @@ 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 <`_ package. .. code-block:: 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: diff --git a/docs/source/install/rhel9.rst b/docs/source/install/rhel9.rst index b2fd439ca..8fb562861 100644 --- a/docs/source/install/rhel9.rst +++ b/docs/source/install/rhel9.rst @@ -57,29 +57,26 @@ Install MongoDB, RabbitMQ, and Redis: .. code-block:: bash - sudo yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.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 <`_ package. .. code-block:: 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: diff --git a/docs/source/install/u20.rst b/docs/source/install/u20.rst index 09e3255fb..85b86581f 100644 --- a/docs/source/install/u20.rst +++ b/docs/source/install/u20.rst @@ -27,39 +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. .. code-block:: 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: diff --git a/docs/source/install/u22.rst b/docs/source/install/u22.rst index 2a4968c20..608e1c29a 100644 --- a/docs/source/install/u22.rst +++ b/docs/source/install/u22.rst @@ -183,6 +183,7 @@ is to use the `st2chatops `_ package. .. code-block:: 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: From cd86a6c25d8823e6b9b1c0b464712c41053984ef Mon Sep 17 00:00:00 2001 From: Jacob Zufelt Date: Wed, 9 Apr 2025 10:11:22 -0600 Subject: [PATCH 58/67] st2chatops docs updates --- Dockerfile | 4 +-- Makefile | 2 +- docs/source/chatops/aliases.rst | 20 ++++++++++++ docs/source/chatops/chatops.rst | 54 ++++++++++++++------------------- docs/source/chatops/index.rst | 2 +- docs/source/chatops/msteams.rst | 4 +++ 6 files changed, 50 insertions(+), 36 deletions(-) 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 83c978386..0aac133a2 100644 --- a/Makefile +++ b/Makefile @@ -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/chatops/aliases.rst b/docs/source/chatops/aliases.rst index a94293e9f..010c0eb79 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..fc339cc1c 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,7 +76,7 @@ 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. @@ -94,27 +86,25 @@ 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 +134,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: 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. From 87a8873ecddf238979fe8ae64257441588993f97 Mon Sep 17 00:00:00 2001 From: Jacob Zufelt Date: Wed, 9 Apr 2025 10:23:12 -0600 Subject: [PATCH 59/67] Remove reference to centos --- docs/source/chatops/chatops.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/chatops/chatops.rst b/docs/source/chatops/chatops.rst index fc339cc1c..b416da11c 100644 --- a/docs/source/chatops/chatops.rst +++ b/docs/source/chatops/chatops.rst @@ -251,5 +251,5 @@ 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 +systemd-based distros (Ubuntu 18/20, RHEL/RockyLinux8+), you can access the logs via ``journalctl --unit=st2chatops`` From 3170f762f5adca7f38f24c4d4897c815ef39e9db Mon Sep 17 00:00:00 2001 From: Jacob Zufelt Date: Fri, 6 Jun 2025 12:51:05 -0600 Subject: [PATCH 60/67] Few fixes to chatops docs --- docs/source/chatops/aliases.rst | 2 +- docs/source/chatops/chatops.rst | 5 +++-- docs/source/install/common/configure_chatops.rst | 13 ++----------- 3 files changed, 6 insertions(+), 14 deletions(-) diff --git a/docs/source/chatops/aliases.rst b/docs/source/chatops/aliases.rst index 010c0eb79..8e507c05d 100644 --- a/docs/source/chatops/aliases.rst +++ b/docs/source/chatops/aliases.rst @@ -374,7 +374,7 @@ 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. diff --git a/docs/source/chatops/chatops.rst b/docs/source/chatops/chatops.rst index b416da11c..73a48f0dd 100644 --- a/docs/source/chatops/chatops.rst +++ b/docs/source/chatops/chatops.rst @@ -78,8 +78,9 @@ installed, and StackStorm :ref:`API keys ` have been con 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: 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 From 8271bfd4534e24f57878bb5d931c879c4a563bb4 Mon Sep 17 00:00:00 2001 From: NitinNahal Date: Thu, 10 Jul 2025 12:57:04 +0000 Subject: [PATCH 61/67] Fix: st2-run-pack-tests examples - With migration from nosetest to pytest, st2-run-pack-tests examples should be modified. Signed-off-by: NitinNahal --- docs/source/development/pack_testing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 From e966682db969a415b19fd2b86f958f4cca872e9a Mon Sep 17 00:00:00 2001 From: Carlos Date: Mon, 28 Apr 2025 08:58:44 +0200 Subject: [PATCH 62/67] Upgrade notes for v3.9 --- docs/source/chatops/chatops.rst | 3 +-- docs/source/install/uninstall.rst | 4 +-- docs/source/roadmap.rst | 19 ++++++++++--- docs/source/upgrade_notes.rst | 45 +++++++++++++++++++++++++------ 4 files changed, 55 insertions(+), 16 deletions(-) diff --git a/docs/source/chatops/chatops.rst b/docs/source/chatops/chatops.rst index 73a48f0dd..6d544855b 100644 --- a/docs/source/chatops/chatops.rst +++ b/docs/source/chatops/chatops.rst @@ -252,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/RockyLinux8+), 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/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/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/upgrade_notes.rst b/docs/source/upgrade_notes.rst index b41ed12b2..6a4839e2b 100644 --- a/docs/source/upgrade_notes.rst +++ b/docs/source/upgrade_notes.rst @@ -3,6 +3,35 @@ 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) + + .. _ref-upgrade-notes-v3-8: |st2| v3.8 @@ -53,7 +82,7 @@ Upgrade Notes * 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. + 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. @@ -102,7 +131,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: @@ -156,10 +185,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, @@ -288,11 +317,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: @@ -405,7 +434,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. From 6d1f997ac82c8e8b6d83a640bb3e03d567194377 Mon Sep 17 00:00:00 2001 From: Stanley CI Bot Date: Fri, 10 Oct 2025 06:20:59 +0000 Subject: [PATCH 63/67] Update version info for release - 3.9.0 --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 907306f81..c15bcf273 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -82,7 +82,7 @@ # The full version, including alpha/beta/rc tags. release = __version__ # The complete list of current StackStorm versions. -release_versions = [ +release_versions = ['3.9', "3.8", "3.7", "3.6", From 87e39c0aaaa04df999f4414cc24d4d0da10f83f9 Mon Sep 17 00:00:00 2001 From: Stanley CI Bot Date: Thu, 23 Oct 2025 05:40:51 +0000 Subject: [PATCH 64/67] Test Stanley Bot From 782d7110e5363b439951cd8e7f4b90ab704ecd65 Mon Sep 17 00:00:00 2001 From: NitinNahal Date: Mon, 3 Nov 2025 14:34:37 +0000 Subject: [PATCH 65/67] Key-value pairs trigger example - Include example demonstrating a rule to use key-value based internal trigger resulting into an action Signed-off-by: NitinNahal --- docs/source/sensors.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) 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 ----------------- From 5b630ad1f1ebcfc26f615b629d48e5f8b79a2d97 Mon Sep 17 00:00:00 2001 From: Stanley CI Bot Date: Mon, 12 Jan 2026 06:32:58 +0000 Subject: [PATCH 66/67] Update version to 3.10dev --- version.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/version.txt b/version.txt index 83c5bc505..f4a91a70c 100644 --- a/version.txt +++ b/version.txt @@ -1 +1 @@ -3.9dev +3.10dev From d24522d49e436f8aebeda1a73a015294e73f4475 Mon Sep 17 00:00:00 2001 From: Carlos Date: Wed, 14 Jan 2026 18:41:04 +0100 Subject: [PATCH 67/67] Update release notes for YAQL format removal --- docs/source/install/rhel8.rst | 38 ++++++++++++--------------- docs/source/upgrade_notes.rst | 48 ++++++++++++++++++++++++++++++++--- 2 files changed, 60 insertions(+), 26 deletions(-) diff --git a/docs/source/install/rhel8.rst b/docs/source/install/rhel8.rst index 52f107777..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 @@ -86,7 +80,7 @@ Install MongoDB, RabbitMQ, and Redis: Setup Repositories -~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following script will detect your platform and architecture and setup the appropriate |st2| repository. It will also add the the GPG key used for package signing. @@ -96,7 +90,7 @@ repository. It will also add the the GPG key used for package signing. curl -s https://packagecloud.io/install/repositories/StackStorm/stable/script.rpm.sh | sudo bash Install |st2| Components -~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -105,27 +99,27 @@ Install |st2| Components .. include:: common/configure_components.rst Setup Datastore Encryption -~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. include:: common/datastore_crypto_key.rst Configure SSH and SUDO -~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. include:: common/configure_ssh_and_sudo.rst Start Services -~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. include:: common/start_services.rst 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. @@ -144,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 @@ -212,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 @@ -262,7 +256,7 @@ 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 diff --git a/docs/source/upgrade_notes.rst b/docs/source/upgrade_notes.rst index 6a4839e2b..834e6eba5 100644 --- a/docs/source/upgrade_notes.rst +++ b/docs/source/upgrade_notes.rst @@ -9,9 +9,10 @@ Upgrade Notes ---------- * 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. + + * 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``. @@ -21,7 +22,7 @@ Upgrade Notes .. code-block:: - cat path/to/ssl_keyfile path/to/ssl_certfile > path/to/tls_certificate_key_file + 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``): @@ -31,6 +32,45 @@ Upgrade Notes * ``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: