Skip to content

Update Docker stable docs (v3.2) #1001

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
arm4b merged 4 commits into from
Aug 4, 2020
Merged

Update Docker stable docs (v3.2) #1001

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d63e6f9
Reorder the deployment methods by simplicity
Jul 17, 2020
52f15b3
Update Docker installation instructions
Jul 28, 2020
a25bb5f
Fix Docker link
Aug 4, 2020
e4099fb
Fix Puppet link
Aug 4, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 0 additions & 6 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,8 +113,6 @@ ewcdocs: .clone-st2 .clone-orquesta .clone-ipfabric requirements .requirements-s
@echo
cp -R ipfabric/docs/source/* docs/source/
rm docs/source/install/puppet_chef_salt_ansible.rst
rm docs/source/install/docker.rst
rm docs/source/install/puppet.rst

.PHONY: .git-checkout-local-changes
.git-checkout-local-changes:
Expand All @@ -125,11 +123,7 @@ ewcdocs: .clone-st2 .clone-orquesta .clone-ipfabric requirements .requirements-s
@echo
git checkout docs/source/info.py
git checkout docs/source/_includes/solutions.rst
git checkout docs/source/_includes/community_only_installs_overview.rst
git checkout docs/source/_includes/community_only_installs_toctree.rst
git checkout docs/source/install/puppet_chef_salt_ansible.rst
git checkout docs/source/install/docker.rst
git checkout docs/source/install/puppet.rst

.PHONY: ewclivedocs
ewclivedocs: ewcdocs .livedocs
Expand Down
11 changes: 0 additions & 11 deletions docs/source/_includes/community_only_installs_overview.rst
View file
Open in desktop

This file was deleted.

5 changes: 0 additions & 5 deletions docs/source/_includes/community_only_installs_toctree.rst
View file
Open in desktop

This file was deleted.

107 changes: 28 additions & 79 deletions docs/source/install/docker.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Docker
======

Like `Docker <https://www.docker.com>`_? And `Kubernetes <https://kubernetes.io>`_? So do we!
Like Docker? So do we!

One of the quickest ways to get StackStorm running is using Docker. This page will show you the basics
of how to use StackStorm with Docker.
Expand All @@ -10,120 +10,69 @@ For more detailed information and examples, check out the `README
<https://github.com/StackStorm/st2-docker/blob/master/README.md>`_ at our `st2-docker GitHub repo
<https://github.com/StackStorm/st2-docker>`_.

.. note::
If you use Kubernetes, check the :doc:`/install/k8s_ha` for more information.

Host Requirements
-----------------

* Install the latest versions of Docker engine, and optionally ``docker-compose``. Installation
* Install the latest versions of ``Docker`` engine and ``docker-compose``. Installation
instructions are at https://www.docker.com/community-edition and
https://docs.docker.com/compose/install.

.. note::
We require at least version 1.13.0 of Docker engine. If you choose to use ``docker-compose``
it must also be at least version 1.13.0.

* If you use Kubernetes, check the :doc:`/install/k8s_ha`
for more information.

Docker Images
-------------

The ``stackstorm/stackstorm`` image comes pre-installed with the ``st2``, ``st2web``,
``st2mistral`` and ``st2chatops`` packages.

.. note::

This docker image only supports the open source version of StackStorm. Please contact
`Extreme Sales <https://www.extremenetworks.com/contact-sales/>`_ if you want more info on running
Extreme Workflow Composer (EWC) in container.

We use version tags, so if you install the image ``stackstorm/stackstorm:2.3.2``, then it has the
StackStorm 2.3.2 release packages. Similarly, if you install image ``stackstorm/stackstorm:2.2.1``,
then it has the StackStorm 2.2.1 release packages. The ``stackstorm/stackstorm:latest`` image simply
references the image with the highest version number. Don't worry, this will still be a stable GA
release, not a nightly build.

The mongo, rabbitmq, postgres and redis containers store their data on persistent storage.
Additionally, the stackstorm container persists the contents of ``/var/log``. If you do not wish to
persist this data, then remove the appropriate entries from ``docker-compose.yml``.
Docker-compose deployment relies on pre-built, tested and deployed to Docker Hub StackStorm images.
Check out `stackstorm/st2-dockerfiles <https://github.com/stackstorm/st2-dockerfiles>`_ GitHub repository
if you need more details about the StackStorm Dockerfiles internals.

Usage
-----
Assuming ``Docker engine`` and ``docker-compose`` are properly installed, getting started is easy.

Assuming Docker engine and ``docker-compose`` are properly installed, getting started is easy.

First, clone the ``st2-docker`` repository and change directory to ``st2-docker``. Unless specified
otherwise, all subsequent commands assume they are run within ``st2-docker`` directory:
First, clone the ``st2-docker`` repository. Unless specified otherwise, all subsequent
commands assume they are run within ``st2-docker`` directory:

.. code-block:: bash

git clone https://github.com/stackstorm/st2-docker
cd st2-docker

Second, execute:

.. code-block:: bash

make env

to create the environment files under ``conf/`` used by ``docker-compose``. Prior to doing so, you
may want to change some variables as necessary. The defaults should be okay if you are not using
any off-cluster services (e.g. mongo, redis, postgres, rabbitmq).

Below is the complete list of available options that can be used to customize your container:
You may want to change some variables as necessary. The defaults should be okay.
Below is the complete list of available options that can be used to customize your containers:

+---------------------------+-------------------------------------------------------------------------------------------------------------+
| Parameter | Description |
+===========================+=============================================================================================================+
| ``ST2_USER`` | StackStorm account username |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``ST2_PASSWORD`` | StackStorm account password |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``MONGO_HOST`` | MongoDB server hostname |
| ``ST2_VERSION`` | Tag at the end of the docker image (ie: ``stackstorm/st2api:v3.3dev``). |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``MONGO_PORT`` | MongoDB server port (typically `27017`) |
| ``ST2_IMAGE_REPO`` | The image or path to the images. Default is ``stackstorm/``. |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``MONGO_DB`` | *(Optional)* MongoDB dbname (will use `st2` if not specified) |
| ``ST2_EXPOSE_HTTP`` | Port to expose st2web port 80 on. Default is ``127.0.0.1:80``, and you may want to do ``0.0.0.0:80``. |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``MONGO_USER`` | *(Optional)* MongoDB username (will connect without credentials if this and `MONGO_PASS` are not specified) |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``MONGO_PASS`` | *(Optional)* MongoDB password |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``RABBITMQ_HOST`` | RabbitMQ server hostname |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``RABBITMQ_PORT`` | RabbitMQ server port (typically `5672`) |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``RABBITMQ_DEFAULT_USER`` | RabbitMQ username |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``RABBITMQ_DEFAULT_PASS`` | RabbitMQ password |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``POSTGRES_HOST`` | PostgreSQL server hostname |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``POSTGRES_PORT`` | PostgreSQL server port (typically `5432`) |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``POSTGRES_DB`` | PostgreSQL database |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``POSTGRES_USER`` | PostgreSQL username |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``POSTGRES_PASSWORD`` | PostgreSQL password |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``REDIS_HOST`` | Redis server hostname |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``REDIS_PORT`` | Redis server port |
+---------------------------+-------------------------------------------------------------------------------------------------------------+
| ``REDIS_PASSWORD`` | *(Optional)* Redis password |
| ``ST2_PACKS_DEV`` | Directory to development packs. This allows you to develop packs locally. Default is ``./packs.dev``. |
+---------------------------+-------------------------------------------------------------------------------------------------------------+

Third, start the containers:
Then, start the containers:

.. code-block:: bash

docker-compose up -d

This will pull the required images from Docker Hub, and then start them.

To switch to shell inside the container where you can use ``st2`` CLI:

.. sourcecode:: bash

docker-compose exec st2client bash

Navigate the UI configured by default at http://localhost/.
Username/Password pair is ``st2admin:Ch@ngeMe`` and could be configured via ``files/htpasswd``.

To stop the containers, run:

.. sourcecode:: bash

docker-compose down

More information can be found in the ``st2-docker`` `README.md <https://github.com/StackStorm/st2-docker/blob/master/README.md>`_.
21 changes: 14 additions & 7 deletions docs/source/install/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,16 +19,22 @@ Here's an overview of the options:
your needs. Here's some `additional guidance
<https://stackstorm.com/2017/02/10/installing-stackstorm-offline-systems/>`_ for setting up an
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,
pack development or demo system and recommended to get familiar with StackStorm platform.
``vagrant init stackstorm/st2 && vagrant up`` is all you need to get started.
See :doc:`Vagrant </install/vagrant>` for more detailed instructions.
* **Docker:** StackStorm is supported on Docker - check out our :doc:`/install/docker` instructions.
It's one of the quickest way to get StackStorm running and useful for trying the platform and development.
* **Ansible Playbooks:** If you are an Ansible user, check these :doc:`/install/ansible` for
installing |st2|. Ideal for repeatable, consistent, idempotent installation of |st2|.
* **Puppet Module:** For Puppet users, check this :doc:`/install/puppet` for
installing StackStorm. A robust and idempotent method of installing and configuring StackStorm.
* **High Availability** Entrusting business critical automation tasks to a system like StackStorm
leads to higher demands on that system. StackStorm can run in a HA mode to ensure these needs.
:doc:`/install/k8s_ha` automates entire complex infrastructure as a reproducible blueprint.

.. only:: community

.. include:: /_includes/community_only_installs_overview.rst


Choose the option that best suits your needs.

Expand Down Expand Up @@ -90,10 +96,11 @@ For more details on reference deployments, or OS-specific installation instructi
RHEL 6 / CentOS 6 <rhel6>
RHEL 7 / CentOS 7 <rhel7>
RHEL 8 / CentOS 8 <rhel8>
Kubernetes / HA <k8s_ha>
Vagrant / OVA <vagrant>
Docker <docker>
Ansible Playbooks <ansible>

.. include:: /_includes/community_only_installs_toctree.rst
Puppet Module <puppet>
Kubernetes / HA <k8s_ha>

.. toctree::
:maxdepth: 1
Expand Down