docs: Refresh install steps in docs and README
- Prefer --user over virtualenv - Move python requirements from faq to installation docs - Mention Fedora and OpenSUSE packages Change-Id: I5f27534500041630209ac0cf449b4f3ce25d7213
This commit is contained in:
David Moreau Simard
23
README.rst
23
README.rst
@@ -8,35 +8,32 @@ ARA Records Ansible playbooks and makes them easier to understand and troublesho
|
||||
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.
|
||||
|
||||
This project provides the ARA API as well as the Ansible components.
|
||||
This project provides ARA's Ansible plugins, the REST API server as well as
|
||||
simple built-in web interfaces to browse the recorded data.
|
||||
|
||||
For the web client interface, see `ara-web <https://github.com/ansible-community/ara-web>`_.
|
||||
A stateless javascript client interface is provided by a different project,
|
||||
`ara-web <https://github.com/ansible-community/ara-web>`_.
|
||||
|
||||
Quickstart
|
||||
==========
|
||||
|
||||
Here's how you can get started from scratch with sane defaults:
|
||||
Here's how you can get started from scratch with sane defaults with python>=3.6:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# 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 ara[server]
|
||||
# Install ARA and Ansible for the current user
|
||||
python3 -m pip install --user ansible "ara[server]"
|
||||
|
||||
# Tell Ansible to use the ARA callback plugin
|
||||
export ANSIBLE_CALLBACK_PLUGINS="$(python -m ara.setup.callback_plugins)"
|
||||
export ANSIBLE_CALLBACK_PLUGINS="$(python3 -m ara.setup.callback_plugins)"
|
||||
|
||||
# Run your playbook as usual
|
||||
# Run your playbook
|
||||
ansible-playbook playbook.yml
|
||||
|
||||
If nothing went wrong, your playbook data should have been saved in a local
|
||||
database at ``~/.ara/server/ansible.sqlite``.
|
||||
|
||||
You can browse this data through the API by executing ``ara-manage runserver``
|
||||
You can take a look at the recorded data by running ``ara-manage runserver``
|
||||
and pointing your browser at http://127.0.0.1:8000/.
|
||||
|
||||
That's it !
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
.. _ansible-configuration:
|
||||
|
||||
Configuring Ansible to use ARA
|
||||
==============================
|
||||
|
||||
|
||||
@@ -57,26 +57,20 @@ What versions of Ansible are supported ?
|
||||
The upstream Ansible community and maintainers provide support for the latest
|
||||
three major stable releases and ARA follows the same support cycle.
|
||||
|
||||
For example, if the latest version of Ansible is 2.8, then the latest release
|
||||
of ARA will support 2.8 as well as 2.7 and 2.6.
|
||||
For example, if the latest version of Ansible is 2.9, then the latest release
|
||||
of ARA will support 2.9 as well as 2.8 and 2.7.
|
||||
|
||||
For more information on Ansible's release and maintenance cycle, you can refer
|
||||
to the `Ansible documentation <https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html>`_.
|
||||
|
||||
If you are using a release of Ansible that is no longer supported, we strongly
|
||||
encourage you to upgrade as soon as possible in order to benefit from the
|
||||
latest features and security fixes.
|
||||
If you are using a release of Ansible that is no longer supported, it doesn't
|
||||
mean that ARA won't work but it will no longer be tested. We strongly encourage
|
||||
you to upgrade as soon as possible in order to benefit from the latest features
|
||||
and security fixes not just in ARA but in Ansible as well.
|
||||
|
||||
Older unsupported versions of Ansible can contain unfixed security
|
||||
vulnerabilities (*CVE*).
|
||||
|
||||
What versions of Python are supported ?
|
||||
---------------------------------------
|
||||
|
||||
Before version 1.0 of ARA, both python2 and python3 were supported.
|
||||
Versions of ARA after 1.0 are not designed to support python2 in consideration
|
||||
that python2 will reach end of life in `January 2020 <https://pythonclock.org/>`_.
|
||||
|
||||
Why ARA instead of <X> ?
|
||||
------------------------
|
||||
|
||||
|
||||
@@ -3,61 +3,91 @@
|
||||
Installing ARA
|
||||
==============
|
||||
|
||||
ARA is packaged on PyPi_ as well as for Fedora_ and OpenSUSE_.
|
||||
|
||||
This documentation covers the two main components in ARA:
|
||||
|
||||
- The Ansible plugins
|
||||
- The API server and the built-in web interface
|
||||
|
||||
See :ref:`ansible-configuration` to enable ARA once it's been installed.
|
||||
|
||||
Instructions for ara-web, a javascript API client interface, are available in
|
||||
the project's `README <https://github.com/ansible-community/ara-web>`_.
|
||||
|
||||
Requirements and dependencies
|
||||
-----------------------------
|
||||
|
||||
ARA should work on any Linux distributions as long as python3 is available.
|
||||
ARA should work on any Linux distribution as long as python3.6 and greater is
|
||||
available.
|
||||
|
||||
Since ARA provides Ansible plugins to record data, it should be installed
|
||||
wherever Ansible is running from so that Ansible can use those plugins.
|
||||
The API server does not require to run on the same machine as Ansible.
|
||||
In order to record data, ARA provides Ansible plugins that must be installed
|
||||
wherever Ansible is running from.
|
||||
|
||||
By default, only the client and plugin dependencies are installed.
|
||||
The main package only installs the API client and Ansible plugin dependencies.
|
||||
This lets users record and send data to a remote API server without requiring
|
||||
that the API server dependencies are installed.
|
||||
|
||||
If you are standing up an API server or if your use case is about recording
|
||||
data locally or offline, the required dependencies can be installed
|
||||
automatically by suffixing ``[server]`` to your pip install commands.
|
||||
When recording data locally using the offline client, the API server does not
|
||||
need to be running but the dependencies must be installed.
|
||||
|
||||
Installing from PyPi or from source
|
||||
-----------------------------------
|
||||
|
||||
First, it is recommended to use a python `virtual environment <https://docs.python.org/3/tutorial/venv.html>`_
|
||||
in order to avoid conflicts with your Linux distribution python packages.
|
||||
.. note::
|
||||
|
||||
.. code-block:: bash
|
||||
When installing from source or from PyPi, it is highly recommended to set up
|
||||
ARA in either:
|
||||
|
||||
python3 -m venv ~/.ara/virtualenv
|
||||
- `user-specific python packages <https://packaging.python.org/tutorials/installing-packages/#installing-to-the-user-site>`_ using ``pip install --user``
|
||||
- a python `virtual environment <https://docs.python.org/3/tutorial/venv.html>`_ using ``python3 -m venv </path/to/venv>``
|
||||
|
||||
This will prevent conflicts with your Linux distribution's python packages.
|
||||
|
||||
To install the latest release of ARA from PyPi_:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# With the API server dependencies
|
||||
~/.ara/virtualenv/bin/pip install "ara[server]"
|
||||
|
||||
# Without the API server dependencies
|
||||
~/.ara/virtualenv/bin/pip install ara
|
||||
pip install --user ara
|
||||
|
||||
# With the API server dependencies
|
||||
pip install --user "ara[server]"
|
||||
|
||||
Installing from source is possible by using the git repository:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Without the API server dependencies
|
||||
pip install --user git+https://github.com/ansible-community/ara
|
||||
|
||||
# With the API server dependencies
|
||||
# (Suffixes don't work when supplying the direct git URL)
|
||||
git clone https://github.com/ansible-community/ara ara-src
|
||||
pip install "./ara-src[server]"
|
||||
pip install --user "./ara-src[server]"
|
||||
|
||||
Installing from Fedora packages
|
||||
-------------------------------
|
||||
|
||||
The install the latest packaged version of ARA for Fedora:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Without the API server dependencies
|
||||
~/.ara/virtualenv/bin/pip install git+https://github.com/ansible-community/ara
|
||||
dnf install ara
|
||||
|
||||
.. _PyPi: https://pypi.org/project/ara/
|
||||
# With the API server dependencies
|
||||
dnf install ara ara-server
|
||||
|
||||
With Ansible roles
|
||||
------------------
|
||||
Installing with Ansible roles
|
||||
-----------------------------
|
||||
|
||||
Two roles are built-in to help users configure their API and web deployments:
|
||||
Two Ansible roles are available to help users configure their API and web
|
||||
deployments:
|
||||
|
||||
- :ref:`ansible-role-ara-api` to install the python parts (Ansible plugins, API server)
|
||||
- :ref:`ansible-role-ara-web` to install the web client (nodejs, react+patternfly)
|
||||
|
||||
.. _PyPi: https://pypi.org/project/ara/
|
||||
.. _Fedora: https://koji.fedoraproject.org/koji/packageinfo?packageID=24394
|
||||
.. _OpenSUSE: https://build.opensuse.org/package/show/devel:languages:python/python-ara
|
||||
|
||||
Reference in New Issue
Block a user