From 6c734132e5c99ec7ef5b507c4dae12206acac96b Mon Sep 17 00:00:00 2001 From: David Moreau Simard Date: Sun, 2 Jun 2019 21:30:30 -0400 Subject: [PATCH] Update README - Make the intro shorter and more to the point - Link to ara-web - Add local dev server to the quickstart - Include links to live demos and Ansible roles - Test docs have been moved to contributing docs Change-Id: Ie82c66965ed220824448048cbbd434c585afe0b9 --- README.rst | 107 +++++++++++++++-------------------------------------- 1 file changed, 30 insertions(+), 77 deletions(-) diff --git a/README.rst b/README.rst index 84cfa97d..11ea953d 100644 --- a/README.rst +++ b/README.rst @@ -1,122 +1,75 @@ ARA Records Ansible =================== +ARA Records Ansible playbooks and makes them easier to understand and troubleshoot. + .. image:: doc/source/_static/ara-with-icon.png -ARA Records Ansible playbook runs and makes the recorded data available and -intuitive for users and systems. +ARA saves playbook results to a local or remote database by using an Ansible +callback plugin and provides an API to integrate this data in tools and interfaces. -The project provides several distinct components in order to make this happen: +This project provides the ARA API as well as the Ansible components. -- An API server for sending and querying data relative to playbook execution results -- An API client library for communicating with the API -- An Ansible callback plugin to record events as they happen throughout the execution -- An Ansible action module to associate arbitrary key/values to your playbook reports +For the web client interface, see `ara-web `_. Quickstart ========== -Here's how you can get started from scratch with default settings: +Here's how you can get started from scratch with sane defaults: .. code-block:: bash - # Create a virtual environment and activate it so we don't conflict + # Create a python3 virtual environment and activate it so we don't conflict # with system or distribution packages python3 -m venv ~/.ara/virtualenv source ~/.ara/virtualenv/bin/activate # Install Ansible, ARA and it's API server dependencies - pip install ansible git+https://github.com/ansible-community/ara@feature/1.0[server] + pip install ansible ara[server] # Tell Ansible to use the ARA callback plugin export ANSIBLE_CALLBACK_PLUGINS="$(python -m ara.setup.callback_plugins)" - # Run your playbook as your normally would + # Run your playbook as usual ansible-playbook playbook.yml -The data will be saved in real time throughout the execution of the Ansible playbook. +If nothing went wrong, your playbook data should have been saved in a local +database at ``~/.ara/server/ansible.sqlite``. -What happens behind the scenes is that the ARA Ansible callback plugin used -the built-in API client to send the data to the API which then saved it to a -database located by default at ``~/.ara/server/ansible.sqlite``. +You can browse this data through the API by executing ``ara-manage runserver`` +and pointing your browser at http://127.0.0.1:8000/. -You're now ready to start poking at the API with the built-in -`API clients `_ ! +That's it ! -If you'd like to have the ARA web reporting interface, take a look at -`ara-web `_. +Live demos +========== + +You can find live demos deployed by the built-in ara_api_ and ara_web_ Ansible +roles at https://api.demo.recordsansible.org and https://web.demo.recordsansible.org. + +.. _ara_api: https://ara.readthedocs.io/en/feature-1.0/ansible-role-ara-api.html +.. _ara_web: https://ara.readthedocs.io/en/feature-1.0/ansible-role-ara-web.html Documentation ============= -Documentation for installing, configuring, running and using ara is +Documentation for installing, configuring, running and using ARA 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. +- Bugs, issues and enhancements: https://github.com/ansible-community/ara/issues +- IRC: #ara on `Freenode `_ +- Slack: https://arecordsansible.slack.com (`invitation link `_) -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 and testing -======================= - -.. code-block:: bash - - # Retrieve the source and check out the 1.0 branch - git clone https://github.com/ansible-community/ara - cd ara - git checkout feature/1.0 - - # Install tox from pip or from your distro packages - pip install tox - - # Run Ansible integration tests with the latest version of Ansible - tox -e ansible-integration - - # Run integration tests with a specific version of Ansible - # Note: tox will always use the latest version of Ansible to run the playbook which runs the tests. - # For example, if the latest version of Ansible is 2.7.9, it will use Ansible 2.7.9 - # to install Ansible==2.6.15 in a virtual environment and 2.6.15 is what will be tested. - tox -e ansible-integration -- -e ara_tests_ansible_version=2.6.15 - - # Run integration tests with Ansible from source - tox -e ansible-integration -- -e "ara_tests_ansible_name=git+https://github.com/ansible/ansible" - - # Run unit tests - tox -e py3 - - # Run linters (pep8, black, isort) - tox -e linters - - # Run test server -> http://127.0.0.1:8000/api/v1/ - tox -e runserver - - # Build docs - tox -e docs +- Website and blog: https://ara.recordsansible.org +- Twitter: https://twitter.com/arecordsansible Contributors ============ -See contributors on GitHub_. - -.. _GitHub: https://github.com/ansible-community/ara/graphs/contributors +See contributors on `GitHub `_. Copyright =========