* Sets-up system for performing checks on pip requirements files. Roles that

  want their requirements files checked should create a sub-directory inside of

  ``/etc/pip_check_requirements_upgrades``, and place ``.txt`` and ``.in`` files

  inside (with same base name). The ``.txt`` files should be standard

  requirements files with fixed versions (the ones installed by the role). The

  ``.in`` files should contain only the top-level packages (no

  dependencies). Avoid hard-coding versions in the ``.in`` file unless really

  needed. For packages where you want to stick to stable/LTS version branch, you

  should be able to use ``~=`` operator (for example ``django~=1.8.0``. Checks

  are implemented via `pip-tools <https://github.com/jazzband/pip-tools>`_ and a

  custom script that outputs diffs if upgrades are available. Script is run via

  cronjob on hourly basis, and any output will be delivered to local ``root``

  user.

**futures_version** (string, optional, ``3.1.1``)

**gunicorn_version** (string, optional, ``19.7.1``)

**wsgi_requirements** (list, optional, ``[]``)

  Complete list of pip requirements used for deploying Gunicorn. If specified,

  this list will be used to create requirements file and install Gunicorn and

  its dependencies from that one. This allows to have pinned packages for both

  Gunicorn, futures, and their dependencies.

  It should be noted that this installation method is meant primarily in case of

  roles that want to take advantage of upgrade checks for pip requirements

  files, and that employ `pip-tools <https://github.com/jazzband/pip-tools>`_.

  In addition to change of installation method, when this parameter is specified

  the role will deploy necessary files for running the pip requirements upgrade

  check (see the ``common`` role for description). For this a directory is

  created under ``/etc/pip_check_requirements_upgrades/FQDN``. The same

  directory should be used by dependant roles to deploy their own ``.in`` and

  ``.txt`` files. Make sure the file ownership is set to ``root:pipreqcheck``.

  Should you need to utilise the requirements file in some manner (other than

  checking for its upgrades), it will be also stored (and made accessible to

  application user/admin)) in application's home directory under the name

  ``.wsgi_requirements.txt``.

  To create complete requirements list, it is recommended to use `pip-tools

  <https://github.com/jazzband/pip-tools>`_ (the ``pip-compile`` utility) with

  ``gunicorn`` and ``futures`` in the ``.in.`` file.

    # Sample for a Django installation.

    # Use wsgi_requirements to deploy Gunicorn.

    - role: wsgi_website

      fqdn: wsgi.example.com

      wsgi_application: wsgi:main

      wsgi_requirements:

        - gunicorn==19.7.1

	- futures==3.1.1

easily do so by updating the ``common_packages`` setting.

In addition to system packages, the ``common`` role makes it easy to check if

any of the pip requirements files are outdated as well. It should be noted,

though, that this check does *not* verify the Python virtual environments

themselves.

This is primarily useful when you use `pip-tools

<https://github.com/jazzband/pip-tools>`_ for maintaining the requirements

files. In fact, I would both encourage you to utilise ``pip-tools`` for both

this purpose and for keeping the virtual environment in sync and up-to-date.

Roles that want to take advantage of this would:

- Create a sub-directory under ``/etc/pip_check_requirements_upgrades/``.

  ``/etc/pip_check_requirements_upgrades/FQDN``.

- Deploy ``.in`` and ``.txt`` files within the sub-directory (see ``pip-tools``

  docs for explanation of how the ``.in`` files work).

- Ensure the created sub-directory and files have ownership set to

  ``root:pipreqcheck``.

.. note::

   If you are using the ``wsgi_website`` role as dependency, simply set-up the

   ``wsgi_requirements`` parameter, and then deploy the ``.in`` and ``.txt``

   file into directory ``/etc/pip_check_requirements_upgrades/FQDN`` (this

   directory is automatically created when ``wsgi_requirements`` is specified).