Refresh README

This updates the README and moves "how ara works" as well as
"what ara looks like" from the FAQs to the README where they
are more relevant.

Change-Id: Ic928b23802b393e6775b54b3e6c51982758e79d6

README.rst

@@ -5,44 +5,124 @@ ARA Records Ansible playbooks and makes them easier to understand and troublesho
 
 .. image:: doc/source/_static/ara-with-icon.png
 
-ARA saves playbook results to a local or remote database by using an Ansible
+How it works
-callback plugin and provides an API to integrate this data in tools and interfaces.
+============
 
-This project provides ARA's Ansible plugins, the REST API server as well as
+ARA saves Ansible playbook execution results to local or remote databases by
-simple built-in web interfaces to browse the recorded data.
+using an Ansible `callback plugin <https://docs.ansible.com/ansible/latest/plugins/callback.html>`_.
 
-A stateless javascript client interface is provided by a different project,
+This callback plugin leverages built-in python API clients to send data to a
-`ara-web <https://github.com/ansible-community/ara-web>`_.
+REST API server where data and metrics are made available for querying,
+browsing, monitoring or for integration in other tools and interfaces.
 
-Quickstart
+.. image:: doc/source/_static/graphs/recording-workflow.png
-==========
 
-Here's how you can get started from scratch with sane defaults with python>=3.5:
+What it looks like
+==================
+
+API browser
+-----------
+
+Included by the API server with django-rest-framework, the API browser allows
+users to navigate the different API endpoints and query recorded data.
+
+.. image:: doc/source/_static/ui-api-browser.png
+
+Reporting interface
+-------------------
+
+A simple reporting interface built-in to the API server without any extra
+dependencies.
+
+.. image:: doc/source/_static/ui-playbook-search.png
+
+ara-web
+-------
+
+A project that is a work in progress and would appreciate contributions,
+`ara-web <https://github.com/ansible-community/ara-web>`_ is a stateless
+javascript interface to the API built with react and patternfly.
+
+.. image:: doc/source/_static/ui-ara-web.png
+
+Getting started
+===============
+
+Recording playbooks without an API server
+-----------------------------------------
+
+The default API client, ``offline``, requires API server dependencies to be
+installed but does not need the API server to be running in order to query or
+send data.
+
+With defaults and using a local sqlite database:
 
 .. code-block:: bash
 
-    # Install ARA and Ansible for the current user
+    # Install Ansible and ARA (with API server dependencies) for the current user
     python3 -m pip install --user ansible "ara[server]"
 
-    # Tell Ansible to use the ARA callback plugin
+    # Configure Ansible to use the ARA callback plugin
     export ANSIBLE_CALLBACK_PLUGINS="$(python3 -m ara.setup.callback_plugins)"
 
-    # Run your playbook
+    # Run an Ansible playbook
-    ansible-playbook playbook.yml
+    ansible-playbook playbook.yaml
 
-If nothing went wrong, your playbook data should have been saved in a local
+    # Start the built-in development server to browse recorded results
-database at ``~/.ara/server/ansible.sqlite``.
+    ara-manage runserver
 
-You can take a look at the recorded data by running ``ara-manage runserver``
+Recording playbooks with an API server
-and pointing your browser at http://127.0.0.1:8000/.
+--------------------------------------
 
-That's it !
+When running Ansible from multiple servers or locations, data can be aggregated
+by running the API server as a service and configuring the ARA Ansible callback
+plugin to use the ``http`` API client with the API server endpoint.
 
-Live demos
+The API server is a relatively simple django web application written in python
-==========
+that can run with WSGI application servers such as gunicorn, uwsgi or mod_wsgi.
 
-You can find live demos deployed by the built-in ara_api_ and ara_web_ Ansible
+Alternatively, the API server can also run from a container image such as the
-roles at https://api.demo.recordsansible.org and https://web.demo.recordsansible.org.
+one available on `DockerHub <https://hub.docker.com/r/recordsansible/ara-api>`_:
+
+.. code-block:: bash
+
+    # Start an API server from the image on DockerHub:
+    mkdir -p ~/.ara/server
+    podman run --name api-server --detach --tty \
+      --volume ~/.ara/server:/opt/ara:z -p 8000:8000 \
+      docker.io/recordsansible/ara-api:latest
+
+Once the server is running, Ansible playbook results can be sent to it by
+configuring the ARA callback plugin:
+
+.. code-block:: bash
+
+    # Install Ansible and ARA (without API server dependencies) for the current user
+    python3 -m pip install --user ansible ara
+
+    # Configure Ansible to use the ARA callback plugin
+    export ANSIBLE_CALLBACK_PLUGINS="$(python3 -m ara.setup.callback_plugins)"
+
+    # Set up the ARA callback to know where the API server is located
+    export ARA_API_CLIENT="http"
+    export ARA_API_SERVER="http://127.0.0.1:8000"
+
+    # Run an Ansible playbook
+    ansible-playbook playbook.yaml
+
+Data will be available on the API server in real time as the playbook progresses
+and completes.
+
+Live demo
+=========
+
+Deployments of the ARA API server and ara-web are available for demonstration
+and test purposes:
+
+- https://api.demo.recordsansible.org
+- https://web.demo.recordsansible.org
+
+These live demos are deployed using the ara_api_ and ara_web_ Ansible roles.
 
 .. _ara_api: https://ara.readthedocs.io/en/latest/ansible-role-ara-api.html
 .. _ara_web: https://ara.readthedocs.io/en/latest/ansible-role-ara-web.html
@@ -63,17 +143,25 @@ Community and getting help
 - Website and blog: https://ara.recordsansible.org
 - Twitter: https://twitter.com/arecordsansible
 
-Contributors
+Contributing
 ============
 
-See contributors on `GitHub <https://github.com/ansible-community/ara/graphs/contributors>`_.
+Contributions to the project are welcome and appreciated !
+
+Get started with the `contributor's documentation <https://ara.readthedocs.io/en/latest/contributing.html>`_.
+
+Authors
+=======
+
+Contributors to the project can be viewed on
+`GitHub <https://github.com/ansible-community/ara/graphs/contributors>`_.
 
 Copyright
 =========
 
 ::
 
-    Copyright (c) 2019 Red Hat, Inc.
+    Copyright (c) 2020 Red Hat, Inc.
 
     ARA Records Ansible is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -86,4 +174,4 @@ Copyright
     GNU General Public License for more details.
 
     You should have received a copy of the GNU General Public License
-    along with ARA Records Ansible.  If not, see <http://www.gnu.org/licenses/>.
+    along with ARA Records Ansible.  If not, see <http://www.gnu.org/licenses/>.

doc/source/api-documentation.rst

@@ -12,15 +12,15 @@ favorite web browser.
 For example, if you run ``ara-manage runserver``, this interface would be
 available at ``http://127.0.0.1:8000/api/v1/``:
 
-.. image:: ../source/_static/ara-api-browser-root.png
+.. image:: ../source/_static/ui-api-browser.png
 
 You can navigate the interface and drill down to list views, for example:
 
-.. image:: ../source/_static/ara-api-browser-playbooks.png
+.. image:: ../source/_static/ui-api-browser-playbooks.png
 
 You can also see what a detailed view looks like by querying a specific object id:
 
-.. image:: ../source/_static/ara-api-browser-playbook.png
+.. image:: ../source/_static/ui-api-browser-playbook.png
 
 Alternatively, you may also find an up-to-date live demonstration of the API at
 ``https://api.demo.recordsansible.org``.

doc/source/faq.rst

@@ -10,62 +10,6 @@ ARA is currently composed of three different free and open source projects:
 - https://github.com/ansible-community/ara-web for the standalone web interface
 - https://github.com/ansible-community/ara-infra for project-specific infrastructure needs (such as the `ara.recordsansible.org <https://ara.recordsansible.org>`_ website)
 
-How does ARA record data from Ansible ?
----------------------------------------
-
-ARA Records Ansible playbooks through an Ansible `callback plugin`_.
-
-.. image:: _static/graphs/recording-workflow.png
-
-0. ARA is installed and Ansible is configured to use the callback plugin
-1. An ``ansible-playbook`` command is executed
-2. Ansible triggers the callback plugin for every event (``v2_playbook_on_start``, ``v2_runner_on_failed``, etc.)
-3. The relevant information is retrieved from the Ansible playbook execution context and is sent to the API server
-4. The API server validates and serializes the data before storing it the configured database backend
-5. The API server sends a response back to the API client with the results
-6. The callback plugin returns, ending the callback hook
-7. Ansible continues running the playbook until it fails or is completed (back to step 2)
-
-Once the data has been saved in the database, it is made available for query by
-the API.
-
-.. _callback plugin: https://docs.ansible.com/ansible/latest/plugins/callback.html
-
-How can we browse the data recorded by ARA ?
---------------------------------------------
-
-There are currently three ways to browse data recorded by ARA:
-
-Built-in REST API Browser
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The ARA API server ships with a built-in REST API browser provided by `django-rest-framework <https://www.django-rest-framework.org/>`_.
-
-.. image:: ../source/_static/ara-api-browser-root.png
-
-Built-in simple interface
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-ARA also provides a simple, but limited, interface for use cases that do not need or require features provided by ara-web.
-
-.. image:: ../source/_static/ui-built-in.png
-
-ara-web
-~~~~~~~
-
-ara-web_ is a stateless javascript API client interface built with react.
-It queries a running API server to provide reporting and visualization of playbook runs.
-
-.. image:: ../source/_static/ui-ara-web.png
-
-Are there live demos available ?
---------------------------------
-
-Yes, you can find persistent and up-to-date live demos at
-`api.demo.recordsansible.org <https://api.demo.recordsansible.org>`_ for the
-API and `web.demo.recordsansible.org <https://web.demo.recordsansible.org>`_ for
-the ara-web_ standalone interface.
-
 What's an Ansible callback ?
 ----------------------------