This document describes how to install and upgrade DebOps scripts, roles and playbooks, as well as additional software requirements that are needed by the DebOps roles to be used properly.

Quick setup

DebOps uses latest Ansible stable release, which can be installed using variety of methods. On MacOS X, you should use Ansible from PyPI (Python Package Index), not Homebrew. Various DebOps roles require additional Python packages on the Ansible Controller; see the list in the DebOps prerequisites section for more details.

You can install DebOps on a host that supports Ansible and Python using a package from PyPI:

pip install debops

To perform an upgrade of an existing script installation, you can use the command:

pip install --upgrade debops

After installation, you need to download the DebOps roles and playbooks. To do that, on your regular user account (not root) run the command:


This command is used to download the roles and playbooks on a fresh installation, as well as to update the existing set of roles and playbooks.

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 $XDG_DATA_HOME/debops/ which usually is expanded to ~/.local/share/debops/;
  • on MacOSX systems, it will be ~/Library/Application Support/debops

Afterwards, you should check out the Getting Started guide to learn how to create and manage your first DebOps environment.

Ansible Controller

The DebOps playbooks and roles are designed to be used in an Ansible "push" model, with a central host called an "Ansible Controller" executing Ansible playbooks and connecting to the "remote hosts" to manage them over SSH. Ansible Controller host is not an integral part of the DebOps environment, which means that this host does not need to be available at all times for other hosts managed by DebOps. You can use DebOps playbook and roles on a laptop or another device that can then be disconnected from the network and securely stored offline.

The Ansible Controller operating system needs to be able to run Ansible and Python. Preferably the OS can be a Debian GNU/Linux Stable release, which then can be managed by DebOps itself; other operating systems that support Ansible and Python can also be used (Ubuntu and other Linux distributions, MacOS X) however they may have issues.

DebOps prerequisites

To use DebOps roles and playbooks, you need some additional tools on your Ansible Controller besides the official scripts. Some of these tools will be installed for you by pip as prerequisites of the DebOps scripts if they are not already present on the host.


You need to install Ansible to use DebOps roles and playbooks. The project is focused on current stable Ansible release, which means that the Ansible packages provided in some OS distributions like Debian Stable are not sufficient.


This is a Python library used to manipulate strings containing IP addresses and networks. DebOps provides an Ansible plugin (included in Ansible 1.9+) which uses this library to manipulate IP addresses.

You can install netaddr either using your favorite package manager, or through pip.


This Python library is used to access and manipulate LDAP servers. It can be installed through your package manager or using pip.


This Python library is used to encrypt random passwords generated by DebOps and store them in the secret/ directory.


This Debian package provides the uuidgen command, which is used to generate unique identifiers for hosts which are then saved as Ansible facts and can be used to identify hosts in the playbook. In most Linux or MacOSX desktop distributions this command should be already installed.


This is an optional application, which is used by the debops-padlock script to encrypt the secret/ directory within DebOps project directories, which holds confidential data like passwords, private keys and certificates. EncFS is available on Linux distributions, usually as the encfs package.


GnuPG is used to encrypt the file which holds EncFS password; this allows you to share the encrypted secret/ directory with other users without sharing the password, and using private GPG keys instead. debops script will automatically decrypt the keyfile and use it to open an EncFS volume.

GnuPG is usually installed on Linux or MacOSX operating systems.


Git is required to be installed for DebOps to be used. Git is a version control system. If it is not already install, it can be usually be installed using your favourite package manager.