.. _debops-logodebops-logo-debops:
|DebOps logo| DebOps
====================
*Your Debian-based data center in a box*
|GitHub CI| |GitLab CI| |CII Best Practices| |REUSE status| |RSS
commits|
The DebOps project provides a set of general-purpose
`Ansible <https://github.com/ansible/ansible/>`__ roles that can be used
to manage `Debian <https://www.debian.org/>`__ or
`Ubuntu <https://www.ubuntu.com/>`__ hosts. In addition, a default set
of Ansible playbooks can be used to apply the provided roles in a
controlled way, using Ansible inventory groups.
The roles are written with a high customization in mind, which can be
done using Ansible inventory. This way the role and playbook code can be
shared between multiple environments, with different configuration in to
each one.
Services can be managed on a single host, or spread between multiple
hosts. DebOps provides support for different SQL and NoSQL databases,
web servers, programming languages and specialized applications useful
in a data center environment or in a cluster. The project can also be
used to deploy virtualization environments using KVM/libvirt, Docker or
LXC technologies to manage virtual machines and/or containers.
You can find out more about DebOps features on the `project’s
documentation page <https://docs.debops.org/>`__.
Quick start
-----------
Start a Docker container which acts as an Ansible Controller host with
DebOps support, based on Debian Buster:
::
docker run -it --rm debops/debops
cd src/controller ; debops run common --diff
Or, create a Vagrant VM which acts as an Ansible Controller host:
::
git clone https://github.com/debops/debops
cd debops && vagrant up && vagrant ssh
cd src/controller ; debops run common --diff
You can use configuration in the ``src/controller`` subdirectory to try
out DebOps against the container/VM, or create your own DebOps project
directory using ``debops project init`` command.
More quick start tips can be found `in the DebOps quick start
guide <https://docs.debops.org/en/master/introduction/quick-start.html>`__.
Installation
------------
You can install the `DebOps Python
package <https://pypi.org/project/debops/>`__, which includes the DebOps
roles and playbooks, as well as additional scripts which can be used to
setup separate project directories and run Ansible in a convenient way.
To install the Python package with Ansible and other required
dependencies, run the command:
::
pip install --user debops[ansible]
Alternatively, DebOps roles are available on `Ansible
Galaxy <https://galaxy.ansible.com/debops/debops/>`__ as an Ansible
Collection which can be installed using the ``ansible-galaxy`` command:
::
ansible-galaxy collection install debops.debops
Read the `installation
instructions <https://docs.debops.org/en/master/introduction/install.html>`__
in the DebOps documentation for more details about required software and
dependencies.
Getting started
---------------
Ansible uses SSH to connect to and manage the hosts. DebOps enforces the
SSH security by disabling password authentication, therefore using SSH
keys to connect to the hosts is strongly recommended. This can be
changed using the inventory variables.
During initial deployments you might find that the firewall created by
DebOps blocked you from accessing the hosts. Because of that it’s
advisable to have an out-of-band console access to the host which can be
used to login and troubleshoot the connection.
Create a new environment within a DebOps “project directory”, add some
hosts in the Ansible inventory and run the default DebOps playbook
against them to configure them:
::
# Create a new environment
debops project init ~/src/projects/my-environment
cd ~/src/projects/my-environment
# Modify the 'ansible/inventory/hosts' file to suit your needs, for example
# uncomment the local host to configure it with DebOps
# Run the full playbook against all hosts in the inventory
debops run site
# Run the common playbook against specific host in the inventory
debops run common -l <hostname>
You should read the `Getting Started with
DebOps <https://docs.debops.org/en/master/introduction/getting-started.html>`__
guide for a more in-depth explanation of how the project can be used to
manage multiple hosts via Ansible.
Development
-----------
Create `a fork of this
repository <https://github.com/debops/debops/fork>`__ and clone it to
your workstation. Create a development DebOps environment and symlink
the forked repository in it. Now you can create new playbooks/roles in
the forked repository and see their results in the development
environment.
::
git clone git@github.com:<username>/debops ~/src/github.com/<username>/debops
cd ~/src/github.com/<username>/debops
git remote add upstream https://github.com/debops/debops.git
debops project init ~/src/projects/debops-devel
cd ~/src/projects/debops-devel
ln -s ~/src/github.com/<username>/debops debops
You can pull latest changes to the project from the upstream repository:
::
cd ~/src/github.com/<username>/debops
git checkout master
git fetch upstream
git rebase upstream/master
Read the `development
guide <https://docs.debops.org/en/master/developer-guide/contribution-workflow.html>`__
file for more details about the DebOps development process.
Contributing
------------
DebOps development is done via a distributed development model. New
features and changes are prepared in a `fork of the official
repository <https://github.com/debops/debops/fork>`__ and are published
to the original repository via GitHub pull requests. PRs are reviewed by
the DebOps developer team and if accepted, are merged in the main
repository.
GPG-signed ``git`` commits are preferred to ensure authenticity.
Read the `contributing
guide <https://docs.debops.org/en/master/developer-guide/contributing.html>`__
file for more details about how to contribute to DebOps.
Licensing
---------
The DebOps project is licensed under the `GNU General Public License 3.0
or later <https://www.gnu.org/licenses/gpl-3.0>`__. You can find full
text of the license in the
`LICENSES/GPL-3.0-or-later.txt <https://github.com/debops/debops/blob/master/LICENSES/GPL-3.0-or-later.txt>`__
file.
Some files included with the DebOps project use a different license. The
licenses are marked in these files using the `SPDX license
identifiers <https://spdx.org/ids>`__ and can be found in the
``LICENSES/`` subdirectory. They are also included in the project
tarballs, Ansible Collections and Python packages. The project uses the
`REUSE Specification <https://reuse.software/spec/>`__ and its
associated tool to check and verify copyright and license information in
all files.
.. |DebOps logo| image:: https://raw.githubusercontent.com/debops/debops/master/lib/images/debops-small.png
:target: https://debops.org/
.. |GitHub CI| image:: https://github.com/debops/debops/workflows/Continuous%20Integration/badge.svg
:target: https://github.com/debops/debops/actions?query=workflow%3A%22Continuous+Integration%22
.. |GitLab CI| image:: https://gitlab.com/debops/debops/badges/master/pipeline.svg
:target: https://gitlab.com/debops/debops/pipelines
.. |CII Best Practices| image:: https://bestpractices.coreinfrastructure.org/projects/237/badge
:target: https://bestpractices.coreinfrastructure.org/en/projects/237
.. |REUSE status| image:: https://api.reuse.software/badge/github.com/debops/debops
:target: https://api.reuse.software/info/github.com/debops/debops
.. |RSS commits| image:: https://img.shields.io/badge/RSS-commits-orange.svg
:target: https://github.com/debops/debops/commits/master.atom