.. _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. By default, the test site uses domain ``example.com``, but it has been designed so it is easy to set your own domain (see below in step-by-step instructions). Some changes may be necessary to listed commands in that case (i.e. replace every occurance of ``example.com`` with your own domain). 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. As mentioned in introduction, default domain used by test site is ``example.com``. To change it, perform the following steps (otherwise, just skip to step 2): a. Update the file ``hosts``. Simply replace all occurances of ``example.com`` with your chosen domain. b. Update the file ``group_vars/all.yml``, changing the value of variable ``testsite_domain``. This value will then be used to calculate some of derived values, like LDAP base DN (which will be set to something along the lines of ``dc=example,dc=com`` or ``dc=your,dc=domain,dc=components``). 2. If you do not wish to have the hassle of creating the private keys and issuing certificates, there is a small playbook that can help you with this. Just run the ``tls.yml`` playbook, and skip to step 6 (otherwise follow steps 3 through 5): .. code-block:: shell ansible-playbook playbooks/tls.yml 3. Create TLS private keys (relative to top level directory), making sure to change domain in filenames if necessary: - ``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`` 4. Issue TLS certificates corresponding to the generated TLS private keys (correct FQDN for DNS subject alternative name **must** be used), making sure to change domain in filenames if necessary: - ``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``) 5. 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/ca.pem``. It is very important to include the full CA chain used for LDAP server. 6. Generate the preseed files: .. code-block:: shell ansible-playbook playbooks/preseed.yml 7. Install all servers using the generated preseed files. 8. 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 (don't forget to modify domain if you need to): .. code-block:: shell ssh-keyscan mail.example.com ldap.example.com xmpp.example.com web.example.com $(resolveip -s mail.example.com) $(resolveip -s ldap.example.com) $(resolveip -s xmpp.example.com) $(resolveip -s web.example.com) 9. 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 10. 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``).