.. _usage:

Usage
=====

Majic Ansible Roles are targeted at sysadmins who wish to deploy services for
their own, small-scale use. This chapter gives a simple tutorial-like set of
instructions for using all of the roles available.


Overview
--------

There is a number of different roles that can prove useful for setting-up a
small infrastructure of your own.

Some roles are suited for one-off operations during installation, like the
``preseed`` and ``bootstrap``, while some are better suited for periodic runs
for maintaining the users and integrity of the system.

By the end of the instructions you will have the following:

* Ansible server, used for configuring the remaining servers.
* Communications server, providing the LDAP, mail, and XMPP services.
* Web server, providing the web services.


Pre-requisites
--------------

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

* One server where Ansible will be installed at. Debian Jessie will 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).
* Two servers where the services will be set-up. Both servers must be able to
  communicate over network with each-other, the Ansible servers, and with
  Internet. Debian Jessie will be installed on top of this server as part of the
  usage instructions.
* Debian Jessie network install CD.
* All servers should be on the same network.
* IP addresses for all three servers should be known.
* Netmask for all three servers should be known.
* Gateway for all three servers should be known.

In case of the three servers above, it might be safest to have three VMs
available and handy.

Usage instructions assume the following:

* Domain used for all three servers is ``example.com``. If you wish to use a
  different domain, adjust the instructions accordingly.
* Server hostnames are ``ansible``, ``comms``, and ``www`` (for Ansible server,
  communications server, and web 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.

3. Pick **English** as language.

4. Pick the country you are living in (or whatever else you want).

5. Pick the **en_US.UTF-8** locale.

6. Pick the **American English** keymap.

7. Configure the network if necessary.

8. Set the hostname to ``ansible``.

9. Set the domain to ``example.com``.

10. Set the root password.

11. Create a new user. For simplicity, call the user **Ansible user**, with
    username **ansible**.

12. Set-up partitioning in any way you want. You can go for **Guided - use
    entire disk** if you want to keep it simple and are just testing things.

13. Wait until the base system has been installed.

14. Pick whatever Debian archive mirror is closest to you.

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 python-pip python-dev

2. Set-up the virtual environment (using the ``ansible`` account)::

     mkdir ~/mysite/
     mkvirtualenv -a ~/mysite/ mysite
     pip install ansible


Cloning the *Majic Ansible Roles*
---------------------------------

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

1. Clone the git repository::

     git clone http://code.majic.rs/majic-ansible-roles ~/majic-ansible-roles

2. Checkout the correct version of the roles::

     cd ~/majic-ansible-roles/
     git checkout -b 1.0.0 1.0.0


Preparing the basic site configuration
--------------------------------------

Phew... Now that was a bit tedious and boring... But at least you are now ready
to set-up your own site :)

First of all, let's set-up some basic directory structure and configuration:

1. Create Ansible configuration file.

   :file:`~/mysite/ansible.cfg`::

     [defaults]

     roles_path=/home/ansible/majic-ansible-roles/roles
     force_handlers = True
     retry_files_save_path = /home/ansible/mysite/retry
     inventory = /home/ansible/mysite/hosts

2. Create directory where retry files will be stored at (so they woudln't
   pollute your home directory)::

     mkdir ~/mysite/retry

3. Create the hosts file.

   :file:`~/mysite/hosts`::

     [preseed]
     localhost ansible_connection=local

     [communications]
     comms.example.com

     [web]
     www.example.com

4. Create directory where playbooks files will be stored at (the top-level
   ones)::

     mkdir ~/mysite/playbooks/

5. Create directory where variables will be stored at::

     mkdir ~/mysite/group_vars/

6. Before moving ahead, we should also create SSH private/public key pair that
   will be used by Ansible for connecting to destination servers, as well as
   for some roles::

     ssh-keygen -f ~/.ssh/id_rsa -N ''


Preseed files
-------------

The ``preseed`` role is useful for generating Debian preseed files. Preseed
files can be used for automating the Debian installation process.

Preseed files are commonly created on the Ansible host, and then in some way
served to the servers using them during install.

So, let's set this up for start:

1. First of all, create the playbook for generating the preseed files locally.

   :file:`~/mysite/playbooks/preseed.yml`::

      ---
      - hosts: preseed
        roles:
          - preseed

2. And that is about it to be able to actually use this particular role! So
   let's try running it::

     workon mysite
     ansible-playbook playbooks/preseed.yml

3. If all went well, you should have two files now:

   * :file:`~/mysite/preseed_files/comms.example.com.cfg` and
   * :file:`~/mysite/preseed_files/www.example.com.cfg`

4. You can have a look at them, but you might notice the settings in the file
   might not be to your liking. In particular, it could be using wrong timezone,
   defaulting to DHCP for network configuration etc. Let's concentrate on making
   the network configuration changes - this is the main thing that will probably
   differ in your environment. Create a new configuration file:

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

      ---

      # Set your default (initial) root password.
      preseed_root_password: changeit
      # Use manual network configuration (no DHCP).
      preseed_network_auto: no
      # Set the gateway for all servers.
      preseed_gateway: 10.32.64.1
      # Set the netmask for all servers.
      preseed_netmask: 255.255.255.0
      # Set the DNS for all servers.
      preseed_dns: 10.32.64.1
      # Set the domain for all servers.
      preseed_domain: example.com
      # Set the server-specific options.
      preseed_server_overrides:
        comms.example.com:
          hostname: comms
          ip: 10.32.64.19
        www.example.com:
          hostname: www
          ip: 10.32.64.20

5. Now re-run the preseed playbook::

     ansible-playbook playbooks/preseed.yml

6. 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`` and ``www.example.com`` using them with network
install CD. Have a look at `Debian
<https://www.debian.org/releases/stable/amd64/apbs02.html.en>`_ instructions for
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/
  python -m SimpleHTTPServer 8000


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 authroisation.

When you use the preseed configuration files to deploy a server, you get the
benefit of having the authorized_keys set-up for the root operating system,
making it easier to bootstrap the machines subsequently via Ansible.

Let's bootstrap our two machines now:

1. For start, create a dedicated playbook for the bootstrap process.

   :file:`~/mysite/playbooks/bootstrap.yml`::

      ---

      - hosts: [communications, web]
        remote_user: root
        roles:
          - bootstrap

2. The ``bootstrap`` role actually has only one parameter - for specifying the
   SSH key to deploy to authorized_keys file for the Ansible user on managed
   server. This defaults to content of local file ``~/.ssh/id_rsa.pub``, so no
   need to make any changes so far.

3. SSH into both machines at least once from the Ansible server in order to
   store the SSH fingerprints into known hosts file::

     ssh root@comms.example.com date
     ssh root@www.example.com date

4. Now, simply run the bootstrap role against the two servers::

     ansible-playbook playbooks/bootstrap.yml

6. At this point you won't be able to ssh into the machines with root account
   anymore. You would be able to ssh into the machine via public key using the
   ``ansible`` user. The ``ansible`` user will also be granted password-less
   sudo privileges.

7. After this you can finally move on to configuring what you really want -
   common configuration and services for your site.


Common server configuration
---------------------------

Each server needs to share some common configuration in order to be functioning
properly. This includes set-up of some shared accounts, perhaps some hardening
etc.

Let's take care of this common configuration right away:

1. Create playbook for the communications server:

   :file:`~/mysite/playbooks/communications.yml`::

      ---
      - hosts: communications
        remote_user: ansible
        sudo: yes
        roles:
          - common

2. Create playbook for the web server:

   :file:`~/mysite/playbooks/web.yml`::

      ---
      - hosts: web
        remote_user: ansible
        sudo: yes
        roles:
          - common

3. Create the global site playbook:

   :file:`~/mysite/playbooks/site.yml`::

      ---
      - include: preseed.yml
      - include: communications.yml
      - include: web.yml

4. 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`::

      ---

      os_users:
        - name: admin
          uid: 1000
          additional_groups:
            - sudo
          authorized_keys:
            - "{{ lookup('file', '~/.ssh/id_rsa.pub') }}"
          password: "{{ 'admin' | password_hash('sha512') }}"

      common_packages:
        - emacs24-nox

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

     ansible-playbook playbooks/site.yml

6. After this you should be able to ssh using the user ``admin`` via public
   key. The ``admin`` user's password has also been set to ``admin``, and the
   user will be member of ``sudo`` group.