Browse Source

website: Align index content with the project README

We should have a great README and there is no need for the project home
page to have different content.

Change-Id: I53e48f10ab9c833f09f8392078f837bf49fd8db7
changes/67/776667/2
David Moreau Simard 2 weeks ago
parent
commit
c04b918e60
No known key found for this signature in database GPG Key ID: 7D4729EC4E64E8B7
8 changed files with 144 additions and 131 deletions
  1. +38
    -69
      website/config.toml
  2. +106
    -62
      website/content/_index.md
  3. BIN
      website/content/static/ara-full-logo.png
  4. BIN
      website/content/static/ara-quickstart-default.gif
  5. BIN
      website/content/static/ara-quickstart-server.gif
  6. BIN
      website/content/static/cli-playbook-list.png
  7. BIN
      website/content/static/ui-api-browser.png
  8. BIN
      website/content/static/ui-playbook-details.png

+ 38
- 69
website/config.toml View File

@ -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"

+ 106
- 62
website/content/_index.md View File

@ -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
python3 -m pip install --user ansible "ara[server]"
### Reporting interface
# Tell Ansible to use the ARA callback plugin
export ANSIBLE_CALLBACK_PLUGINS="$(python3 -m ara.setup.callback_plugins)"
A simple reporting interface built-in to the API server without any extra dependencies.
# Run your playbook
ansible-playbook playbook.yml
```
![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)
If nothing went wrong, your playbook data should have been saved in a local
database at ``~/.ara/server/ansible.sqlite``.
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).
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/.
## Getting started
That's it !
### Requirements
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).
- 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
## Live demos
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.
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.
### Recording playbooks without an API server
## ARA is free and open source
With defaults and using a local sqlite database:
ARA is free and open source under the GPLv3 license.
```bash
# Install Ansible and ARA (with API server dependencies) for the current user
python3 -m pip install --user ansible "ara[server]"
# 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).
# Run an Ansible playbook
ansible-playbook playbook.yaml
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).
# Use the CLI to see recorded playbooks
ara playbook list
## ARA is tested, stable and production ready
# Start the built-in development server to browse recorded results
ara-manage runserver
```
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.
### Recording playbooks with an API server
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.
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):
It works.
```bash
# Create a directory for a volume to store settings and a sqlite database
mkdir -p ~/.ara/server
# 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
# 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
```
## ARA is offline and decentralized by default
Once the server is running, ara's Ansible callback plugin must be installed and configured to send data to it:
Running Ansible from your laptop ? No problem.
```bash
# Install Ansible and ARA (without API server dependencies) for the current user
python3 -m pip install --user ansible ara
# Configure Ansible to use the ARA callback plugin
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
ansible-playbook playbook.yaml
# Use the CLI to see recorded playbooks
ara playbook list
```
You can browse your ARA reports locally from a sqlite database without ever leaving the comfort of localhost.
Data will be available on the API server in real time as the playbook progresses and completes.
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).

BIN
website/content/static/ara-full-logo.png View File

Before After
Width: 557  |  Height: 439  |  Size: 50 KiB

BIN
website/content/static/ara-quickstart-default.gif View File

Before After
Width: 835  |  Height: 558  |  Size: 1.6 MiB

BIN
website/content/static/ara-quickstart-server.gif View File

Before After
Width: 835  |  Height: 558  |  Size: 1.7 MiB

BIN
website/content/static/cli-playbook-list.png View File

Before After
Width: 1326  |  Height: 300  |  Size: 98 KiB

BIN
website/content/static/ui-api-browser.png View File

Before After
Width: 549  |  Height: 518  |  Size: 70 KiB

BIN
website/content/static/ui-playbook-details.png View File

Before After
Width: 1098  |  Height: 962  |  Size: 81 KiB

Loading…
Cancel
Save