diff --git a/README.rst b/README.rst index 359c2d39..873cb451 100644 --- a/README.rst +++ b/README.rst @@ -25,8 +25,8 @@ Here's how you can get started from scratch with default settings: python3 -m venv ~/.ara/virtualenv source ~/.ara/virtualenv/bin/activate - # Install Ansible and the required ARA projects - pip install ansible git+https://github.com/openstack/ara@feature/1.0 + # Install Ansible, ARA and it's API server dependencies + pip install ansible git+https://github.com/openstack/ara@feature/1.0[server] # Tell Ansible to use the ARA callback plugin export ANSIBLE_CALLBACK_PLUGINS="$(python -m ara.setup.callback_plugins)" diff --git a/ara/clients/offline.py b/ara/clients/offline.py index e3e5142e..1be252eb 100644 --- a/ara/clients/offline.py +++ b/ara/clients/offline.py @@ -22,10 +22,14 @@ import logging import os import threading -from django.core.handlers.wsgi import WSGIHandler -from django.core.servers.basehttp import ThreadedWSGIServer, WSGIRequestHandler - from ara.clients.http import AraHttpClient +from ara.setup.exceptions import MissingDjangoException + +try: + from django.core.handlers.wsgi import WSGIHandler + from django.core.servers.basehttp import ThreadedWSGIServer, WSGIRequestHandler +except ImportError as e: + raise MissingDjangoException from e class AraOfflineClient(AraHttpClient): diff --git a/ara/server/__main__.py b/ara/server/__main__.py index ccc20792..c523f05d 100644 --- a/ara/server/__main__.py +++ b/ara/server/__main__.py @@ -19,11 +19,16 @@ import os import sys +from ara.setup.exceptions import MissingDjangoException + def main(): os.environ.setdefault("DJANGO_SETTINGS_MODULE", "ara.server.settings") - from django.core.management import execute_from_command_line + try: + from django.core.management import execute_from_command_line + except ImportError as e: + raise MissingDjangoException from e execute_from_command_line(sys.argv) diff --git a/ara/server/wsgi.py b/ara/server/wsgi.py index ff643479..d83c0aec 100644 --- a/ara/server/wsgi.py +++ b/ara/server/wsgi.py @@ -17,7 +17,12 @@ import os -from django.core.wsgi import get_wsgi_application +from ara.setup.exceptions import MissingDjangoException + +try: + from django.core.wsgi import get_wsgi_application +except ImportError as e: + raise MissingDjangoException from e os.environ.setdefault("DJANGO_SETTINGS_MODULE", "ara.server.settings") diff --git a/ara/setup/exceptions.py b/ara/setup/exceptions.py new file mode 100644 index 00000000..b8815ba6 --- /dev/null +++ b/ara/setup/exceptions.py @@ -0,0 +1,22 @@ +# Copyright (c) 2019 Red Hat, Inc. +# +# This file is part of ARA Records Ansible. +# +# ARA 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 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. If not, see . + + +class MissingDjangoException(Exception): + def __init__(self): + exc = "Unable to import Django: the server dependencies can be installed with 'pip install ara[server]'" + super().__init__(exc) diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 537ad836..bbc206d9 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -3,22 +3,58 @@ Installing ARA ============== -Manually with pip ------------------ +Requirements and dependencies +----------------------------- ARA should work on any Linux distributions as long as python3 is available. -It is recommended to use a python `virtual environment `_ -in order to avoid conflicts with your Linux distribution python packages:: +Since ARA provides Ansible plugins to record data, it should be installed +wherever Ansible is running from so that Ansible can use those plugins. +The API server does not require to run on the same machine as Ansible. - # Create a virtual environment - python3 -m venv ~/.ara/venv +By default, only the client and plugin dependencies are installed. +This lets users record and send data to a remote API server without requiring +that the API server dependencies are installed. - # Install ARA 1.0 from source - ~/.ara/venv/bin/pip install git+https://git.openstack.org/openstack/ara@feature/1.0 +If you are standing up an API server or if your use case is about recording +data locally or offline, the required dependencies can be installed +automatically by suffixing ``[server]`` to your pip install commands. -Using Ansible roles -------------------- +Installing from PyPi or from source +----------------------------------- + +First, it is recommended to use a python `virtual environment `_ +in order to avoid conflicts with your Linux distribution python packages. + +.. code-block:: bash + + python3 -m venv ~/.ara/virtualenv + +To install the latest pre-release for ARA 1.0 from PyPi_: + +.. code-block:: bash + + # With the API server dependencies + ~/.ara/virtualenv/bin/pip install --pre ara[server] + + # Without the API server dependencies + ~/.ara/virtualenv/bin/pip install --pre ara + +Installing from source is possible by using the +`feature/1.0 `_ branch: + +.. code-block:: bash + + # With the API server dependencies + ~/.ara/virtualenv/bin/pip install git+https://github.com/ansible-community/ara@feature/1.0[server] + + # Without the API server dependencies + ~/.ara/virtualenv/bin/pip install git+https://github.com/ansible-community/ara@feature/1.0 + +.. _PyPi: https://pypi.org/project/ara/ + +With Ansible roles +------------------ Two roles are built-in to help users configure their API and web deployments: diff --git a/requirements.txt b/requirements.txt index faed390b..680e644b 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,9 +1,3 @@ pbr!=2.1.0,>=2.0.0 # Apache-2.0 -Django>=2.1.5 -djangorestframework>=3.9.1 -django-cors-headers -django-filter -dynaconf[yaml] requests>=2.14.2 -whitenoise \ No newline at end of file diff --git a/roles/ara_api/tasks/install/source.yaml b/roles/ara_api/tasks/install/source.yaml index 8cbe90e1..acd2c677 100644 --- a/roles/ara_api/tasks/install/source.yaml +++ b/roles/ara_api/tasks/install/source.yaml @@ -24,7 +24,7 @@ - name: Install ara pip: - name: "{{ ara_api_source_checkout }}" + name: "{{ ara_api_source_checkout }}[server]" state: present virtualenv: "{{ ara_api_venv | bool | ternary(ara_api_venv_path, omit) }}" virtualenv_python: python3 diff --git a/roles/ara_tests/tasks/main.yaml b/roles/ara_tests/tasks/main.yaml index 3c1d1bed..779ec3f6 100644 --- a/roles/ara_tests/tasks/main.yaml +++ b/roles/ara_tests/tasks/main.yaml @@ -62,7 +62,7 @@ - name: Install ARA from source in virtual environment pip: - name: "{{ _ara_tests_repository }}" + name: "{{ _ara_tests_repository }}[server]" state: present virtualenv: "{{ ara_tests_virtualenv }}" virtualenv_python: python3 diff --git a/setup.cfg b/setup.cfg index d0bef45d..0ec7f9d9 100644 --- a/setup.cfg +++ b/setup.cfg @@ -31,6 +31,15 @@ packages = console_scripts = ara-manage = ara.server.__main__:main +[extras] +server= + Django>=2.1.5 + djangorestframework>=3.9.1 + django-cors-headers + django-filter + dynaconf[yaml] + whitenoise + [build_sphinx] source-dir = doc/source build-dir = doc/build diff --git a/tox.ini b/tox.ini index 9a83ce6b..1fb8dee8 100644 --- a/tox.ini +++ b/tox.ini @@ -10,6 +10,7 @@ usedevelop = True install_command = pip install -U {opts} {packages} -c{env:CONSTRAINTS_FILE:/dev/null} setenv = VIRTUAL_ENV={envdir} deps = -r{toxinidir}/test-requirements.txt +extras = server [testenv:venv] commands = {posargs}