.. _quick_start:

Quick start
===========

You can try out DebOps without installing it on your computer, by using
a Docker container or a Vagrant virtual machine to execute Ansible commands.


Start the Ansible Controller host
---------------------------------

DebOps uses the concept of an "Ansible Controller", a central management host
where Ansible playbooks are executed in a "push" mode against other hosts.
Normally DebOps would be installed on that host either manually or through
a package manager, however you can set one up using either a Docker container
or a Vagrant virtual machine and execute Ansible commands from there.

The Ansible Controller can also be managed by DebOps as long as it's based on
a compatible operating system, ie. Debian or Ubuntu. A suitable configuration
to do so will be automatically generated for you in the
:file:`~/src/controller/` directory located on the container/VM.

.. warning::

   The default configuration assumes that this is a testing environment - for
   example, `Diffie-Hellman parameters`__ generated by the :ref:`debops.dhparam` role
   are very small, only 512 bytes, to make their generation faster. If you want to
   use the configuration located in :file:`~/src/controller/` directory against
   production hosts, you should review it before doing so.

.. __: https://security.stackexchange.com/questions/94390/whats-the-purpose-of-dh-parameters

.. _quick_start__docker:

Quick start with Docker
~~~~~~~~~~~~~~~~~~~~~~~

Start a Docker container which acts as an Ansible Controller host with DebOps
support, based on Debian Buster:

.. code-block:: console

   docker run -it --rm debops/debops

The DebOps Docker images are automatically regenerated and should contain
latest changes. You can look at the `DebOps Dockerfile`__ for details about the
image configuration.

.. __: https://github.com/debops/debops/blob/master/Dockerfile


.. _quick_start__vagrant:

Quick start with Vagrant
~~~~~~~~~~~~~~~~~~~~~~~~

Start a Vagrant VM which acts as an Ansible Controller host with DebOps
support, based on Debian Stretch:

.. code-block:: console

   git clone -b stable-1.1 https://github.com/debops/debops ; cd debops
   vagrant up && vagrant ssh

The configuration relies heavily on your Vagrant environment. Having a real
domain is benefical. The box can be used to manage other Debian hosts as well.

Vagrant will include contents of the cloned DebOps repository in the
:file:`/vagrant/` directory on the created VM. This can be useful for project
development.

See the `DebOps Vagrantfile`__ for more details and configuration variables.

.. __: https://github.com/debops/debops/blob/master/Vagrantfile


Run the DebOps playbook against the host
----------------------------------------

When your desired container/VM is up and ready, you can find the prepared
DebOps project configuration in the :file:`~/src/controller/` subdirectory of the
unprivileged user account. To run the DebOps playbook against the host, execute the
commands:

.. code-block:: console

   cd ~/src/controller
   debops

Docker notes
~~~~~~~~~~~~

Not everything will work as expected inside a Docker container, for example
various daemons are not restarted properly. However you can still use the
container to manage remote DebOps hosts, and inspect the configuration files
generated when DebOps has been run against the container itself.

Some of the remote host state as well as the general environment is managed on
the Ansible Controller itself. If you want to use a Docker container as one,
you might want to enable a persistent storage volume for the project
directories, where :ref:`secrets <debops.secret>`,
:ref:`Certificate Authorities <debops.pki>` and other data are kept safe.
