Ubuntu Xenial (16.04)¶
If you’re just looking for a quick “one-liner” installation, check the top-level install guide. If you need a customised installation, use this guide for step-by-step instructions for installing StackStorm on a single system as per the Reference deployment.
Note
Use the Source, Luke! We strive to keep the documentation current, but the best way to find out what really happens is to look at the code of the installer scripts.
Contents
System Requirements¶
Please check the supported versions and system requirements.
Minimal Installation¶
Install Dependencies¶
Note
The currently supported version of MongoDB is 4.0. This is the version installed by the installer script.
Install MongoDB, and RabbitMQ:
sudo apt-get update
sudo apt-get install -y gnupg-curl
sudo apt-get install -y curl
# Add key and repo for the latest stable MongoDB (4.0)
wget -qO - https://www.mongodb.org/static/pgp/server-4.0.asc | sudo apt-key add -
sudo sh -c "cat <<EOT > /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
sudo apt-get install -y crudini
sudo apt-get install -y mongodb-org
sudo apt-get install -y rabbitmq-server
For Ubuntu Xenial
you may need to enable and start MongoDB.
sudo systemctl enable mongod
sudo systemctl start mongod
Setup Repositories¶
The following script will detect your platform and architecture and setup the appropriate StackStorm repository. It will also add the the GPG key used for package signing.
curl -s https://packagecloud.io/install/repositories/StackStorm/stable/script.deb.sh | sudo bash
Python 3.6 is not available in the base Ubuntu Xenial distro, but the following instructions can add unofficial 3rd party Python PPA repository that provides it.
Warning
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.
sudo apt-get install -y software-properties-common
# add unofficial 3rd party python3 PPA repository
sudo add-apt-repository -y ppa:deadsnakes/ppa
sudo apt-get update
Install StackStorm Components¶
sudo apt-get install -y st2
If you are not running RabbitMQ or MongoDB on the same system, or have changed the defaults, please adjust these settings:
RabbitMQ connection at
/etc/st2/st2.conf
MongoDB at
/etc/st2/st2.conf
See the Configuration documentation for more information.
Setup Datastore Encryption¶
The Key-value store allows users to store encrypted values (secrets). These are stored using symmetric encryption (AES256). To generate a crypto key, run these commands:
DATASTORE_ENCRYPTION_KEYS_DIRECTORY="/etc/st2/keys"
DATASTORE_ENCRYPTION_KEY_PATH="${DATASTORE_ENCRYPTION_KEYS_DIRECTORY}/datastore_key.json"
sudo mkdir -p ${DATASTORE_ENCRYPTION_KEYS_DIRECTORY}
sudo st2-generate-symmetric-crypto-key --key-path ${DATASTORE_ENCRYPTION_KEY_PATH}
# Make sure only st2 user can read the file
sudo chgrp st2 ${DATASTORE_ENCRYPTION_KEYS_DIRECTORY}
sudo chmod o-r ${DATASTORE_ENCRYPTION_KEYS_DIRECTORY}
sudo chgrp st2 ${DATASTORE_ENCRYPTION_KEY_PATH}
sudo chmod o-r ${DATASTORE_ENCRYPTION_KEY_PATH}
# set path to the key file in the config
sudo crudini --set /etc/st2/st2.conf keyvalue encryption_key_path ${DATASTORE_ENCRYPTION_KEY_PATH}
sudo st2ctl restart-component st2api
Configure SSH and SUDO¶
To run local and remote shell actions, StackStorm uses a special system user (by default stanley
).
For remote Linux actions, SSH is used. We recommend configuring public key-based SSH access on all
remote hosts. We also recommend configuring SSH access to localhost for running examples and
testing.
Create StackStorm system user, enable passwordless sudo, and set up ssh access to “localhost” so that SSH-based actions can be tested locally. You will need elevated privileges to do this:
# Create an SSH system user (default `stanley` user may already exist) sudo useradd stanley sudo mkdir -p /home/stanley/.ssh sudo chmod 0700 /home/stanley/.ssh # Generate ssh keys sudo ssh-keygen -f /home/stanley/.ssh/stanley_rsa -P "" # Authorize key-based access sudo sh -c 'cat /home/stanley/.ssh/stanley_rsa.pub >> /home/stanley/.ssh/authorized_keys' sudo chown -R stanley:stanley /home/stanley/.ssh # Enable passwordless sudo sudo sh -c 'echo "stanley ALL=(ALL) NOPASSWD: SETENV: ALL" >> /etc/sudoers.d/st2' sudo chmod 0440 /etc/sudoers.d/st2 # Make sure `Defaults requiretty` is disabled in `/etc/sudoers` sudo sed -i -r "s/^Defaults\s+\+?requiretty/# Defaults +requiretty/g" /etc/sudoers
Configure SSH access and enable passwordless sudo on the remote hosts which StackStorm will be running remote actions on via SSH. Using the public key generated in the previous step, follow the instructions at Configure SSH. To control Windows boxes, configure access for Windows runners.
If you are using a different user, or path to their SSH key, you will need to change this section in
/etc/st2/st2.conf
:[system_user] user = stanley ssh_key_file = /home/stanley/.ssh/stanley_rsa
Start Services¶
Start services:
sudo st2ctl start
Register sensors, rules and actions:
sudo st2ctl reload
Verify¶
The following commands will test your StackStorm installation. They should all complete successfully:
st2 --version
st2 -h
# List the actions from a 'core' pack
st2 action list --pack=core
# Run a local shell command
st2 run core.local -- date -R
# See the execution results
st2 execution list
# Fire a remote comand via SSH (Requires passwordless SSH)
st2 run core.remote hosts='localhost' -- uname -a
# Install a pack
st2 pack install st2
Use the supervisor script to manage StackStorm services:
sudo st2ctl start|stop|status|restart|restart-component|reload|clean
At this point you have a minimal working installation, and can happily play with StackStorm: follow the Quick Start tutorial, deploy the examples, explore and install packs from StackStorm Exchange.
But there is no joy without a Web UI, no security without SSL or authentication, no fun without ChatOps, and no money without Extreme Workflow Composer. Read on!
Configure Authentication¶
The reference deployment uses a file-based authentication provider for simplicity. Refer to Authentication to configure and use PAM or LDAP authentication backends.
To set up authentication with file-based provider:
Create a user with a password:
# 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
Enable and configure authentication in
/etc/st2/st2.conf
:[auth] # ... enable = True backend = flat_file backend_kwargs = {"file_path": "/etc/st2/htpasswd"} # ...
Restart the st2api service:
sudo st2ctl restart-component st2api
Authenticate, and check that it works:
# Login - you will be prompted for password (default 'Ch@ngeMe') st2 login st2admin # Check that it works st2 action list
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 StackStorm’s supplied site config file st2.conf.
StackStorm depends on Nginx version >=1.7.5. Ubuntu has an older version in the package repositories, so you will need to add the official Nginx repository:
# Add key and repo for the latest stable nginx
sudo apt-key adv --fetch-keys http://nginx.org/keys/nginx_signing.key
sudo sh -c "cat <<EOT > /etc/apt/sources.list.d/nginx.list
deb http://nginx.org/packages/ubuntu/ $(lsb_release -c | awk '{print $2}') nginx
EOT"
sudo apt-get update
# Install st2web and nginx
# note nginx should be > 1.4.6
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
# 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.
If you are trying to access the API from outside the box and you have configured nginx according to
these instructions, use https://${EXTERNAL_IP}/api/v1/${REST_ENDPOINT}
.
For example:
curl -X GET -H 'Connection: keep-alive' -H 'User-Agent: manual/curl' -H 'Accept-Encoding: gzip, deflate' -H 'Accept: */*' -H 'X-Auth-Token: <YOUR_TOKEN>' https://1.2.3.4/api/v1/actions
Similarly, you can connect to auth REST endpoints with https://${EXTERNAL_IP}/auth/v1/${AUTH_ENDPOINT}
.
You can see the actual REST endpoint for a resource by adding a --debug
option to the CLI
command for the appropriate resource.
For example, to see the endpoint for getting actions, invoke:
st2 --debug action list
Setup ChatOps¶
If you already run a Hubot instance, you can install the hubot-stackstorm plugin and configure StackStorm environment variables, as described below. Otherwise, the easiest way to enable StackStorm ChatOps is to use the st2chatops package.
Validate that the
chatops
pack is installed, and a notification rule is enabled:# 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
-
curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
Install the
st2chatops
package:sudo apt-get install -y st2chatops
Review and edit the
/opt/stackstorm/chatops/st2chatops.env
configuration file to point it to your StackStorm installation and the Chat Service you are using. At a minimum, you should generate an API key and set theST2_API_KEY
variable. By defaultst2api
andst2auth
are expected to be on the same host. If that is not the case, please update theST2_API
andST2_AUTH_URL
variables or just point to the correct host withST2_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 inst2chatops.env
: Slack, Flowdock, IRC , Mattermost, RocketChat, XMPP.Start the service:
sudo service st2chatops start
Reload st2 packs to make sure
chatops.notify
rule is registered:sudo st2ctl reload --register-all
That’s it! Go to your Chat room and begin ChatOps-ing. Read more in the ChatOps section.
A Note on Security¶
By default, when MongoDB and RabbitMQ are installed, they have authentication disabled or use a default static password. As such, after you install those services you should configure them and enable authentication with strong randomly generated passwords.
NB: If you use the StackStorm installation script, this is done automatically for you.
Configuring authorization and passwords for those services is out of the scope for this documentation. For more information refer to the links below:
MongoDB - https://docs.mongodb.com/manual/tutorial/enable-authentication/, https://docs.mongodb.com/manual/core/authorization/
RabbitMQ - https://www.rabbitmq.com/authentication.html
After you enable authentication for those components, you will also need to update StackStorm services to use the new settings.
This means editing the following configuration options:
StackStorm -
/etc/st2/st2.conf
database.username
- MongoDB database username.
database.password
- MongoDB database password.
messaging.url
- RabbitMQ transport url (amqp://<username>:<password>@<hostname>:5672
)
In addition, you are strongly encouraged to follow these best practices for running network services:
Ensure communication between services is encrypted. Enable SSL/TLS for MongoDB and RabbitMQ,
Configure services to only listen on localhost, and where needed, internal IP addresses. There is usually no need for most services which are used by StackStorm (MongoDB, RabbitMQ) to be available on a public IP address.
Configure a firewall and set up a whitelist. The firewall should only allow access by those users and systems which need access to those services. API and auth services usually need to be accessible to your users, but other dependent services such as MongoDB and RabbitMQ don’t. These should not be directly accessible by users, and only StackStorm components should be allowed to talk to them.
Where possible, you should also utilize additional network-based isolation and security features such as DMZs.
The steps mentioned above are especially important for distributed production deployments where StackStorm components are running on multiple servers.
Upgrade to Extreme Workflow Composer¶
For StackStorm versions earlier than 3.3, Extreme Networks provided a commercial version of the StackStorm automation platform (EWC). EWC added priority support, advanced features such as fine-tuned access control (RBAC), LDAP, and Workflow Designer.
As these enterprise features were donated to the Linux Foundation, RBAC, LDAP and Workflow Designer components are now available in StackStorm Open Source since 3.4. The Workflow Designer is integrated into the StackStorm Web UI, and RBAC and LDAP components are installed (but not configured) with the default installation.
What’s Next?
Check out the Quick Start Guide to build a simple automation.
Get more actions, triggers, rules:
Install integration packs from StackStorm Exchange - follow the Packs guide.
Learn how to write custom actions.
Use workflows to stitch actions into higher level automations - Workflows.
Check out tutorials on stackstorm.com