From d671ff33b4d668ec043e9adbed093beb16ccc202 Mon Sep 17 00:00:00 2001 From: David Moreau Simard Date: Fri, 21 Dec 2018 10:20:12 -0500 Subject: [PATCH] Update and improve README - Add quickstart docs - Remove scary disclaimer - Add community info Change-Id: Ib506baa6590ac2debc718fc42a572c747e6ac46f --- README.rst | 76 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 60 insertions(+), 16 deletions(-) diff --git a/README.rst b/README.rst index b1ec53d..5acddcf 100644 --- a/README.rst +++ b/README.rst @@ -6,33 +6,77 @@ ara-server ARA Records Ansible playbook runs and makes the recorded data available and intuitive for users and systems. -``ara-server`` is a component of ARA which provides an API to store and query -Ansible execution results: +ara-server is a modern python 3 application built with the latest releases of +`Django `_ and `django-rest-framework `_. + +``ara-server`` is the component from ARA that manages the REST API and the database. .. image:: doc/source/_static/screenshot.png -Disclaimer +- For the ARA Ansible callback plugin or the ``ara_record`` action module, look at `ara-plugins `_ +- For the ARA REST API clients, look at `ara-clients `_ +- For the ARA web interface, look at `ara-web `_ + +Quickstart ========== -``ara-server`` is not yet stable and will be shipped as part of a coordinated -ARA 1.0 release. It is not currently recommended for production use. +Here's how you can get started from scratch with default settings:: -While most of the major work has landed, please keep in mind that we can still -introduce backwards incompatible changes until we ship the first release. + # Create a virtual environment + python3 -m venv ~/.ara/venv -You are free to use this project and in fact, you are more than welcome to -contribute feedback, bug fixes or improvements ! + # Install Ansible and the required ARA projects + ~/.ara/venv/bin/pip install ansible ara-server ara-clients ara-plugins -If you are looking for a stable version of ARA, you can find the latest 0.x -version on PyPi_ and the source is available here_. + # Tell Ansible to use the ARA callback plugin from ara-plugins + export ANSIBLE_CALLBACK_PLUGINS="$(~/.ara/venv/bin/python -m ara.plugins)/callback" -.. _PyPi: https://pypi.org/project/ara/ -.. _here: https://github.com/openstack/ara + # Run your playbook as your normally would + ~/.ara/venv/bin/ansible-playbook playbook.yml + +The data is saved in real time during the Ansible playbook execution. + +What happened behind the scenes is that the ARA Ansible callback plugin +(provided by ``ara-plugins``) used the offline API client +(provided by ``ara-clients``) to send your data to the ``ara-server`` API which +then saved it to a database located by default at +``~/.ara/server/ansible.sqlite``. + +You're now ready to start poking at the API with the built-in API clients ! + +If you'd like to have the ARA web reporting interface, take a look at +`ara-web `_. Documentation ============= -*Work in progress* +Documentation for installing, configuring, running and using ara-server is +available on `readthedocs.io `_. + +Community and getting help +========================== + +You can chat with the ARA community on Slack and IRC. +The two are transparently bridged with teamchat_ which broadcasts messages from +one platform to the other. + +In addition, you can also find ARA on Twitter: `@ARecordsAnsible `_ + +**IRC** + +- Server: `irc.freenode.net`_ +- Channel: #ara + +**Slack** + +- https://arecordsansible.slack.com +- Join with the `Slack invitation `_ + +.. _teamchat: https://github.com/dmsimard/teamchat +.. _irc.freenode.net: https://webchat.freenode.net/ + +Development +=========== **TL;DR**: Using tox is convenient for the time being:: @@ -43,7 +87,7 @@ Documentation # Install tox from pip or from your distro packages pip install tox - # Run an Ansible playbook integrated ara-server, ara-clients and ara-plugins + # Run an Ansible playbook integrated with ara-server, ara-clients and ara-plugins # This will exercise all three components and record real data from Ansible tox -e ansible-integration @@ -84,4 +128,4 @@ Copyright GNU General Public License for more details. You should have received a copy of the GNU General Public License - along with ARA. If not, see . + along with ARA. If not, see . \ No newline at end of file