# ARA Records Ansible
ARA Records Ansible and makes it easier to understand and troubleshoot.
It is another recursive acronym with a focus on simplicity.
## About ara
ara provides Ansible reporting by recording ``ansible`` and ``ansible-playbook`` commands regardless of how and where they run:
- from most Linux distributions and even on Mac OS (as long as ``python >= 3.8`` is available)
- from tools that run Ansible like ansible-(pull|test|runner|navigator), AWX & Automation Controller (Tower), Molecule and Semaphore
- from a terminal, a script or by hand
- from a laptop, desktop, server, virtual machine, container or execution environment
- from CI/CD platforms such as Jenkins, Rundeck and Zuul
- from git forges like GitHub, GitLab, Gitea & Forgejo
The recorded results are available via an included CLI, a REST API as well as a self-hosted, local-first web reporting interface.
<!-- https://github.com/ansible-community/ara/blob/master/doc/source/_static/demo.mp4 -->
https://github.com/ansible-community/ara/assets/1291204/4fbdf5f7-509c-46ea-beb0-726b43e1b985
## How it works
ARA Records Ansible results to SQLite, MySQL and PostgreSQL databases with a standard [callback plugin](https://docs.ansible.com/ansible/latest/plugins/callback.html).
This plugin gathers data as Ansible runs and sends it to a Django REST API server:
## Requirements
- Any recent Linux distribution or Mac OS with python >=3.8 available
- The ara package (containing the Ansible plugins) must be installed for the same python interpreter as Ansible itself
## Getting started
For production use, consider learning about [best practices](https://ara.readthedocs.io/en/latest/troubleshooting.html#improving-playbook-recording-performance), [enabling authentication](https://ara.readthedocs.io/en/latest/api-security.html#authentication) and [ignoring what doesn't need to be recorded](https://ara.readthedocs.io/en/latest/ansible-plugins-and-use-cases.html#ansible-plugins).
### Recording playbooks without an API server
ara records to a local sqlite database by default and does not require a persistent server:
```bash
# Install ansible (or ansible-core) with ara (including API server dependencies)
python3 -m pip install --user ansible "ara[server]"
# Configure Ansible to enable ara
export ANSIBLE_CALLBACK_PLUGINS="$(python3 -m ara.setup.callback_plugins)"
# Run an Ansible playbook as usual
ansible-playbook playbook.yml
# Check out the CLI
ara playbook list
ara host list
# or the UI at http://127.0.0.1:8000
ara-manage runserver
```
### Recording playbooks with an API server
The server includes a REST API as well a web reporting interface.
Consider running one to aggregate playbook runs from different tools, jobs or servers into a single dashboard that can be shared with friends.
Get started with the [ara_api role](https://github.com/ansible-community/ara-collection/blob/master/roles/ara_api/README.md)
or with the [container images](https://ara.readthedocs.io/en/latest/container-images.html) published by the project on
[DockerHub](https://hub.docker.com/r/recordsansible/ara-api) and [quay.io](https://quay.io/repository/recordsansible/ara-api):
```bash
# Create a directory for a volume to store settings and a sqlite database
mkdir -p ~/.ara/server
# Start an API server with docker from the image on DockerHub:
docker run --name api-server --detach --tty \
--volume ~/.ara/server:/opt/ara -p 8000:8000 \
docker.io/recordsansible/ara-api:latest
# or with podman from the image on quay.io:
podman run --name api-server --detach --tty \
--volume ~/.ara/server:/opt/ara -p 8000:8000 \
quay.io/recordsansible/ara-api:latest
```
Once the server is running, ara must be installed and configured to send data to it:
```bash
# Install ansible (or ansible-core) with ara (excluding API server dependencies)
python3 -m pip install --user ansible ara
# Configure Ansible to enable ara
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 as usual
ansible-playbook playbook.yml
# Check out the CLI
ara playbook list
ara host list
# Or browse http://127.0.0.1:8000 (running from the container)
```
## Live demo
A live demo is deployed with the ara Ansible collection from [Ansible Galaxy](https://galaxy.ansible.com/recordsansible/ara).
It is available at https://demo.recordsansible.org.
## Documentation and changelog
Documentation for installing, configuring, running and using ara is available on [ara.readthedocs.io](https://ara.readthedocs.io).
Common issues may be resolved by reading the [troubleshooting guide](https://ara.readthedocs.io/en/latest/troubleshooting.html).
Changelog and release notes are available within the repository's [git tags](https://github.com/ansible-community/ara/tags) as well as the [documentation](https://ara.readthedocs.io/en/latest/changelog-release-notes.html).
## Community and getting help
- Bugs, issues and enhancements: https://github.com/ansible-community/ara/issues
- IRC: #ara on [Libera.chat](https://web.libera.chat/?channels=#ara)
- Matrix: Bridged from IRC via [#ara:libera.chat](https://matrix.to/#/#ara:libera.chat)
- Slack: Bridged from IRC via [https://arecordsansible.slack.com](https://join.slack.com/t/arecordsansible/shared_invite/enQtMjMxNzI4ODAxMDQxLTU2NTU3YjMwYzRlYmRkZTVjZTFiOWIxNjE5NGRhMDQ3ZTgzZmQyZTY2NzY5YmZmNDA5ZWY4YTY1Y2Y1ODBmNzc>)
- Website and blog: https://ara.recordsansible.org
- ~~Twitter: https://twitter.com/recordsansible~~
- Mastodon: https://fosstodon.org/@ara
## Contributing
Contributions to the project are welcome and appreciated !
Get started with the [contributor's documentation](https://ara.readthedocs.io/en/latest/contributing.html).
## Authors
Code contributions to the project can be viewed from the git log or on [GitHub](https://github.com/ansible-community/ara/graphs/contributors).
The ara parrot logo was designed and contributed by [Jason E. Rist](https://github.com/ansible-community/ara/commit/0d5d0939a6b7a319d99acc1fb20d4ca282bd76ab).
## Copyright
```
Copyright (c) 2023 The ARA Records Ansible authors
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
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
ARA Records Ansible is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
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/>.
```
Raw data
{
"_id": null,
"home_page": "https://github.com/ansible-community/ara",
"name": "ara",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "ARA Records Ansible Authors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/32/c2/6311b6b9d2a4958cd5ec03160a579f6503dd85b47a76899d9b2aeca508c8/ara-1.7.2.tar.gz",
"platform": null,
"description": "# ARA Records Ansible\n\nARA Records Ansible and makes it easier to understand and troubleshoot.\n\n\n\nIt is another recursive acronym with a focus on simplicity.\n\n## About ara\n\nara provides Ansible reporting by recording ``ansible`` and ``ansible-playbook`` commands regardless of how and where they run:\n\n- from most Linux distributions and even on Mac OS (as long as ``python >= 3.8`` is available)\n- from tools that run Ansible like ansible-(pull|test|runner|navigator), AWX & Automation Controller (Tower), Molecule and Semaphore\n- from a terminal, a script or by hand\n- from a laptop, desktop, server, virtual machine, container or execution environment\n- from CI/CD platforms such as Jenkins, Rundeck and Zuul\n- from git forges like GitHub, GitLab, Gitea & Forgejo\n\nThe recorded results are available via an included CLI, a REST API as well as a self-hosted, local-first web reporting interface.\n\n<!-- https://github.com/ansible-community/ara/blob/master/doc/source/_static/demo.mp4 -->\nhttps://github.com/ansible-community/ara/assets/1291204/4fbdf5f7-509c-46ea-beb0-726b43e1b985\n\n## How it works\n\nARA Records Ansible results to SQLite, MySQL and PostgreSQL databases with a standard [callback plugin](https://docs.ansible.com/ansible/latest/plugins/callback.html).\n\nThis plugin gathers data as Ansible runs and sends it to a Django REST API server:\n\n\n\n## Requirements\n\n- Any recent Linux distribution or Mac OS with python >=3.8 available\n- The ara package (containing the Ansible plugins) must be installed for the same python interpreter as Ansible itself\n\n## Getting started\n\nFor production use, consider learning about [best practices](https://ara.readthedocs.io/en/latest/troubleshooting.html#improving-playbook-recording-performance), [enabling authentication](https://ara.readthedocs.io/en/latest/api-security.html#authentication) and [ignoring what doesn't need to be recorded](https://ara.readthedocs.io/en/latest/ansible-plugins-and-use-cases.html#ansible-plugins).\n\n### Recording playbooks without an API server\n\nara records to a local sqlite database by default and does not require a persistent server:\n\n```bash\n# Install ansible (or ansible-core) with ara (including API server dependencies)\npython3 -m pip install --user ansible \"ara[server]\"\n\n# Configure Ansible to enable ara\nexport ANSIBLE_CALLBACK_PLUGINS=\"$(python3 -m ara.setup.callback_plugins)\"\n\n# Run an Ansible playbook as usual\nansible-playbook playbook.yml\n\n# Check out the CLI\nara playbook list\nara host list\n\n# or the UI at http://127.0.0.1:8000\nara-manage runserver\n```\n\n\n\n### Recording playbooks with an API server\n\nThe server includes a REST API as well a web reporting interface.\n\nConsider running one to aggregate playbook runs from different tools, jobs or servers into a single dashboard that can be shared with friends.\n\nGet started with the [ara_api role](https://github.com/ansible-community/ara-collection/blob/master/roles/ara_api/README.md)\nor with the [container images](https://ara.readthedocs.io/en/latest/container-images.html) published by the project on\n[DockerHub](https://hub.docker.com/r/recordsansible/ara-api) and [quay.io](https://quay.io/repository/recordsansible/ara-api):\n\n```bash\n# Create a directory for a volume to store settings and a sqlite database\nmkdir -p ~/.ara/server\n\n# Start an API server with docker from the image on DockerHub:\ndocker run --name api-server --detach --tty \\\n --volume ~/.ara/server:/opt/ara -p 8000:8000 \\\n docker.io/recordsansible/ara-api:latest\n\n# or with podman from the image on quay.io:\npodman run --name api-server --detach --tty \\\n --volume ~/.ara/server:/opt/ara -p 8000:8000 \\\n quay.io/recordsansible/ara-api:latest\n```\n\nOnce the server is running, ara must be installed and configured to send data to it:\n\n```bash\n# Install ansible (or ansible-core) with ara (excluding API server dependencies)\npython3 -m pip install --user ansible ara\n\n# Configure Ansible to enable ara\nexport ANSIBLE_CALLBACK_PLUGINS=\"$(python3 -m ara.setup.callback_plugins)\"\n\n# Set up the ara callback to know where the API server is located\nexport ARA_API_CLIENT=\"http\"\nexport ARA_API_SERVER=\"http://127.0.0.1:8000\"\n\n# Run an Ansible playbook as usual\nansible-playbook playbook.yml\n\n# Check out the CLI\nara playbook list\nara host list\n\n# Or browse http://127.0.0.1:8000 (running from the container)\n```\n\n## Live demo\n\nA live demo is deployed with the ara Ansible collection from [Ansible Galaxy](https://galaxy.ansible.com/recordsansible/ara).\n\nIt is available at https://demo.recordsansible.org.\n\n## Documentation and changelog\n\nDocumentation for installing, configuring, running and using ara is available on [ara.readthedocs.io](https://ara.readthedocs.io).\n\nCommon issues may be resolved by reading the [troubleshooting guide](https://ara.readthedocs.io/en/latest/troubleshooting.html).\n\nChangelog and release notes are available within the repository's [git tags](https://github.com/ansible-community/ara/tags) as well as the [documentation](https://ara.readthedocs.io/en/latest/changelog-release-notes.html).\n\n## Community and getting help\n\n- Bugs, issues and enhancements: https://github.com/ansible-community/ara/issues\n- IRC: #ara on [Libera.chat](https://web.libera.chat/?channels=#ara)\n- Matrix: Bridged from IRC via [#ara:libera.chat](https://matrix.to/#/#ara:libera.chat)\n- Slack: Bridged from IRC via [https://arecordsansible.slack.com](https://join.slack.com/t/arecordsansible/shared_invite/enQtMjMxNzI4ODAxMDQxLTU2NTU3YjMwYzRlYmRkZTVjZTFiOWIxNjE5NGRhMDQ3ZTgzZmQyZTY2NzY5YmZmNDA5ZWY4YTY1Y2Y1ODBmNzc>)\n- Website and blog: https://ara.recordsansible.org\n- ~~Twitter: https://twitter.com/recordsansible~~\n- Mastodon: https://fosstodon.org/@ara\n\n## Contributing\n\nContributions to the project are welcome and appreciated !\n\nGet started with the [contributor's documentation](https://ara.readthedocs.io/en/latest/contributing.html).\n\n## Authors\n\nCode contributions to the project can be viewed from the git log or on [GitHub](https://github.com/ansible-community/ara/graphs/contributors).\n\nThe ara parrot logo was designed and contributed by [Jason E. Rist](https://github.com/ansible-community/ara/commit/0d5d0939a6b7a319d99acc1fb20d4ca282bd76ab).\n\n## Copyright\n\n```\nCopyright (c) 2023 The ARA Records Ansible authors\n\nARA Records Ansible is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nARA Records Ansible is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with ARA Records Ansible. If not, see <http://www.gnu.org/licenses/>.\n```\n\n",
"bugtrack_url": null,
"license": null,
"summary": "ARA Records Ansible",
"version": "1.7.2",
"project_urls": {
"Homepage": "https://github.com/ansible-community/ara"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2e37111b1b55cb5c81de0cae15b6c8fdea9aedf3eeb21fb880823b7b89f4bbf3",
"md5": "c3b952852eeb9c3eb3bc42cb29da5669",
"sha256": "18f0e98c2d8d0913e5a3df6cd166b7c0a856611ce675ec494bfbb957f78f264f"
},
"downloads": -1,
"filename": "ara-1.7.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c3b952852eeb9c3eb3bc42cb29da5669",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 233748,
"upload_time": "2024-09-04T11:59:28",
"upload_time_iso_8601": "2024-09-04T11:59:28.572743Z",
"url": "https://files.pythonhosted.org/packages/2e/37/111b1b55cb5c81de0cae15b6c8fdea9aedf3eeb21fb880823b7b89f4bbf3/ara-1.7.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "32c26311b6b9d2a4958cd5ec03160a579f6503dd85b47a76899d9b2aeca508c8",
"md5": "e0711d2f21f62fbc64cf83d6e3e6cde5",
"sha256": "16d4f5cee550c23efda83d3e1fa9b48a67af3db37741c14a9e99dc4c2cefc7c8"
},
"downloads": -1,
"filename": "ara-1.7.2.tar.gz",
"has_sig": false,
"md5_digest": "e0711d2f21f62fbc64cf83d6e3e6cde5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12925821,
"upload_time": "2024-09-04T11:59:35",
"upload_time_iso_8601": "2024-09-04T11:59:35.332207Z",
"url": "https://files.pythonhosted.org/packages/32/c2/6311b6b9d2a4958cd5ec03160a579f6503dd85b47a76899d9b2aeca508c8/ara-1.7.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-04 11:59:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ansible-community",
"github_project": "ara",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "pbr",
"specs": [
[
"!=",
"2.1.0"
],
[
">=",
"2.0.0"
]
]
},
{
"name": "cliff",
"specs": []
},
{
"name": "requests",
"specs": [
[
">=",
"2.14.2"
]
]
}
],
"tox": true,
"lcname": "ara"
}
JSON
