122 lines
3.8 KiB
ReStructuredText
122 lines
3.8 KiB
ReStructuredText
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/>.
|