Getting started
===============

After DebOps scripts are installed, you need to download playbooks and roles
provided with the project. To do that, you need to run command:

.. code:: shell

   debops-update

This script will download playbooks and roles from their GitHub repositories
into your user directory. Exact location is dependent upon your operating
system:

- on Linux systems, it will be :file:`$XDG_DATA_HOME/debops/` which usually is
  expanded to :file:`~/.local/share/debops/`;

- on MacOSX systems, it will be ``~/Library/Application Support/debops``;

When all roles are downloaded and installed, you can start using DebOps by
creating a project directory. This will be a directory which contains
everything related to a specific environment - Ansible inventory, custom
playbooks, roles, templates and files. Most of the time you will run commands
from the base of that directory. You can create it by running command:

.. code:: shell

   debops-init ~/project-directory

It can be anywhere in your filesystem. DebOps is designed to be used on an
unprivileged user account on Ansible Controller, so you don't need to be
``root`` in order to use it - most of the time you can use your existing user
account.

After entering your new project directory, you can see an :file:`ansible/`
directory which contains files related to Ansible, mostly inventory, secret
directory, playbooks and roles. You can also notice ``.debops.cfg``
configuration file which indicates to the DebOps script that this is indeed
a project directory and contains configuration related to it.

Main Ansible inventory file is ``ansible/inventory/hosts``. You should add
hosts that you want to manage to it, just make sure that you can access them
through SSH without issues. It's a good idea to start using groups right away
to keep many hosts under control. An example inventory file:

.. code:: ini

   [debops_all_hosts]
   host1
   host2

If you want, and your Ansible Controller host is Debian/Ubuntu based, you can
manage it using DebOps as well. You can do it by adding its hostname to Ansible
inventory with "local" connection type:

.. code:: ini

   [debops_all_hosts]
   myhostname ansible_connection=local

When all hosts you want to use are written in inventory and you checked the
connectivity, you can run main DebOps script to generate Ansible configuration
and execute default DebOps playbooks:

.. code:: shell

   debops

The ``debops`` command is a wrapper for :command:`ansible-playbook`, which means that
you can pass any :command:`ansible-playbook` parameters to it. For example, to limit
the Ansible run to a specific host, you can execute command:

.. code:: shell

   debops --limit host1

