From 99dfc0d637115cf50789c19bd67afc564f280146 Mon Sep 17 00:00:00 2001 From: Carlos Date: Thu, 29 Jan 2026 08:10:01 +0100 Subject: [PATCH] Add Rocky10 and Ubuntu 24.04 to installation documentation --- docs/source/install/__mongodb_note.rst | 5 +- docs/source/install/rhel10.rst | 354 +++++++++++++++++++++++++ docs/source/install/u24.rst | 224 ++++++++++++++++ 3 files changed, 579 insertions(+), 4 deletions(-) create mode 100644 docs/source/install/rhel10.rst create mode 100644 docs/source/install/u24.rst diff --git a/docs/source/install/__mongodb_note.rst b/docs/source/install/__mongodb_note.rst index 309555bf0..deba6bb5a 100644 --- a/docs/source/install/__mongodb_note.rst +++ b/docs/source/install/__mongodb_note.rst @@ -1,6 +1,3 @@ .. note:: - The currently supported version of MongoDB is 4.0. This is the version installed by - the installer script. - - + The currently supported version of MongoDB is 8.2. This is the version installed by the installer script. diff --git a/docs/source/install/rhel10.rst b/docs/source/install/rhel10.rst new file mode 100644 index 000000000..1bd533800 --- /dev/null +++ b/docs/source/install/rhel10.rst @@ -0,0 +1,354 @@ +RHEL 10/Rocky 10 +======================================================================== + +.. 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 ``10.x`` distributions, but our RPMs should be compatible with other RHEL``10.x`` derivatives, e.g. CentOS 10 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 dnf 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 + +MongoDB, RabbitMQ, and Redis: + +.. note:: + + At the time of writing these instructions, MongoDB community RPM packages are unavailable for Rocky 10 so the Rocky 9 package is used. + Refer to the official MongoDB documentation to check if Rocky 10 RPM packages have been published. + +.. code-block:: bash + + sudo dnf -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-10.noarch.rpm + + # Configure MongoDB (8.2) package repository + sudo tee </etc/yum.repos.d/redis.repo + [Redis] + name=Redis + baseurl=http://packages.redis.io/rpm/rockylinux9 + enabled=1 + gpgcheck=1 + EOF + + sudo rpm --import https://packages.redis.io/gpg + + sudo dnf -y install crudini erlang rabbitmq-server redis mongodb-org + sudo systemctl enable mongod rabbitmq-server redis + sudo systemctl start 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 dnf 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 dnf -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 tee </etc/yum.repos.d/nginx.repo + [nginx] + name=nginx repo + baseurl=http://nginx.org/packages/rhel/\$releasever/x86_64/ + gpgcheck=1 + enabled=1 + EOF + + # Ensure that EPEL repo is not used for nginx + sudo crudini --ini-options=nospace --set /etc/yum.repos.d/epel.repo epel exclude nginx + + # Install nginx + sudo dnf install -y nginx + + # Install st2web + sudo dnf 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. + +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 + source ~/.bashrc + 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 `__ diff --git a/docs/source/install/u24.rst b/docs/source/install/u24.rst new file mode 100644 index 000000000..6b53003c8 --- /dev/null +++ b/docs/source/install/u24.rst @@ -0,0 +1,224 @@ +Ubuntu Noble (24.04) +===================== + +.. include:: common/intro.rst + +.. contents:: Contents + :local: + +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 gnupg apt-transport-https -y + export OS_CODENAME=$(source /etc/os-release && echo $VERSION_CODENAME) + + # Add MongoDB (8.2) repository signing key and apt repository + curl -1sLf https://pgp.mongodb.com/server-8.0.asc | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/mongodb-org-8.0.gpg + echo "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/mongodb-org-8.0.gpg] https://repo.mongodb.org/apt/ubuntu ${OS_CODENAME}/mongodb-org/8.2 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-8.2.list + + # Add RabbitMQ (4.2), RabbitMQ-erlang (27.x) 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 + + 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 + +.. _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 v20 repository `_: + + .. 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: + + .. 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 `__