Docker Compose Updates

Adds docker-compose directory with content to start container suite using
nginx as front and and SwaggerUI in its own container.
Updates the documentation to reflect new method of starting StorPerf.

Change-Id: I469676e330dcad6c968b90133df8866b69eb5ea1
JIRA: STORPERF-181
Signed-off-by: mbeierl <mark.beierl@dell.com>

1 files changed, 56 insertions, 97 deletions

diff --git a/docs/testing/user/introduction.rst b/docs/testing/user/introduction.rst
index a40750f..49e3220 100644
--- a/docs/testing/user/introduction.rst
+++ b/docs/testing/user/introduction.rst
@@ -2,100 +2,59 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. (c) OPNFV, Dell EMC and others.
 
-==================================
-StorPerf Container Execution Guide
-==================================
-
-Planning
-========
-
-There are some ports that the container can expose:
-
-    * 22 for SSHD. Username and password are root/storperf. This is used for CLI access only
-    * 5000 for StorPerf ReST API.
-    * 8000 for StorPerf's Graphite Web Server
-
-OpenStack Credentials
-~~~~~~~~~~~~~~~~~~~~~
-
-You must have your OpenStack Controller environment variables defined and passed to
-the StorPerf container. The easiest way to do this is to put the rc file contents
-into a clean file the looks similar to this for V2 authentication:
-
-.. code-block:: console
-
-    OS_AUTH_URL=http://10.13.182.243:5000/v2.0
-    OS_TENANT_ID=e8e64985506a4a508957f931d1800aa9
-    OS_TENANT_NAME=admin
-    OS_PROJECT_NAME=admin
-    OS_USERNAME=admin
-    OS_PASSWORD=admin
-    OS_REGION_NAME=RegionOne
-
-For V3 authentication, use the following:
-
-.. code-block:: console
-
-   OS_AUTH_URL=http://10.13.182.243:5000/v3
-   OS_PROJECT_ID=32ae78a844bc4f108b359dd7320463e5
-   OS_PROJECT_NAME=admin
-   OS_USER_DOMAIN_NAME=Default
-   OS_USERNAME=admin
-   OS_PASSWORD=admin
-   OS_REGION_NAME=RegionOne
-   OS_INTERFACE=public
-   OS_IDENTITY_API_VERSION=3
-
-Additionally, if you want your results published to the common OPNFV Test Results
- DB, add the following:
-
-.. code-block:: console
-
-    TEST_DB_URL=http://testresults.opnfv.org/testapi
-
-Running StorPerf Container
-==========================
-
-You might want to have the local disk used for storage as the default size of the docker
-container is only 10g. This is done with the -v option, mounting under
-/opt/graphite/storage/whisper
-
-.. code-block:: console
-
-    mkdir -p ~/carbon
-    sudo chown 33:33 ~/carbon
-
-The recommended method of running StorPerf is to expose only the ReST and Graphite
-ports.  The command line below shows how to run the container with local disk for
-the carbon database.
-
-.. code-block:: console
-
-    docker run -t --env-file admin-rc -p 5000:5000 -p 8000:8000 -v ~/carbon:/opt/graphite/storage/whisper --name storperf opnfv/storperf
-
-
-Docker Exec
-~~~~~~~~~~~
-
-Instead of exposing port 5022 externally, you can use the exec method in docker.  This
-provides a slightly more secure method of running StorPerf container without having to
-expose port 22.
-
-If needed, the container can be entered with docker exec.  This is not normally required.
-
-.. code-block:: console
-
-    docker exec -it storperf bash
-
-Container with SSH
-~~~~~~~~~~~~~~~~~~
-
-Running the StorPerf Container with all ports open and a local disk for the result
-storage.  This is not recommended as the SSH port is open.
-
-.. code-block:: console
-
-    docker run -t --env-file admin-rc -p 5022:22 -p 5000:5000 -p 8000:8000 -v ~/carbon:/opt/graphite/storage/whisper --name storperf opnfv/storperf
-
-This will then permit ssh to localhost port 5022 for CLI access.
-
+=====================
+StorPerf Introduction
+=====================
+
+The purpose of StorPerf is to provide a tool to measure ephemeral and block
+storage performance of OpenStack.
+
+A key challenge to measuring disk performance is to know when the disk (or,
+for OpenStack, the virtual disk or volume) is performing at a consistent and
+repeatable level of performance.  Initial writes to a volume can perform
+poorly due to block allocation, and reads can appear instantaneous when
+reading empty blocks.  How do we know when the data reported is valid?  The
+Storage Network Industry Association (SNIA_) has developed methods which enable
+manufacturers to set, and customers to compare, the performance specifications
+of Solid State Storage devices.  StorPerf applies this methodology to OpenStack
+Cinder and Glance services to provide a high level of confidence in the
+performance metrics in the shortest reasonable time.
+
+.. _SNIA: http://www.snia.org/sites/default/files/HoEasen_SNIA_Solid_State_Storage_Per_Test_1_0.pdf
+
+How Does StorPerf Work?
+=======================
+
+Once launched, StorPerf presents you with a ReST interface, along with a
+`Swagger UI <https://swagger.io/swagger-ui/>`_ that makes it easier to
+form HTTP ReST requests.  Issuing an HTTP POST to the configurations API
+causes StorPerf to talk to your OpenStack's heat service to create a new stack
+with as many agent VMs and attached Cinder volumes as you specify.
+
+After the stack is created, you can issue one or more jobs by issuing a POST
+to the jobs ReST API.  The job is the smallest unit of work that StorPerf
+can use to measure the disk's performance.
+
+While the job is running, StorPerf collects the performance metrics from each
+of the disks under test every minute.  Once the trend of metrics match the
+criteria specified in the SNIA methodology, the job automatically terminates
+and the valid set of metrics are available for querying.
+
+What is the criteria?  Simply put, it specifies that when the metrics
+measured start to "flat line" and stay within that range for the specified
+amount of time, then the metrics are considered to be indicative of a
+repeatable level of performance.
+
+What Data Can I Get?
+====================
+
+StorPerf provides the following metrics:
+
+* IOPS
+* Bandwidth (number of kilobytes read or written per second)
+* Latency
+
+These metrics are available for every job, and for the specific workloads,
+I/O loads and I/O types (read, write) associated with the job.
+
+As of this time, StorPerf only provides textual reports of the metrics.