custom tasks, but at this point we need to.

   :file:`~/mysite/roles/tbg/tasks/main.yml`

   ::

      ---

      - name: Define TBG version

        set_fact:

          tbg_version: "4.3.1"

          tbg_archive_checksum: "45de72b1ef82142ad46686577d593375ba370156df4367d17386b4e26a37f342"

      - name: Download the TBG archive

        get_url:

          url: "https://github.com/thebuggenie/thebuggenie/archive/v{{ tbg_version }}.tar.gz"

          dest: "/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}.tar.gz"

          sha256sum: "{{ tbg_archive_checksum }}"

        become: yes

        become_user: admin-tbg_example_com

      - name: Download Composer

        get_url:

          url: "https://getcomposer.org/download/1.10.19/composer.phar"

          dest: "/usr/local/bin/composer"

          sha256sum: "688bf8f868643b420dded326614fcdf969572ac8ad7fbbb92c28a631157d39e8"

          owner: root

          group: root

          mode: 0755

      - name: Unpack TBG

        unarchive:

          src: "/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}.tar.gz"

          dest: "/var/www/tbg.example.com/"

          copy: no

          creates: "/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}"

        become: yes

        become_user: admin-tbg_example_com

      - name: Allow use of lib-pcre version 10 (since PHP is built against it in Debian Buster)

        lineinfile:

          dest: "/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}/{{ item }}"

          state: present

          regexp: '.*"lib-pcre".*'

          line: '        "lib-pcre": ">=8.0",'

        with_items:

          - "composer.json"

          - "composer.lock"

      - name: Create TBG cache directory

        file:

          path: "/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}/cache"

          state: directory

          mode: 02770

        become: yes

        become_user: admin-tbg_example_com

      - name: Set-up the necessary write permissions for TBG directories

        file:

          path: "{{ item }}"

          mode: g+w

        with_items:

          - /var/www/tbg.example.com/thebuggenie-{{ tbg_version }}/

          - /var/www/tbg.example.com/thebuggenie-{{ tbg_version }}/public/

          - /var/www/tbg.example.com/thebuggenie-{{ tbg_version }}/core/config/

      - name: Create symbolic link to TBG application

        file:

          src: "/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}/public"

          path: "/var/www/tbg.example.com/htdocs"

          state: link

          owner: "admin-tbg_example_com"

          group: "web-tbg_example_com"

        become: yes

        become_user: admin-tbg_example_com

      - name: Install TBG dependencies

        composer:

          command: install

          working_dir: "/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}"

        become: yes

        become_user: admin-tbg_example_com

      - name: Deploy database configuration file for TBG

        copy:

          src: "b2db.yml"

          dest: "/var/www/tbg.example.com/thebuggenie-{{ tbg_version }}/core/config/b2db.yml"

          mode: 0640

          owner: admin-tbg_example_com

          group: web-tbg_example_com

      - name: Install pexpect package

        apt:

          name: python3-pexpect

          state: present

      - name: Deploy expect script for installing TBG

As mentioned before, all of the supplied roles coming with *Majic Ansible Roles*

include backup support. What gets backed-up depends on the role implementation

(see role reference for details). What about backup support for custom roles?

This is something that has to be done by hand. However, it is quite simple to do

so.

Backup integration will be demonstrated with the previously implemented

``tbg`` role.

*The Bug Genie* stores most of its data in database, but thanks to the

``database`` role its backup is already handled for us. As a side-note, just

before every backup run the database is dumped and stored in location

``/srv/backup/tbg.sql``. That file is subsequently backed-up via *Duply* run.

What is not backed-up for us, though, are the files uploaded to *The Bug

Genie*. So let's fix that one.

1. Add the ``backup`` role to list of dependencies. Take note that while the

   ``backup_client`` role deals with basic set-up of backup client and its

   configuration, the ``backup`` role is used to define what should be

   backed-up. It is important to define unique filename for the backup patterns

   file. Take into account that you can use pretty much any globbing pattern

   supported by Duplicity.

   .. warning::

      Make sure the addition is properly aligned in the yaml file to previous

      role dependency definitions.

   :file:`~/mysite/roles/tbg/meta/main.yml`

   .. Small workaround for Sphinx not preserving leading spaces in

      case all lines have the same amount of leading spaces.

   .. code-block:: none

      :name: sphinx_workaround

        - role: backup

          when: enable_backup

          backup_patterns_filename: "tbg"

          backup_patterns:

            - "/var/www/tbg.example.com/files"

2. Apply the changes::

     workon mysite && ansible-playbook playbooks/site.yml

   ::

     duply main backup

4. Verify that the files have been backed-up:

   ::

      duply main list

.. note:: If you wanted to run a script prior to backup run, you would simply

          deploy a shell script with desired content to

          ``/etc/duply/main/pre.d/``. Just make sure the permissions for it are

          ok (it has to be executable by the root user).

Dealing with failures

---------------------

While the roles have been designed to be fairly robust, it should be taken into

account that certain handlers are used to bring the system into consistent

state. These handlers are mostly the ones dealing with service restarts, but

there are also a couple of handlers that take care of transforming certain data

into the required formats, import of files etc.

This means that failure to successfully execute such handlers could result in

inconsistent state on the server. Think of service configuration files being

updated, yet the service itself is not restarted and therefore continues to run

with the old configuration.

Handler execution failure can depend on a couple of things, including the loss

of SSH connectivity to managed machine, or some kind of unusual time-out during

handler execution.

To help handle this situation, Majic Ansible Roles all come with a special way

to invoke the handlers explicitly. Each role will include handlers as tasks,

provided that a special variable (``run_handlers``) is passed in to playbook run. To

make the run shorter, the handlers in such a run are also tagged with

``handlers``. This doubling of environment variable + tagging stems from current

limitations of Ansible (it is not possible to specify that certain task should

be run only if a tag is specified, therefore an additional variable has to be

used).

Handlers alone can be invoked specifically with command similar to::

  ansible-playbook -t handlers -e run_handlers=true playbooks/site.yml