About Majic Ansible Roles
=========================

Majic Ansible Roles is a collection of Ansible roles that are used on regular
basis for deployment and maintenance of Majic infrastructure.

The roles are kept as a separate project in hope of making them potentially
useful to wider audience, and for reference purposes.

Roles cover different aspects of infrastructure, such as mail servers, web
servers, web applications etc. The roles are mainly well-suited for smaller
installations.

Roles are mainly written for use with *Debian 8 Jessie*, although some support
*Debian 9 Stretch* as well. You can find out more about distribution
compatibility in :ref:`rolereference`.

At the moment, the roles have been written for and tested against **Ansible
1.9.x**.

Roles should work for the most part with **Ansible 2.0.x** and **Ansible
2.1.x**, but due to bugs in those releases they should not be used for
production purposes. Roles are kept forward-compatible as much as possible until
a couple of breaking bugs get fixed in **Ansible 2.x** series. The main blockers
are:

* Inability to use dynamic name handlers (handlers that include variables in
  their name).
* Referencing non-existing handlers does not produce error.
* Referencing non-existing tags does not produce error.

The role also utilises the ``dig`` lookup plugin which requires ``dnspython``
package to be installed. Make sure you have the package available on controller
machine.


Why were these roles created?
-----------------------------

For a long time I have had a couple of Internet-facing servers where I hosted
all the IT infrastructure I needed for my day-to-day life.

This started off with some basic services, like mail and XMPP server, and in
time extended to include a web server, code repository etc.

As the number of services I used grew, I found it more difficult to track
updates and upgrades, let alone test them in reliable way. The biggest problem
in particular was lack of time to properly document all the different things
I've set-up.

Being familiar with some Puppet-based deployments, I've started looking into the
possibility of using a configuration management system. Ansible emerged as
something that I thought would be easy to use, due to its agent-less nature.

Once I passed some basic tutorials and got to know the system a bit, I decided
to start my journey on implementing the different roles, in the way I want them,
that would let me easily set-up my servers (and reinstall them, amongst other
things).

The roles you see within this repository are the fruit of this labour. I hope
you find them useful.


Features
--------

*Majic Ansible Roles* have the following features:

.. warning::

   Of course, you may want to take some statements with a pinch of salt, and
   possibly attribute them to either delusions of grandeur, or bragging :)

* Emphasis on small, self-hosted deployments.
* Modular role design where possible and where necessary.
* A number of roles covering common set-up of servers, databases, web server,
  XMPP server, mail server, and LDAP server.
* Streamlined integration with LDAP server for most of the services.
* Well-documented, with role reference documentation, examples, and test/sample
  site.
* Balanced implementation allowing both configurability and ease of deployment.
* Free Software, released under liberal BSD license.

Available roles:

* ``bootstrap`` (for setting-up servers for Ansible use)
* ``common`` (for setting-up basic security, accounts, and configuration on
  servers)
* ``database`` (for creating databases to be used for applications)
* ``database_server`` (for deploying a database server, MariaDB)
* ``ldap_client`` (for setting-up LDAP client configuration)
* ``ldap_server`` (for deploying an LDAP server, OpenLDAP)
* ``mail_forwarder`` (for setting-up forwarding of local mails to smart host,
  Postfix)
* ``mail_server`` (for deploying Postfix, Dovecot, ClamAV)
* ``php_website`` (for deploying PHP websites)
* ``preseed`` (for preparing Debian preseed files)
* ``prosody`` (for deploying XMPP server, Prosody)
* ``web_server`` (for deploying web server, Nginx)
* ``wsgi_website`` (for deploying WSGI/Python applications)


Support
-------

In case of problems with the roles or provided code, please do not hestitate to
contact the author at **majic-ansible-roles (at) majic.rs**. The project can be
found at:

* https://code.majic.rs/majic-ansible-roles
* https://projects.majic.rs/majic-ansible-roles


License
-------

Majic Ansible Roles is released under terms of *BSD (3-Clause) License*::

  Copyright (c) 2016, Branko Majic
  All rights reserved.

  Redistribution and use in source and binary forms, with or without modification,
  are permitted provided that the following conditions are met:

    Redistributions of source code must retain the above copyright notice, this
    list of conditions and the following disclaimer.

    Redistributions in binary form must reproduce the above copyright notice, this
    list of conditions and the following disclaimer in the documentation and/or
    other materials provided with the distribution.

    Neither the name of Branko Majic nor the names of any other
    contributors may be used to endorse or promote products derived from
    this software without specific prior written permission.

  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
  ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.