diff --git a/docs/source/install/ewc.rst b/docs/source/install/ewc.rst index edfd3d041..1bed72267 100644 --- a/docs/source/install/ewc.rst +++ b/docs/source/install/ewc.rst @@ -41,8 +41,8 @@ replacing ``${EWC_LICENSE_KEY}`` with the license key you received when register ./install.sh --user=st2admin --password='Ch@ngeMe' --license=${EWC_LICENSE_KEY} To understand the full details of the installation procedure, or to install |ewc| manually, follow -the installation guide for your Linux version: :doc:`/install/u16`, :doc:`/install/u18`, :doc:`/install/rhel7`, -or :doc:`/install/rhel6`. It will walk you through installing and configuring StackStorm and |ewc|. +the installation guide for your Linux version: :doc:`/install/u16`, :doc:`/install/u18`, :doc:`/install/rhel6`, :doc:`/install/rhel7`, +or :doc:`/install/rhel8`. It will walk you through installing and configuring StackStorm and |ewc|. The last step of the instructions is "Upgrade to |ewc|". High Availability deployment diff --git a/docs/source/install/index.rst b/docs/source/install/index.rst index f4c681760..0590989ca 100644 --- a/docs/source/install/index.rst +++ b/docs/source/install/index.rst @@ -15,7 +15,8 @@ Here's an overview of the options: * **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 16 `, :doc:`Ubuntu 18 `, :doc:`RHEL/CentOS 6 `, - :doc:`RHEL/CentOS 7 `), and adapt them to your needs. Here's some `additional guidance + :doc:`RHEL/CentOS 7 `, :doc:`RHEL/CentOS 8 `) and adapt them to + your needs. Here's some `additional guidance `_ for setting up an internal mirror for the |st2| repos. * **Ansible Playbooks:** If you are an Ansible user, check these :doc:`/install/ansible` for @@ -86,8 +87,9 @@ For more details on reference deployments, or OS-specific installation instructi system_requirements Ubuntu 16.04 Ubuntu 18.04 - RHEL 7 / CentOS 7 RHEL 6 / CentOS 6 + RHEL 7 / CentOS 7 + RHEL 8 / CentOS 8 Kubernetes / HA Ansible Playbooks diff --git a/docs/source/install/rhel8.rst b/docs/source/install/rhel8.rst new file mode 100644 index 000000000..9fad77df3 --- /dev/null +++ b/docs/source/install/rhel8.rst @@ -0,0 +1,287 @@ +RHEL 8/CentOS 8 +=============== + +.. include:: common/intro.rst + +.. contents:: Contents + :local: + +System Requirements +------------------- + +Please check the :doc:`supported versions and system requirements `. + +.. note:: + + |st2| on RHEL 8/CentOS 8 runs all services, actions and sensors using Python 3**only**. It + does not support Python2 actions. `More info about python in RHEL 8 and CentOS 8. + `_ + + Mistral is not supported on RHEL 8/CentOS 8. All workflows must be written in + :doc:`Orquesta `. + +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: + +.. 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 + sudo yum -y install rabbitmq-server + sudo systemctl start mongod rabbitmq-server + sudo systemctl enable mongod rabbitmq-server + + +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 v10 repository `_: + + .. code-block:: bash + + curl -sL https://rpm.nodesource.com/setup_10.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 + +.. code-block:: bash + + # Set up Extreme Workflow Composer repository access, install Enterprise packages and configure RBAC + curl -sSL -O https://stackstorm.com/ewc/install.sh && chmod +x install.sh + ./install.sh --user=st2admin --password='Ch@ngeMe' --license=${EWC_LICENSE_KEY} + +.. 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/system_requirements.rst b/docs/source/install/system_requirements.rst index 04d6798aa..ecaaeb88d 100644 --- a/docs/source/install/system_requirements.rst +++ b/docs/source/install/system_requirements.rst @@ -22,6 +22,9 @@ be automatically added when you install |st2|. +-------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `Ubuntu 18.04 `_ | `bento/ubuntu-18.04 `_ | `Ubuntu Server 18.04 LTS Bionic `_ | +-------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `RHEL 8 `_ / | `bento/centos-8.1 `_ | `Red Hat Enterprise Linux (RHEL) 8 (HVM) `_ | +| `CentOS 8.1 `_ | | | ++-------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `RHEL 7 `_ / | `bento/centos-7.4 `_ | `Red Hat Enterprise Linux (RHEL) 7.2 (HVM) `_ | | `CentOS 7 `_ | | | +-------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/docs/source/install/uninstall.rst b/docs/source/install/uninstall.rst index 162c97fb9..87540b51f 100644 --- a/docs/source/install/uninstall.rst +++ b/docs/source/install/uninstall.rst @@ -70,6 +70,15 @@ below. Only execute the instructions for your distribution. sudo systemctl stop mongod sudo systemctl stop rabbitmq-server +* RHEL/CentOS 8.x: + + .. sourcecode:: bash + + sudo st2ctl stop + sudo systemctl stop nginx + sudo systemctl stop mongod + sudo systemctl stop rabbitmq-server + 2. Remove Packages ------------------