.. _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 fresh nodes)
  This playbook can be used for bootstrapping fresh nodes. By default, the
  entire test site will be included in the bootstrap. If you wish to limit
  bootstrap to a single server, just run the playbook with (for example):

  .. code-block:: shell

    ansible-playbook -l ldap.example.com playbooks/bootstrap.yml

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

mail.yml
  This playbook sets-up the mail server. 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.

web.yml
  This playbook sets-up the web server. It is included in ``site.yml``.

xmpp.yml
  This playbook sets-up the XMPP server. It is included in ``site.yml``.

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

1. If you do not wish to have the hassle of creating the private keys and
   issuing certificates, run the following commands to get this done for you
   automatically, and skip to step 5 (otherwise follow steps 2 through 4):

   .. code-block:: shell

     certtool --sec-param high --generate-privkey --outfile tls/example_ca.key
     certtool --template tls/templates/example_ca.cfg --generate-self-signed --load-privkey tls/example_ca.key --outfile tls/example_ca.pem
     cp tls/example_ca.pem tls/example_ca_chain.pem
     for template in tls/templates/*.cfg; do
         entity_basename="$(basename "$template" .cfg)"
         [[ $entity_basename == example_ca ]] && continue
         certtool --sec-param normal --generate-privkey --outfile "tls/$entity_basename.key"
         sleep 1
         certtool --generate-certificate \
           --load-ca-privkey "tls/example_ca.key" \
           --load-ca-certificate "tls/example_ca.pem" \
           --template "$template" \
           --load-privkey "tls/${entity_basename}.key" \
           --outfile "tls/${entity_basename}.pem"
     done

2. Create TLS private keys (relative to top level directory):

   - ``testsite/tls/mail.example.com_imap.key``
   - ``testsite/tls/mail.example.com_smtp.key``
   - ``testsite/tls/xmpp.example.com_xmpp.key``
   - ``testsite/tls/ldap.example.com_ldap.key``
   - ``testsite/tls/web.example.com_https.key``
   - ``testsite/tls/phpfino.example.com_https.key``
   - ``testsite/tls/wsgi.example.com_https.key``

3. Issue TLS certificates corresponding to the generated TLS private keys (make
   sure to use correct FQDN for DNS subject alternative name):

   - ``testsite/tls/mail.example.com_imap.pem`` (subject alternative name should
     be ``mail.example.com``)
   - ``testsite/tls/mail.example.com_smtp.pem`` (subject alternative name should
     be ``mail.example.com``)
   - ``testsite/tls/xmpp.example.com_xmpp.pem`` (subject alternative name should
     be ``xmpp.example.com``)
   - ``testsite/tls/ldap.example.com_ldap.pem`` (subject alternative name should
     be ``ldap.example.com``)
   - ``testsite/tls/web.example.com_https.pem`` (subject alternative name should
     be ``web.example.com``)
   - ``testsite/tls/web.example.com_https.pem`` (subject alternative name should
     be ``web.example.com``)
   - ``testsite/tls/phpinfo.example.com_https.pem`` (subject alternative name
     should be ``phpinfo.example.com``)
   - ``testsite/tls/wsgi.example.com_https.pem`` (subject alternative name
     should be ``wsgi.example.com``)

4. Create ``PEM`` truststore file which contains all CA certificates that form
   CA chain for the issued end entity certificates from previous step at
   location ``testsite/tls/example_ca_chain.pem``. It is very important to
   include the CA chain used for LDAP server.

5. Generate the preseed files:

  .. code-block:: shell

    ansible-playbook playbooks/preseed.yml

6. Install all servers using the generated preseed files.

7. Add the SSH host fingerprints to your ``known_hosts`` file (don't forget to
   remove old entries if you are redoing the process). You can easily obtain all
   the necessary fingerprints with command:

   .. code-block:: shell

      ssh-keyscan mail.example.com ldap.example.com xmpp.example.com web.example.com

8. Invoke the ``bootstrap.yml`` playbook in order to set-up some basic
   environment for Ansible runs on all servers:

  .. code-block:: shell

    ansible-playbook playbooks/bootstrap.yml

9. 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.pub`` (i.e. from home directory of user running the Ansible
  commands).

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