.. _features:

******************
Features and Usage
******************

Initializing Fabex
==================

In addition to the ``task_roles`` decorator, Fabex provides a number
of additional enhancements and extensions. The standard ``from
fabric.api import *`` should be replaced with

 .. code-block:: python

    from fabex.api import *
    from fabex.contrib.files import *

which will import both fabric and fabex. Next use ``fabex_config`` to
setup Fabex's target and templates features.

 .. code-block:: python

    fabex_config({'target_dir': 'targets',
                  'template_dir': 'templates',
                  'template_config': 'templates.yaml'})

Feature Reference
=================

- ``@task_roles`` - Function decorator to make a Fabric task that will
  be invoked  once per role  with role settings injected  into ``env``
  for the scope of that task.  The ``task_roles`` requires one or more
  strings as positional arguments with  the role names. The role names
  may also be specific by a single iterable as the first argument.

  ``task_roles`` also supports a ``group`` keyword argument of string
  type. That task will be added to a "wrapper task" with that name,
  appended to a list of tasks to invoke if the wrapper task is called
  (see *assertion 4*).

  ``task_roles`` supports all of the other keyword arguments of the
  Fabric ``task`` decorator, with function per the Fabric
  documentation.

  *Example:*

 .. code-block:: python

    @task_roles(['webapp', 'cache', 'db'], group='install')
    def install_packages():
        """Install system packages"""
    
        sudo('DEBIAN_FRONTEND=noninteractive apt-get install --yes {}'
             .format(' '.join(env.packages)))

- ``@runs_once_per_host`` - Similar to the Fabric ``runs_once``
  decorator, the task is invoked only the first time for any host,
  regardless of the "once per role per host" rule implemented by
  ``task_roles``.

- ``fabex_config`` - A normal python function that takes a Fabex
  config dictionary, or path to a yaml file with a Fabex config. This
  function initializes several ``env`` attributes used elsewhere in
  Fabex. **Note:** Should be called before any other Fabex tasks are
  invoked, typically at the top of a fabfile.

  *Example:*

 .. code-block:: python

    fabex_config(config={'target_dir': 'targets',
                         'template_dir': 'templates',
                         'template_config': 'templates.yaml'})

- ``target`` - A (normal) Fabric task that reads a yaml file and
  builds a "target configuration" into ``env``. In particular, this
  configuration can contain ``roledefs`` (a la Fabric), ``hostenvs``
  (env settings injected on a per host basis via ``task_roles``), and
  ``roleenvs`` (env settings injected on a per role basis via
  ``task_roles``).

  *Example target.yaml:*

 .. code-block:: yaml

    domain: domain.com
    timezone: America/Los_Angeles
    
    roledefs:
        app: [app1 app2 app3]
        cache: [db_cache]
        db: [db_cache]
    
    hostenvs:
        app1: {ip: 192.168.0.21, ssh_host: app1.prod, ssh_user: ubuntu}
        app2: {ip: 192.168.0.22, ssh_host: app2.prod, ssh_user: ubuntu}
        app3: {ip: 192.168.0.23, ssh_host: app3.prod, ssh_user: ubuntu}
        db_cache: {ip: 192.168.0.20, ssh_host: bigserver.prod, ssh_user: ubuntu}
    
    roleenvs:
        app:
            packages: [ntp, git, python-django, libpq-dev, postgresql-client]
            repo_url: git@github.com:gitaccount/gitrepo.git
            secret_key: ty5s3(d4jjexdror_ti$-ga+q_zs(!byj)k3d8i^iyxl-$r^*j
            db_name: fu
            db_user: bar
            db_pass: spam
        cache:
            packages: [ntp, memcached]
            memory: 128
        db:
            packages: [ntp, postgresql]

- ``template_config`` - Specified in the ``fabex_config`` call, a yaml
  based dictionay referencing Jinja2 templates. The templates
  themselves will be search for in the ``template_dir`` specified in
  ``fabex_config``. Both the ``template_config`` file, and the
  templates themselves have access to the ``env`` as a Jinja2 context,
  and can instatiate ``env`` values.

  Referenced templates are processed and pushed by the Fabex
  ``upload_project_template`` function. In addition to the Jinja2
  processing, uploaded file ownership can be set with ``owner`` and
  ``group`` attributes. A ``reload_command`` attribute may contain a
  sudo-able command that is executed if the remote file is changed by
  the upload.

  *Example templates.yaml*:

 .. code-block:: yaml

    local_settings:
        local_path: local_settings.py
        remote_path: "{{project_home}}/{{project_name}}/local_settings.py"
        reload_command: supervisorctl {{project}} restart
        owner: ubuntu
        group: ubuntu

- ``dryrun`` - A Fabric task that short circuits all of the remote
  client calls. Invoking this task before other tasks allows Fabric
  scripts to be debugged (somewhat) before executing on actual
  servers.

- ``quiet`` - Fabex will hide the 'running' and 'output' streams for
  ``sudo`` and ``run`` in Fabric if this task is invoked. Note, this
  feature is **not** the ``quiet`` keyword arg to those functions, which
  has other effects on tasks.

- ``fxcrypt`` - A command that wraps AES encryption used in Fabex target files.

 .. code-block:: bash

    usage: fxcrypt [-h] [--decrypt] password text
    
    encrypt a string for fabex !decrypt yaml directive
    
    positional arguments:
      password    encryption key, *required* to decrypt
      text        text to encrypt
    
    optional arguments:
      -h, --help  show this help message and exit
      --decrypt   decrypt instead of encrypting