diff --git a/website/config.toml b/website/config.toml index 54e9f7e..e528aed 100644 --- a/website/config.toml +++ b/website/config.toml @@ -4,83 +4,43 @@ languageCode = "en-us" title = "ARA Records Ansible | ara.recordsansible.org" theme = "hugo-future-imperfect" preserveTaxonomyNames = true -paginate = 5 -disqusShortname = "" -googleAnalytics = "UA-119558821-1" +paginate = 10 pluralizeListTitles = false enableRobotsTXT = true enableGitInfo = true relativeURLs = true [params] - # Sets the meta tag description - description = "ARA Records Ansible playbook runs and makes the recorded data available and intuitive for users and systems." - # Sets the navbarTitle that appears in the top left of the navigation bar - navbarTitle = "ARA Records Ansible" - # Sets where "View More Posts" links - viewMorePostLink = "/blog/" - -# Optional Params - # Sets navbarTitle to match the section of the website - dynamicTitles = false - # Sets RSS icons to appear on the sidebar with the social media buttons - rssAppearAtTop = true - rssAppearAtBottom = true - # Sets Social Media icons to appear on the sidebar - socialAppearAtTop = true - socialAppearAtBottom = true - # Sets Categories to sort by number of posts instead of alphabetical - categoriesByCount = true - # set to show or to hide categories in the sidebar - showSidebarCategories = true - # Sets Estimated Reading Time to appear in post headers - includeReadingTime = true - # Sets the Favicon and Version for the site. Default support is for - # apple-touch-icon-precomposed.png, favicon.png, favicon.ico, and mstile.png. - # These are stored in the favicon folder. See the following for more information: - # https://github.com/audreyr/favicon-cheat-sheet - loadFavicon = true - faviconVersion = "" - # Sets Social Share links to appear on posts - socialShare = false - # Sets specific share to appear on posts (default behavior is to appear) - socialShareTwitter = false - socialShareGoogleplus = false - socialShareFacebook = false - socialShareReddit = false - socialShareLinkedin = false - socialShareStumbleupon = false - socialSharePinterest = false - socialShareEmail = false - - # Load custom CSS or JavaScript files. The variable is an array so that you - # can load multiple files if necessary. You can also load the standard theme - # files by adding the value, "default". - # customCSS = ["default", "/path/to/file"] - # customJS = ["default", "/path/to/file"] - customCSS = ["default"] - customJS = ["default"] - - # options for highlight.js (version, additional languages, and theme) - disable_highlight = false # set to true to disable Highlight - highlightjsVersion = "9.13.1" - highlightjsCDN = "//cdn.bootcss.com" - highlightjsLang = ["r", "yaml", "css"] - highlightjsTheme = "github" + categoriesByCount = true + cssFiles = ["default"] + description = "ARA Records Ansible and makes it easier to understand and troubleshoot." + dynamicTitles = false + enableCDN = false + faviconVersion = "" + hideEmptyStats = false + highlightjsLang = ["bash", "python", "yaml"] + highlightjsTheme = "github" + highlightjs = true + imageStretch = "" + jsFiles = ["default"] + loadFavicon = true + navbarTitle = "ARA Records Ansible" + readingTime = true + removeBlur = false + rssAppearAtBottom = true + rssAppearAtTop = true + showSidebarCategories = true + socialShare = [] + viewMorePostsLink = "/blog/" [permalinks] blog = "/blog/:year/:month/:day/:slug/" [params.intro] - paragraph = "Making your Ansible playbooks easier to understand and troubleshoot." - - # This appears at the top of the sidebar above params.intro.header. - # A width of less than 100px is recommended from a design perspective. + paragraph = "Records Ansible and makes it easier to understand and troubleshoot." [params.intro.pic] src = "static/logo.png" - # Sets Image to be a circle circle = false - # Sets Image to be Future Imperfect's hexagon imperfect = false width = "" alt = "ara.recordsansible.org" @@ -91,7 +51,7 @@ unsafe = true [params.postAmount] # Sets the number of recent posts to show in the sidebar. The default value is 5. - sidebar = 5 + sidebar = 8 # Sets the menu items in the navigation bar # Identifier prepends a Font Awesome icon to the menu item @@ -107,21 +67,30 @@ unsafe = true identifier = "fa fa-newspaper-o" weight = 2 +[[menu.main]] + name = "Code" + url = "https://github.com/ansible-community/ara" + identifier = "fa fa-github" + weight = 3 + [[menu.main]] name = "Documentation" url = "https://ara.readthedocs.io" identifier = "fa fa-book" - weight = 3 + weight = 4 + +[[menu.main]] + name = "Demo" + url = "https://demo.recordsansible.org" + identifier = "fa fa-external-link" + weight = 5 [[menu.main]] name = "Community & Help" url = "/community" identifier = "fa fa-users" - weight = 4 + weight = 6 -# Sets Social Media icons to appear and link to your account. Value should be your -# username unless otherwise noted. These are the icons affected by socialAppearAtTop -# and socialAppearAtBottom. [social] github = "ansible-community/?q=ara" twitter = "RecordsAnsible" diff --git a/website/content/_index.md b/website/content/_index.md index 479ed15..fd5762c 100644 --- a/website/content/_index.md +++ b/website/content/_index.md @@ -2,99 +2,143 @@ kind: home --- -# What's ARA ? +ARA Records Ansible and makes it easier to understand and troubleshoot. -ARA Records Ansible playbooks and makes them easier to understand and troubleshoot. +It's another recursive acronym. -![reports](static/reports.png) +![ara-full-logo](/static/ara-full-logo.png) -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. +## What it does -The [ara](https://github.com/ansible-community/ara) project provides ARA's -Ansible roles and plugins, the REST API server as well as simple built-in web -interfaces to browse the recorded data. +Simple to install and get started, ara provides reporting by saving detailed and +granular results of ``ansible`` and ``ansible-playbook`` commands wherever you run them: -The [ara-web](https://github.com/ansible-community/ara-web) project provides a -stateless javascript client interface to the ARA API. +- by hand or from a script +- from a laptop, a desktop, a container or a server +- for development, CI or production +- from a linux distribution or even on OS X (as long as you have ``python >= 3.5``) +- from tools such as AWX or Tower, Jenkins, GitLab CI, Rundeck, Zuul, Molecule, ansible-pull, ansible-test or ansible-runner -## How does it work ? +By default, ara's Ansible callback plugin will record data to a local sqlite +database without requiring you to run a server or a service: -ARA Records Ansible playbooks through an Ansible -[callback plugin](https://docs.ansible.com/ansible/latest/plugins/callback.html). +![quickstart-default](/static/ara-quickstart-default.gif) + +ara can also provide a single pane of glass when recording data from multiple +locations by pointing the callback plugin to a running API server: + +![quickstart-server](/static/ara-quickstart-server.gif) + +The data is then made available for browsing, searching and querying over the +included reporting interface, a CLI client as well as a REST API. + +## How it works + +ARA Records Ansible execution results to sqlite, mysql or postgresql databases +by using an [Ansible callback plugin](https://docs.ansible.com/ansible/latest/plugins/callback.html). + +This callback plugin leverages built-in python API clients to send data to a +REST API server: ![recording-workflow](/static/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) +## What it looks like -Once the data has been saved in the database, it is made available for query by -the API and web interfaces. +### API browser -## Quickstart +Included by the API server with django-rest-framework, the API browser allows +users to navigate the different API endpoints and query recorded data. -Here's how you can get started from scratch with sane defaults with python>=3.6: +![ui-api-browser](/static/ui-api-browser.png) -``` -# Install ARA and Ansible for the current user +### Reporting interface + +A simple reporting interface built-in to the API server without any extra dependencies. + +![ui-playbook-details](/static/ui-playbook-details.png) + +### ara CLI + +A built-in CLI client for querying and managing playbooks and their recorded data. + +![cli-playbook-list](/static/cli-playbook-list.png) + +The full list of commands, their arguments as well as examples can be found in +the [CLI documentation](https://ara.readthedocs.io/en/latest/cli.html#cli-ara-api-client). + +## Getting started + +### Requirements + +- Any recent Linux distribution or Mac OS with python >=3.5 available +- The ara Ansible plugins must be installed for the same python interpreter as Ansible itself + +For RHEL 7 and CentOS 7 it is recommended to run the API server in a container due to missing or outdated dependencies. +See this [issue](https://github.com/ansible-community/ara/issues/99) for more information. + +### Recording playbooks without an API server + +With defaults and using a local sqlite database: + +```bash +# 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 -ansible-playbook playbook.yml +# Run an Ansible playbook +ansible-playbook playbook.yaml + +# Use the CLI to see recorded playbooks +ara playbook list + +# Start the built-in development server to browse recorded results +ara-manage runserver ``` -If nothing went wrong, your playbook data should have been saved in a local -database at ``~/.ara/server/ansible.sqlite``. +### Recording playbooks with an API server -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/. +You can get an API server deployed using the [ara Ansible collection](https://github.com/ansible-community/ara-collection) +or get started quickly using the container images from [DockerHub](https://hub.docker.com/r/recordsansible/ara-api) and +[quay.io](https://quay.io/repository/recordsansible/ara-api): -That's it ! +```bash +# Create a directory for a volume to store settings and a sqlite database +mkdir -p ~/.ara/server -For more information, refer to the documentation on -[installation](https://ara.readthedocs.io/en/latest/installation.html) and -[configuration](https://ara.readthedocs.io/en/latest/ansible-configuration.html). +# Start an API server with podman from the image on DockerHub: +podman run --name api-server --detach --tty \ + --volume ~/.ara/server:/opt/ara:z -p 8000:8000 \ + docker.io/recordsansible/ara-api:latest -## Live demos +# or with docker from the image on quay.io: +docker run --name api-server --detach --tty \ + --volume ~/.ara/server:/opt/ara:z -p 8000:8000 \ + quay.io/recordsansible/ara-api:latest +``` -You can find live demos deployed by the built-in [ara_api](https://ara.readthedocs.io/en/latest/ansible-role-ara-api.html) -and [ara_web](https://ara.readthedocs.io/en/latest/ansible-role-ara-web.html) -Ansible roles at https://api.demo.recordsansible.org and https://web.demo.recordsansible.org. +Once the server is running, ara's Ansible callback plugin must be installed and configured to send data to it: -## ARA is free and open source +```bash +# Install Ansible and ARA (without API server dependencies) for the current user +python3 -m pip install --user ansible ara -ARA is free and open source under the GPLv3 license. +# Configure Ansible to use the ARA callback plugin +export ANSIBLE_CALLBACK_PLUGINS="$(python3 -m ara.setup.callback_plugins)" -The code review and CI infrastructure is hosted by [OpenDev](https://opendev.org). +# 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" -You can participate in [code reviews](https://review.opendev.org/#/q/project:%255Erecordsansible/.*) -and learn how you can contribute your first patch in the [contributors documentation](https://ara.readthedocs.io/en/latest/contributing.html). +# Run an Ansible playbook +ansible-playbook playbook.yaml -## ARA is tested, stable and production ready +# Use the CLI to see recorded playbooks +ara playbook list +``` -Each new commit to ARA is gated against a series of unit and integration tests -against different Linux distributions and versions of Ansible in order to -prevent regressions. +Data will be available on the API server in real time as the playbook progresses and completes. -ARA is used to record more than a [million playbooks a month](http://superuser.openstack.org/articles/scaling-ara-ansible/) from the OpenStack community alone. - -It works. - -## ARA is offline and decentralized by default - -Running Ansible from your laptop ? No problem. - -You can browse your ARA reports locally from a sqlite database without ever leaving the comfort of localhost. - -Need to aggregate data from multiple locations ? -You can run an API server and hook it up to a database engine like -[PostgreSQL or MySQL](https://ara.readthedocs.io/en/latest/api-configuration.html#ara-database-engine). +You can read more about how container images are built and how to run them in the +[documentation](https://ara.readthedocs.io/en/latest/container-images.html). \ No newline at end of file diff --git a/website/content/static/ara-full-logo.png b/website/content/static/ara-full-logo.png new file mode 100644 index 0000000..1bcc084 Binary files /dev/null and b/website/content/static/ara-full-logo.png differ diff --git a/website/content/static/ara-quickstart-default.gif b/website/content/static/ara-quickstart-default.gif new file mode 100644 index 0000000..051519e Binary files /dev/null and b/website/content/static/ara-quickstart-default.gif differ diff --git a/website/content/static/ara-quickstart-server.gif b/website/content/static/ara-quickstart-server.gif new file mode 100644 index 0000000..85d06e8 Binary files /dev/null and b/website/content/static/ara-quickstart-server.gif differ diff --git a/website/content/static/cli-playbook-list.png b/website/content/static/cli-playbook-list.png new file mode 100644 index 0000000..e6c7fa6 Binary files /dev/null and b/website/content/static/cli-playbook-list.png differ diff --git a/website/content/static/ui-api-browser.png b/website/content/static/ui-api-browser.png new file mode 100644 index 0000000..59435f0 Binary files /dev/null and b/website/content/static/ui-api-browser.png differ diff --git a/website/content/static/ui-playbook-details.png b/website/content/static/ui-playbook-details.png new file mode 100644 index 0000000..bc39b4a Binary files /dev/null and b/website/content/static/ui-playbook-details.png differ