This section of the documentation describes how to install all of the components needed to run DebOps playbooks.
DebOps is designed to use Ansible in a "push" model, where Ansible commands are executed on remote hosts from a central machine, the "Ansible Controller". This host can use any OS that Ansible is supported on - Linux, macOS, Windows with the Windows Subsystem for Linux, etc. Use of an OS that can be managed using DebOps (Debian, Ubuntu) might be preferable in the long run, however.
DebOps doesn't use any active services on the Ansible Controller host in the
infrastructure that is managed, therefore you might consider a laptop or
a virtual machine which can be turned off or put offline when not in use, for
better security. You should consider usage of an encrypted filesystem for
DebOps project directories due to sensitive nature of some of the data stored
secret/ directory, like passwords,
Certificate Authority files, etc.
Current, stable Ansible release is required to run DebOps playbooks and roles. Older Ansible releases may work for a time, but support for them is not guaranteed by the project.
Ansible can be installed in a variety of methods, you can choose your preferred one depending on the platform you use for the Ansible Controller. There are some caveats on specific platforms, described below.
On Debian Stretch, you can use the ansible package from the
stretch-backportsrepository; Ansible version included in the Stretch release is not sufficient anymore.
On older Debian releases, you should consider installing Ansible by creating a
.debpackage from the official git repository sources. You can find a bootstrap-ansible script which can do this for you automatically in the debops.ansible Ansible role
debopsPython package which contains scripts and modules used by the project is currently available only through PyPI. Due to this, Ansible installed using Homebrew might not work correctly with DebOps playbooks and/or roles. In that case, you should install Ansible from PyPI.
The debops.pki role requires Bash 4.x on the Ansible Controller for the management of the internal Certificate Authority. On macOS, you might need to upgrade an existing Bash 3.x installation before using DebOps.
Some of the DebOps roles may depend on additional software installed on the Ansible Controller. Some of these packages are available by default, the rest can usually be installed using a system package manager.
- The encfs command is used to manage an encrypted user-space
filesystem which holds the contents of the
secret/directory. This is an optional feature, useful if you want to protect your secrets at rest.
- The git tool is used to manage DebOps monorepo installation or updates by the debops-update command.
- The gpg command is used by the debops-padlock script to encrypt and decrypt files with EncFS passphrase. It's usually already installed by the operating system.
- This is a Python library that provides various functions related to DNS
queries. Some of the DebOps roles rely on DNS records to get information
about the environment, like addresses of centralized services provided via
DNS SRV records. In Ansible, this library is required by the
- This is a Python library which can be used to interface with the LDAP
servers, Ansible ldap_attr and ldap_entry modules use it. You will
need to install it if you want to manage LDAP using DebOps roles. It's
python-ldapAPT package in Debian, it can also be installed via PyPI.
- This module provides a compatibility layer between Python 2.7 and Python 3.x versions. It allows creation of code that can be run in both old and new Python environments without changes.
- This is a Python library which can be used to manipulate IP addresses in
different ways. It's used by the
ipaddr()Ansible filter plugin used in some of the DebOps roles. On Debian, it's available in the python-netaddr APT packages, it can also be installed via PyPI.
- This is a Python library which is used by Ansible
password()lookup plugin to encrypt passwords on Ansible Controller. This is required in DebOps roles that use debops.secret role to generate random passwords and store them in the
secret/directory. The library is available on Debian as the
python-passlibAPT package, it can also be installed via PyPI.
- This command is used to generate unique UUID strings for hosts which are then
stored as Ansible facts. On Debian, it's available in the
The DebOps scripts are available via PyPI, to install them on the Ansible Controller you can use the command:
sudo pip install debops
An upgrade is also possible with the command:
sudo pip install --upgrade debops
At the moment installation on an unprivileged user account doesn't work as expected, system-wide installation should work fine.
If you installed DebOps using a Python package equal or newer than
the installation should include a set of DebOps playbooks and roles located in
debops Python package directory. The scripts should automatically find
them and use them as necessary.
If you installed an older DebOps release, or you want to use the latest changes in DebOps development branch, you can use the debops-update command to download or update the DebOps monorepo. The git repository will be cloned to the directory:
You can also execute the command:
This will clone the repository to the
debops/ subdirectory inside of
the specified directory. This allows you to create a "local" copy of the DebOps
monorepo which will be used by the debops script instead of the
Running the debops-update command will update the existing DebOps monorepo, either the user-wide clone, or the one found in a local directory.
Installation in a Python virtualenv¶
You can install Ansible and DebOps in a Python virtualenv environment. These instructions are for Debian Jessie or Debian Stretch, they should also work in Ubuntu.
First install python virtual-env packages and other system dependencies required for building:
sudo apt-get install python-virtualenv virtualenv build-essential \ python-dev libffi-dev libssl-dev libsasl2-dev \ libldap2-dev
Next we activate the DebOps virtual environment and prepare it for use:
virtualenv debops-venv cd debops-venv source bin/activate pip install --upgrade setuptools pip install ansible debops
After DebOps is installed, you might want to create symlinks to the
debops scripts in
/usr/local/bin/ directory to make the
commands available outside of the the Python virtual environment:
ln -s debops-venv/bin/ansible /usr/local/bin/ansible ln -s debops-venv/bin/ansible-playbook /usr/local/bin/ansible-playbook ln -s debops-venv/bin/debops /usr/local/bin/debops ln -s debops-venv/bin/debops-init /usr/local/bin/debops-init ln -s debops-venv/bin/debops-update /usr/local/bin/debops-update ln -s debops-venv/bin/debops-defaults /usr/local/bin/debops-defaults
If your Ansible/DebOps-Controller machine has SElinux enabled, delegating tasks
localhost is problematic. A workaround for this issue is to add
a definition for
localhost to your inventory, outside of the
[debops_all_hosts] inventory group:
This makes Ansible use the SElinux libraries from the python-environment outside of the virtualenv.