remaining servers.

* Communications server, providing the LDAP, mail, and XMPP services.

* Web server, providing the web services.

* Backup server, used for storing all of the backups.

.. warning::

   Majic Ansible Roles support *only* Python 3 - both on the

   controller side and on the managed servers side.

   It is important to make sure that both the controller Python

   virtual environment used for Ansible *and* the interpreter for

   remote servers are *both* set-up to use Python 3.

   Python 3 is specified explicitly during virtual environment

   creation and in ``ansible.cfg`` configuration file

   (``interpreter_python`` option under ``defaults`` section).

Pre-requisites

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

For the set-up outlined in this usage guide you'll need the following:

  be installed on top of this server. The server will be set-up

  manually (this is currently out of scope for the *Majic Ansible

  Roles* automated set-up).

* Three servers where the services will be set-up. All servers must be able to

  communicate over network with each-other, the Ansible servers, and with

  usage instructions.

* All servers should be on the same network.

* IP addresses for all servers should be known.

* Netmask for all servers should be known.

* Gateway for all servers should be known.

In case of the servers listed above, it might be safest to have them as VMs -

this is cheapest thing to do, and simplest (who wants to deal with pesky hardware anyway?).

Usage instructions assume the following:

* Domain used for all servers is ``example.com``. If you wish to use a different

  domain, adjust the instructions accordingly.

* Server hostnames are ``ansible``, ``comms``, ``www``, and ``bak`` (for Ansible

  server, communications server, web server, and backup server, respectively).

Installing the OS on Ansible server

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

Start-off by installing the operating system on the Ansible server:

1. Fire-up the ``ansible`` server, and boot from the network installation CD.

2. Select the **Install** option.

15. If you have an HTTP proxy, provide its URL.

16. Pick if you want to participate in package survey or not.

17. Make sure that at least the **standard system utilities** and **SSH server**

    options are selected on task selection screen.

18. Wait for packages to be installed.

19. Install the GRUB boot loader on MBR.

20. Finalise the server install, and remove the installation media from server.

Installing required packages

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

With the operating system installed, it is necessary to install a couple of

packages, and to prepare the environment a bit on the Ansible server:

1. Install the necessary system packages (using the ``root`` account)::

     apt-get install -y virtualenv virtualenvwrapper git python3-pip python3-dev libffi-dev libssl-dev

   .. warning::

      If you are already logged-in as user ``ansible`` in the server, you will

      need to log-out and log-in again in order to be able to use

      ``virtualenvwrapper`` commands!

   ::

     mkdir ~/mysite/

     mkvirtualenv -p /usr/bin/python3 -a ~/mysite/ mysite

     pip install -U pip setuptools

     pip install 'ansible~=2.9.0' dnspython

.. warning::

   The ``dnspython`` package is important since it is used internally via

   ``dig`` lookup plugin.

Cloning the *Majic Ansible Roles*

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

With most of the software pieces in place, the only missing thing is the Majic

Ansible Roles:

          ip: 10.32.64.19

        www.example.com:

          hostname: www

          ip: 10.32.64.20

        bak.example.com:

          hostname: bak

          ip: 10.32.64.23

6. Now re-run the preseed playbook::

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

7. The preseed files should have been updated now, and you should have the new

   customised configuration files in the ``preseed_files`` directory. You can

   now use these to install the servers.

Installing the servers with preseed files

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

You have your preseed files now, so you can go ahead and install the

servers ``comms.example.com``, ``www.example.com``, and

``bak.example.com`` using them with network install CD. Have a look at

`Debian instructions

more details.

If you need to, you can easily serve the preseed files from the Ansible server

with Python's built-in HTTP server::

  cd ~/mysite/preseed_files/

  python3 -m http.server 8000

Then you can point installer to the preseed file selecting the

``Advanced options -> Automated install`` (don't press ``ENTER`` yet),

then pressing ``TAB``, and appending the following at the end (just

fill-in the correct hostname - ``comms``, ``www``, or ``bak``)::

  url=http://ansible.example.com:8000/HOSTNAME.example.com.cfg

Bootstrapping servers for Ansible set-up

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

In order to effectively use Ansible, a small initial bootstrap always has to be

done for managed servers. This mainly involves set-up of Ansible users on the

destination machine, and distributing the SSH public keys for authorisation.

When you use the preseed configuration files to deploy a server, you get the

      - import_playbook: web.yml

      - import_playbook: backup.yml

5. Time to create configuration for the role. Since this role is supposed to

   set-up a common base, we'll set-up the variables file that applies to all

   roles:

   :file:`~/mysite/group_vars/all.yml`

   ::

      ---

      ansible_key: "{{ lookup('file', '~/.ssh/id_rsa.pub') }}"

      os_users:

        - name: admin

          uid: 1000

          additional_groups:

            - sudo

          authorized_keys:

            - "{{ lookup('file', '~/.ssh/id_rsa.pub') }}"

          password: "{{ 'admin' | password_hash('sha512') }}"

      common_packages:

      ca_certificates:

        truststore: "{{ lookup('file', '~/mysite/tls/truststore.pem') }}"

   .. note::

      The ``common`` role comes with ability to set-up time

      synchronisation using NTP. This is not done by default. For

      details see the role parameter ``ntp_servers``.

   .. note::

      The ``ca_certificates`` parameter lets us deploy custom CA

      certificates on servers. The name we pick (in this case

      ``truststore``) can be set to anything. In this particular case,

      we want to deploy our own CA certificate for use as truststore,

      since this is what the services will use to validate server

      certificates when connecting to each-other.

6. That's all for configuration, time to apply the changes::

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

7. After this you should be able to *ssh* from Ansible server onto the

   managed servers as user ``admin`` using the *SSH* private key of

   the ``ansible`` user on controller machine. The ``admin`` user's