.. _testsite:

Test Site
=========

*Majic Ansible Roles* comes with a small sample test site configuration which
demonstrates use of every role. This test site also serves as starting point for
developing new roles etc, and can be used for testing regressions/breakages.

The test site covers everything, starting from generating the Debian preseed
files, through bootstrap process for new nodes, and onto deployment of all
remaining roles.

All example commands listed within this section should be ran from within the
``testsite`` directory in order to have proper environment available for
playbook runs.

A number of playbooks is provided out of the box:

bootstrap.yml (for bootstrapping a new node)
  This playbook can be used for bootstrapping a new node. This playbook expects
  that a server name is passed via extra variables in CLI. The server name has
  to be included in the hosts file, of course. For example:

  .. code-block:: shell

    ansible-playbook -k -e server=ldap.example.com playbooks/bootstrap.yml

ldap.yml
  This playbook sets-up the LDAP servers. It is included in ``site.yml``.

preseed.yml
  This playbook sets-up the Debian preseed files. It is included in
  ``site.yml``.

site.yml
  This playbook sets-up all servers, including preseed files on local host.

In order to deploy the test site, the following steps would normally be taken:

1. Generate the preseed files:

  .. code-block:: shell

    ansible-playbook playbooks/preseed.yml

2. Install all servers using the generated preseed files.

3. Invoke the ``bootstrap.yml`` playbook for every server, one by one. For
   example:

  .. code-block:: shell

    ansible-playbook -k -e server=ldap.example.com playbooks/bootstrap.yml

4. Finally, apply configuration on all servers:

  .. code-block:: shell

    ansible-playbook playbooks/site.yml

The playbooks and configurations for test site make a couple of assumptions:

* Each server will be set-up with an operating system user ``admin``, capable of
  running the sudo commands.
* The password for operating system user ``admin`` is hard-coded to ``admin``.
* An SSH ``authorized_keys`` file is set-up for the operating system user
  ``admin``. The SSH key stored in it will be read from location
  ``~/.ssh/id_rsa`` (i.e. from home directory of user running the Ansible
  commands).
* The TLS truststore can be found in location ``certs/example_ca_chain.crt``
  relative to the ``testsite`` sub-directory.

Additionally, some manual steps may be required to have a fully functioning
system:

* On ``ldap.example.com``, you should manually install the TLS private key and
  certificate ing locations ``/etc/ssl/private/ldap.example.com.pem``
  (*root:ldap, 640*) and ``/etc/ssl/certs/ldap.example.com.pem`` (*root:root,
  644*), respectively. After that, re-run the ``site.yml`` playbook in order to
  re-configure OpenLDAP server to use it.

* On ``xmpp.example.com``:

  * Create TLS private key for XMPP in location
    ``/etc/ssl/private/xmpp.example.com.pem`` (*root:prosody, 640*).
  * Create TLS certificate for XMPP in location
    ``/etc/ssl/certs/xmpp.example.com.pem`` (*root:root, 644*).
  * After all files are in place, re-run the ``site.yml`` playbook in order to
    restart necessary services etc.

* On ``mail.example.com``, you should manually install the TLS private key and
  certificate in locations ``/etc/ssl/private/mail.example.com.pem``
  (*root:ldap, 640*) and ``/etc/ssl/certs/mail.example.com.pem`` (*root:root,
  644*), respectively. After that, restart the servics ``dovecot`` and
  ``postfix``.

* On ``mail.example.com``:

  * Create TLS private key for SMTP in location
    ``/etc/ssl/private/mail.example.com_smtp.pem`` (*root:openldap, 640*).
  * Create TLS certificate for SMTP in location
    ``/etc/ssl/certs/mail.example.com_smtp.pem`` (*root:root, 644*).
  * Create TLS private key for IMAP in location
    ``/etc/ssl/private/mail.example.com_imap.pem`` (*root:openldap, 640*).
  * Create TLS certificate for IMAP in location
    ``/etc/ssl/certs/mail.example.com_imap.pem`` (*root:root, 644*).
  * After all files are in place, re-run the ``site.yml`` playbook in order to
    restart necessary services etc.

For more details on how the playbooks and configuration have been implemented,
feel free to browse the test site files (in directory ``testsite``).