Getting started

Using from Docker

The plumbery Docker image is the simplest and easiest way to use Plumbery, you can process multiple deployments at the same time, isolate the processes and there is no requirement to install any additional software. to download the plumbery image simply run

This will download the latest image from

You can then run the image with the following environment variables:

  • MCP_USERNAME - your API username
  • MCP_PASSWORD - your API password
  • SHARED_SECRET - the password for the deployed servers
  • FITTINGS - The URL to a fittings.yaml file, look in for examples, this can be a:
    • A FTP/FTPS address


Optional arguments

  • WGET_OPTS can be set for the fetching of the fittings file, the following options are supported:
    • "--no-check-certificate" to disable SSL certificate validation
    • "--ftp-user=user --ftp-password=password" for FTP credentials
    • "--no-passive-ftp" disable FTP passive transfer mode, for use with proxys
    • "--http-user=user --http-password=password" for HTTP basic authentication
  • OPTS can be set for the plumbery specific options, "-d" i.e. debug mode is enabled by default, any of the following options can be combined
    • "--safe" to only run the fittings file but not make any changes (i.e deployments) for testing
  • ACTION is "deploy" by default, but can be set to any of the potential actions for plumbery

Using from Python

You will need the latest version of the Python 2.7 language, which you can download for Linux, Mac and Windows at


Install Apache Libcloud

The orchestration of cloud services is a hot topic these days. Apache Libcloud is evolving swiftly thanks to many contributions. For this reason, you are encouraged to install the development version of the library:


This version is the one used by Plumbery, and it may be more advanced than the stable version of Apache Libcloud.


Install the plumbery package

Plumbery is available as a python package, so the installation, the upgrade, and the removal of the software are really easy.


Install the plumbery package

Plumbery is available on PyPi. You can install latest stable version using pip:


The installation of python-dev is required for the installation of the module netifaces, that is used by Plumbery to get information about network interfaces.

For installation on Windows, you may need to first install the Python Compiler for VC++. Note this only works for Python 2.7. If you get an error on installation saying “error: Unable to find vcvarsall.bat” this indicates you need to install this package.


Upgrade the plumbery package

Use the following command to retrieve the version of plumbery that has been installed on a computer:


You can compare this information with reference information posted at Plumbery package at PiPy. If you have used pip to install the software, then you can use it again to upgrade the package:


Remove the plumbery package

Why would you bother about a small set of files at a computer? Anyway, if needed here is the command to remove Plumbery from a python environment:


If you need the full development environment

Maybe you want to upgrade the on-line documentation of Plumbery. For this you have to edit the .rst files that are in the docs directory. Or you want to add a new polisher in plumberypolishers, for a new or special usage. Or you would like to troubleshoot an issue and put some print() statements in the code. And why not fix a bug or even implement a new feature?

In all these situations, you would like to get a full copy of all files, and change them at will on your own computer.


Install the plumbery development environment

Some precautions are needed if you really want to contribute to the Plumbery project. This is not really difficult, if you follow comprehensive instructions provided at How to contribute to Plumbery?

On the other hand, to dump a full copy of the software then you can clone the latest development version from Plumbery repository at GitHub:


Remove the plumbery development environment

Type the following command to clean the python runtime:


Then you have to go back to the directory where plumbery was downloaded, and remove files by yourself.


Configure and test your installation

This section describes the standard workflow which you follow when working with Plumbery.


Put secrets into local environment (Linux)

By default Plumbery reads credentials and other secrets from the environment of the computer where it is running.

If you are running Ubuntu you could do:

and type text like the following:


Put secrets into local environment (Windows)

By default Plumbery reads credentials and other secrets from the environment of the computer where it is running.

Download into %APPDATA%libcloud

Run  the following commands to apply an environment variable from inside the PowerShell command window


Prepare your fittings plan

Since infrastructure is code, your first task is to document your target deployment into a text file. In the context of Plumbery, this is called the fittings plan, and it is usually put into a file named fittings.yaml.

With that in hands, you can then use Plumbery to act on the infrastructure and on nodes. The engine has built-in code to cover the full life cycle:

  • build the infrastructure and configure it
  • build nodes
  • start nodes
  • polish nodes – this is to say that some processing is applied to each node
  • stop nodes
  • destroy nodes
  • destroy the infrastructure and release all resources

Check your installation with demonstration files

In the demos directory that is coming with the plumbery development environment you will find a reference fittings.yaml file. Else you can download the reference fittings plan and use it at will.

To check your installation, you would like to ask plumbery to build a first inventory of your fittings:


If plumbery reports interactively where it is plumbing and what it is doing, then your installation is working great. Congratulations!

Then your next ambition may be to pass through a full life cycle, for example with the following command:

$ ./

This program creates multiple resources, configures them, starts and stops them, then destroys everything. It takes about 30 minutes to execute in total. A lot of information is reported on screen, so you have the ability to monitor what Plumbery is doing, and to understand any problem eventually.