Add README for collection and markdownify role READMEs

Ansible galaxy doesn't support READMEs in .rst right now and so we need
markdown files instead.

Change-Id: Id4ffbe157f6787ef0f811ffde9e6964d6f992a3b
This commit is contained in:
David Moreau Simard 2020-07-01 14:28:49 -04:00
parent 90ff2c9925
commit a327ed9ba7
No known key found for this signature in database
GPG Key ID: 7D4729EC4E64E8B7
10 changed files with 282 additions and 298 deletions

68
README.md Normal file
View File

@ -0,0 +1,68 @@
# ara-collection
Opinionated collection of Ansible roles for deploying and configuring
[ARA Records Ansible](https://github.com/ansible-community/ara).
ARA Records Ansible playbooks and makes them easier to understand and troubleshoot.
![ara](doc/source/_static/ara-with-icon.png)
## ara_api
![ara_api](doc/source/_static/ansible-role-ara-api.png)
A role to install and run the ARA API server and built-in reporting interface
in various supported configurations.
Documentation: [roles/ara_api/README.md](roles/ara_api/README.md)
## ara_web
![ara_web](doc/source/_static/ansible-role-ara-web.png)
Documentation: [roles/ara_web/README.md](roles/ara_web/README.md)
## ara_frontend_nginx
A role that sets up a basic nginx reverse proxy for serving the API server as
well as ara-web.
Documentation: [roles/ara_frontend_nginx/README.md](roles/ara_frontend_nginx/README.md)
# Community and getting help
- Bugs, issues and enhancements: https://github.com/ansible-community/ara-collection/issues
- IRC: #ara on [Freenode](https://webchat.freenode.net/?channels=#ara)
- Slack: https://arecordsansible.slack.com ([invitation link](https://join.slack.com/t/arecordsansible/shared_invite/enQtMjMxNzI4ODAxMDQxLTU2NTU3YjMwYzRlYmRkZTVjZTFiOWIxNjE5NGRhMDQ3ZTgzZmQyZTY2NzY5YmZmNDA5ZWY4YTY1Y2Y1ODBmNzc))
- Website and blog: https://ara.recordsansible.org
- Twitter: https://twitter.com/arecordsansible
# 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
Contributors to the project can be viewed on [GitHub](https://github.com/ansible-community/ara-collection/graphs/contributors).
# Copyright
```
Copyright (c) 2020 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/>.
```

Binary file not shown.

After

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

90
roles/ara_api/README.md Normal file
View File

@ -0,0 +1,90 @@
# Ansible role: ara_api
![ara_api](../../doc/source/_static/ansible-role-ara-api.png)
This Ansible role provides a framework for installing one or many instances of the
[ARA](https://github.com/ansible-community/ara) API Server in a variety of
opinionated deployment topologies.
It is currently tested and supported against Ubuntu 18.04, Fedora 30 and CentOS 8.
## Role Variables
See [defaults/main.yaml](https://github.com/ansible-community/ara-collection/blob/master/roles/ara_api/defaults/main.yaml).
## TL;DR
Playbook that runs the role with defaults:
```yaml
- name: Install ARA with default settings and no persistent API server
hosts: all
gather_facts: yes
roles:
- ara_api
```
What the role ends up doing by default:
- Installs required packages (``git``, ``virtualenv``, etc.) if superuser privileges are available
- Stores everything in the home directory of the user in ``~/.ara``
- Retrieves ARA from source
- Installs ARA in a virtualenv
- Generates a random secret key if none are already configured or provided
- Sets up API configuration in ``~/.ara/server/settings.yaml``
- Runs the API SQL migrations (``ara-manage migrate``)
## About deployment topologies
This Ansible role is designed to support different opinionated topologies that
can be selected with role variables.
For example, the following role variables are used to provide the topology from
the ``TL;DR`` above:
- ``ara_api_install_method: source``
- ``ara_api_wsgi_server: null``
- ``ara_api_database_engine: django.db.backends.sqlite3``
- ``ara_api_web_server: null``
The intent is that as the role gains support for other install methods,
wsgi servers, database engines or web servers, it will be possible to
mix and match according to preference or requirements.
Perhaps ARA could be installed from pypi and run with gunicorn, nginx and mysql.
Or maybe it could be installed from distribution packages and set up to run
with apache, mod_wsgi and postgresql.
Or any combination of any of those.
## Example playbooks
Install ARA and set up the API to be served by a persistent gunicorn service:
```yaml
- name: Install ARA and set up the API to be served by gunicorn
hosts: all
gather_facts: yes
vars:
ara_api_wsgi_server: gunicorn
roles:
- ara_api
```
Install ARA and set up the API to be served by nginx in front of gunicorn:
```yaml
# Requires superuser privileges to set up nginx and the ara-api service
# The API will be reachable at http://api.ara.example.org
- name: Install ARA and set up the API to be served by nginx in front of gunicorn
hosts: all
gather_facts: yes
vars:
ara_api_frontend_server: nginx
ara_api_wsgi_server: gunicorn
ara_api_fqdn: api.ara.example.org
ara_api_allowed_hosts:
- api.ara.example.org
ara_api_frontend_vhost: custom_vhost.conf.j2
roles:
- ara_api
```

View File

@ -1,121 +0,0 @@
ansible-role-ara-api
====================
.. image:: ../../doc/source/_static/ansible-role-ara-api.png
This Ansible role provides a framework for installing one or many instances of
`ARA Records Ansible <https://github.com/ansible-community/ara>`_ in a variety of
opinionated deployment topologies.
It is currently tested and supported against Ubuntu 18.04, Fedora 30 and CentOS 8.
Role Variables
--------------
See `defaults/main.yaml <https://github.com/ansible-community/ara/blob/master/roles/ara_api/defaults/main.yaml>`_.
.. literalinclude:: ../../roles/ara_api/defaults/main.yaml
:language: yaml+jinja
:start-after: www.gnu.org
TL;DR
-----
Playbook that runs the role with defaults:
.. code-block:: yaml+jinja
- name: Install ARA with default settings and no persistent API server
hosts: all
gather_facts: yes
roles:
- ara_api
What the role ends up doing by default:
- Installs required packages (``git``, ``virtualenv``, etc.) if superuser privileges are available
- Stores everything in the home directory of the user in ``~/.ara``
- Retrieves ARA from source
- Installs ARA in a virtualenv
- Generates a random secret key if none are already configured or provided
- Sets up API configuration in ``~/.ara/server/settings.yaml``
- Runs the API SQL migrations (``ara-manage migrate``)
About deployment topologies
---------------------------
This Ansible role is designed to support different opinionated topologies that
can be selected with role variables.
For example, the following role variables are used to provide the topology from
the ``TL;DR`` above:
- ``ara_api_install_method: source``
- ``ara_api_wsgi_server: null``
- ``ara_api_database_engine: django.db.backends.sqlite3``
- ``ara_api_web_server: null``
The intent is that as the role gains support for other install methods,
wsgi servers, database engines or web servers, it will be possible to
mix and match according to preference or requirements.
Perhaps ARA could be installed from pypi and run with gunicorn, nginx and mysql.
Or maybe it could be installed from distribution packages and set up to run
with apache, mod_wsgi and postgresql.
Or any combination of any of those.
Example playbooks
-----------------
Install ARA and set up the API to be served by a persistent gunicorn service:
.. code-block:: yaml+jinja
- name: Install ARA and set up the API to be served by gunicorn
hosts: all
gather_facts: yes
vars:
ara_api_wsgi_server: gunicorn
roles:
- ara_api
Install ARA and set up the API to be served by nginx in front of gunicorn:
.. code-block:: yaml+jinja
# Requires superuser privileges to set up nginx and the ara-api service
# The API will be reachable at http://api.ara.example.org
- name: Install ARA and set up the API to be served by nginx in front of gunicorn
hosts: all
gather_facts: yes
vars:
ara_api_frontend_server: nginx
ara_api_wsgi_server: gunicorn
ara_api_fqdn: api.ara.example.org
ara_api_allowed_hosts:
- api.ara.example.org
ara_api_frontend_vhost: custom_vhost.conf.j2
roles:
- ara_api
.. _include_delimiter_end:
Copyright
---------
.. code-block:: text
Copyright (c) 2019 Red Hat, Inc.
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/>.

View File

@ -0,0 +1,44 @@
# Ansible role: ara_frontend_nginx
A role for deploying a minimal installation of nginx for ara-api and ara-web.
This role is not meant to be used on it's own, it should be included by the
``ara_api`` and ``ara_web`` roles in order to have the necessary variables
available.
It is currently tested and supported against Ubuntu 18.04 and Fedora 29.
## Role Variables
- ``ara_api_frontend_vhost``: Path to a custom nginx vhost configuration file for ara-api.
- ``ara_web_frontend_vhost``: Path to a custom nginx vhost configuration file for ara-web.
## Example playbooks
Install ARA and set up the API to be served by nginx with a custom vhost configuration
in front of gunicorn:
```yaml
# The API will be reachable at http://api.ara.example.org
# The web interface will be reachable at http://web.ara.example.org
# The web interface will be set up to query api.ara.example.org.
- name: Deploy ARA API server and web interface
hosts: all
gather_facts: yes
vars:
# ara_api
ara_api_frontend_server: nginx
ara_api_wsgi_server: gunicorn
ara_api_fqdn: api.ara.example.org
ara_api_allowed_hosts:
- api.ara.example.org
ara_api_frontend_vhost: custom_api_vhost.conf.j2
# ara_web
ara_web_fqdn: web.ara.example.org
ara_web_api_endpoint: "http://api.ara.example.org"
ara_web_frontend_server: nginx
ara_web_frontend_vhost: custom_web_vhost.conf.j2
roles:
- ara_api
- ara_web
```

View File

@ -1,65 +0,0 @@
ansible-role-ara-frontend-nginx
===============================
A role for deploying a minimal installation of nginx for ara-api and ara-web.
This role is not meant to be used on it's own, it should be included by the
``ara_api`` and ``ara_web`` roles in order to have the necessary variables
available.
It is currently tested and supported against Ubuntu 18.04 and Fedora 29.
Role Variables
--------------
- ``ara_api_frontend_vhost``: Path to a custom nginx vhost configuration file for ara-api.
- ``ara_web_frontend_vhost``: Path to a custom nginx vhost configuration file for ara-web.
Example playbooks
-----------------
Install ARA and set up the API to be served by nginx with a custom vhost configuration
in front of gunicorn::
# The API will be reachable at http://api.ara.example.org
# The web interface will be reachable at http://web.ara.example.org
# The web interface will be set up to query api.ara.example.org.
- name: Deploy ARA API server and web interface
hosts: all
gather_facts: yes
vars:
# ara_api
ara_api_frontend_server: nginx
ara_api_wsgi_server: gunicorn
ara_api_fqdn: api.ara.example.org
ara_api_allowed_hosts:
- api.ara.example.org
ara_api_frontend_vhost: custom_api_vhost.conf.j2
# ara_web
ara_web_fqdn: web.ara.example.org
ara_web_api_endpoint: "http://api.ara.example.org"
ara_web_frontend_server: nginx
ara_web_frontend_vhost: custom_web_vhost.conf.j2
roles:
- ara_api
- ara_web
Copyright
---------
::
Copyright (c) 2019 Red Hat, Inc.
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/>.

80
roles/ara_web/README.md Normal file
View File

@ -0,0 +1,80 @@
# Ansible role: ara_web
![ara_web](../../doc/source/_static/ansible-role-ara-web.png)
This Ansible role provides a framework for installing one or many instances of
[ara-web](https://github.com/ansible-community/ara-web) in a variety of
opinionated deployment topologies.
It is currently tested and supported against Ubuntu 18.04 and Fedora 29.
## Role Variables
See [defaults/main.yaml](https://github.com/ansible-community/ara-collection/blob/master/roles/ara_web/defaults/main.yaml).
## TL;DR
This is what the role does by default out of the box:
- Retrieves ara-web from source
- Installs nodejs LTS (v10)
- Installs ara-web dependencies with npm
- Configures an ara-server API endpoint in ara-web's ``public/config.json`` file
- Sets up a systemd unit file for running ara-web with the embedded development server
## About deployment topologies
This Ansible role is designed to support different opinionated topologies that
can be selected with role variables.
For example, the following role variables are defaults used to provide the
topology from the ``TL;DR`` above:
- ``ara_web_install_method: source``
- ``ara_web_dev_server: true``
- ``ara_web_frontend_server: null``
The intent is that as the role gains support for other install methods or
frontend servers, it will be possible to mix and match according to preference
or requirements.
## Example playbooks
Deploy the ARA API and web client on the same machine with defaults:
```yaml
- name: Deploy ARA API and web client
hosts: all
gather_facts: yes
vars:
# ara_api
ara_api_fqdn: api.ara.example.org
ara_api_wsgi_server: gunicorn
ara_api_allowed_hosts:
- api.ara.example.org
ara_api_cors_origin_whitelist:
- "http://web.ara.example.org"
# ara_web
ara_web_fqdn: web.ara.example.org
ara_web_frontend_server: nginx
ara_web_api_endpoint: "http://api.ara.example.org"
roles:
- ara_api
- ara_web
```
Deploy only ara-web behind nginx and point it to a remote API endpoint:
```yaml
# Note: Don't forget to add the web fqdn in the remote cors_origin_whitelist.
# Otherwise, the web client might not be authorized to query the API.
- name: Deploy ara-web for remote API endpoint
hosts: all
gather_facts: yes
vars:
ara_web_fqdn: web.ara.example.org
ara_web_api_endpoint: "http://api.remoteara.example.org"
ara_web_frontend_server: nginx
ara_web_frontend_vhost: custom-web-vhost.conf.j2
roles:
- ara_web

View File

@ -1,112 +0,0 @@
ansible-role-ara-web
====================
.. image:: ../../doc/source/_static/ansible-role-ara-web.png
This Ansible role provides a framework for installing one or many instances of
`ara-web <https://github.com/ansible-community/ara-web>`_ in a variety of
opinionated deployment topologies.
It is currently tested and supported against Ubuntu 18.04 and Fedora 29.
Role Variables
--------------
See `defaults/main.yaml <https://github.com/ansible-community/ara/blob/master/roles/ara_web/defaults/main.yaml>`_.
.. literalinclude:: ../../roles/ara_web/defaults/main.yaml
:language: yaml+jinja
:start-after: www.gnu.org
TL;DR
------
This is what the role does by default out of the box:
- Retrieves ara-web from source
- Installs nodejs LTS (v10)
- Installs ara-web dependencies with npm
- Configures an ara-server API endpoint in ara-web's ``public/config.json`` file
- Sets up a systemd unit file for running ara-web with the embedded development server
About deployment topologies
---------------------------
This Ansible role is designed to support different opinionated topologies that
can be selected with role variables.
For example, the following role variables are defaults used to provide the
topology from the ``TL;DR`` above:
- ``ara_web_install_method: source``
- ``ara_web_dev_server: true``
- ``ara_web_frontend_server: null``
The intent is that as the role gains support for other install methods or
frontend servers, it will be possible to mix and match according to preference
or requirements.
Example playbooks
-----------------
Deploy the ARA API and web client on the same machine with defaults:
.. code-block:: yaml+jinja
- name: Deploy ARA API and web client
hosts: all
gather_facts: yes
vars:
# ara_api
ara_api_fqdn: api.ara.example.org
ara_api_wsgi_server: gunicorn
ara_api_allowed_hosts:
- api.ara.example.org
ara_api_cors_origin_whitelist:
- "http://web.ara.example.org"
# ara_web
ara_web_fqdn: web.ara.example.org
ara_web_frontend_server: nginx
ara_web_api_endpoint: "http://api.ara.example.org"
roles:
- ara_api
- ara_web
Deploy only ara-web behind nginx and point it to a remote API endpoint:
.. code-block:: yaml+jinja
# Note: Don't forget to add the web fqdn in the remote cors_origin_whitelist.
# Otherwise, the web client might not be authorized to query the API.
- name: Deploy ara-web for remote API endpoint
hosts: all
gather_facts: yes
vars:
ara_web_fqdn: web.ara.example.org
ara_web_api_endpoint: "http://api.remoteara.example.org"
ara_web_frontend_server: nginx
ara_web_frontend_vhost: custom-web-vhost.conf.j2
roles:
- ara_web
.. _include_delimiter_end:
Copyright
---------
::
Copyright (c) 2019 Red Hat, Inc.
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/>.