ef0b46adbb
This adds support for deploying the ARA API server with an optional nginx frontend on EL8. It also sets up integration test jobs to make sure we test it. Change-Id: I7ce026667ea85d8c59e4910572a34d29f78a8dca
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/>.
|