diff --git a/docs/source/install/index.rst b/docs/source/install/index.rst index 12cd0477..5e7ca583 100644 --- a/docs/source/install/index.rst +++ b/docs/source/install/index.rst @@ -93,6 +93,7 @@ For more details on reference deployments, or OS-specific installation instructi system_requirements Ubuntu 16.04 Ubuntu 18.04 + Ubuntu 20.04 RHEL 7 / CentOS 7 RHEL 8 / CentOS 8 Vagrant / OVA diff --git a/docs/source/install/system_requirements.rst b/docs/source/install/system_requirements.rst index 069acf64..e5e77fa1 100644 --- a/docs/source/install/system_requirements.rst +++ b/docs/source/install/system_requirements.rst @@ -22,6 +22,8 @@ be automatically added when you install |st2|. +-------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `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/centos-8.2 `_ | `Red Hat Enterprise Linux (RHEL) 8 (HVM) `_ | | `CentOS 8.2 `_ | | | +-------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -48,16 +50,16 @@ This is the recommended minimum sizing for testing and deploying |st2|: If you split your filesystem into multiple partitions and mount points, ensure you have at least 1GB of free space in ``/var`` and ``/opt``. RabbitMQ and MongoDB may not operate correctly without -sufficient free space. +sufficient free space. -By default, |st2| and related services use these TCP ports: +By default, |st2| and related services use these TCP ports: * nginx (80, 443) * mongodb (27017) * rabbitmq (4369, 5672, 25672) * st2auth (9100) * st2api (9101) -* st2stream (9102) +* st2stream (9102) If any other services are currently using these ports, |st2| may fail to install or run correctly. @@ -69,12 +71,9 @@ Linux Distribution Support Policy StackStorm only support Ubuntu and RHEL/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 ``16.04`` and ``18.04``. - - Support for Ubuntu ``14.04`` has been removed, as it is now End of Life. |st2| 3.0 is the last - release that supports Ubuntu ``14.04``. +* **Ubuntu**: Current LTS releases are supported. Today this is ``16.04``, ``18.04`` and ``20.04``. * **RHEL/CentOS**: We currently support RHEL/CentOS ``7.x`` and ``8.x``. In general, we recommend using - the most recent version in that series, but any version may be used. + the most recent version in that series, but any version may be used. Support for RHEL/CentOS ``6.x`` has been removed. |st2| 3.2 is the last release that supported RHEL/CentOS ``6.x``. diff --git a/docs/source/install/u16.rst b/docs/source/install/u16.rst index 8578210e..b72ab764 100644 --- a/docs/source/install/u16.rst +++ b/docs/source/install/u16.rst @@ -61,7 +61,7 @@ Python 3.6 is not available in the base Ubuntu Xenial distro, but the following Please be aware of the support and security risks associated with using unofficial 3rd party PPA repository. StackStorm does NOT provide ANY support or security update for python3.6 packages on Ubuntu 16.04. - If security is a priority for you, we recommend starting migrating to Ubuntu 18.04 LTS (Bionic) as a base OS which has official python 3.6 packages. + If security is a priority for you, we recommend starting migrating to Ubuntu 18.04 LTS (Bionic) or 20.04 LTS (Focal) as a base OS which has official python 3.6 packages. .. code-block:: bash diff --git a/docs/source/install/u20.rst b/docs/source/install/u20.rst new file mode 100644 index 00000000..95cbbef8 --- /dev/null +++ b/docs/source/install/u20.rst @@ -0,0 +1,209 @@ +Ubuntu Focal (20.04) +===================== + +.. include:: common/intro.rst + +.. contents:: Contents + :local: + +.. note:: + + |st2| on Ubuntu ``20.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, and RabbitMQ: + +.. code-block:: bash + + sudo apt-get update + sudo apt-get install -y curl + + # 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 + + sudo apt-get install -y crudini + sudo apt-get install -y mongodb-org + sudo apt-get install -y rabbitmq-server + +For Ubuntu ``Focal`` you may need to enable and start MongoDB. + +.. code-block:: bash + + sudo systemctl enable mongod + sudo systemctl start mongod + +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.deb.sh | sudo bash + +Install |st2| Components +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + sudo apt-get 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 apt-get install -y apache2-utils + # 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 +`. + +.. 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 v10 repository `_: + + .. code-block:: bash + + curl -sL https://deb.nodesource.com/setup_10.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 `__ diff --git a/docs/source/install/uninstall.rst b/docs/source/install/uninstall.rst index d56d25b0..7f12c5ec 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 16.04/18.04: +* Ubuntu 16.04/18.04/20.04: .. sourcecode:: bash @@ -67,7 +67,7 @@ below. Only execute the instructions for your distribution. 2. Remove Packages ------------------ -* Ubuntu 16.04/18.04: +* Ubuntu 16.04/18.04/20.04: If you are using StackStorm only: diff --git a/docs/source/install/upgrades.rst b/docs/source/install/upgrades.rst index ed1df805..6e2936d3 100644 --- a/docs/source/install/upgrades.rst +++ b/docs/source/install/upgrades.rst @@ -208,7 +208,7 @@ v3.4 Please be aware of the support and security risks associated with using unofficial 3rd party PPA repository. StackStorm does NOT provide ANY support or security update for python3.6 packages on Ubuntu 16.04. - If security is a priority for you, we recommend starting migrating to Ubuntu 18.04 LTS (Bionic) as a base OS which has official python 3.6 packages. + If security is a priority for you, we recommend starting migrating to Ubuntu 18.04 LTS (Bionic) or 20.04 LTS (Focal) as a base OS which has official python 3.6 packages. This is a workaround to support Ubuntu Xenial with python 3 until we deprecate it in the future versions. .. sourcecode:: bash