Utility tasks for Fabric¶
Included utility tasks perform some basic actions within Docker. When importing them into your
might want to assign an alias to the module, for having a clear task namespace:
import dockerfabric.tasks as docker
Then the following commands work directly from the command line, e.g.
fab <task name>. A basic description of
each task is displayed when running
fab --list – the following sections describe a few further details.
- If not already installed,
install_docker_centos()installs the most recent release of Docker on the remote host. Furthermore, it assigns the currently signed-in user to the docker user group. This is required in order for the Docker command line interface to work. Note that the user needs to create a new session for the group assignment to be effective. Fabric provides the function
disconnect_all()to enforce this if necessary.
- Provided that Docker can only be contacted via a Unix socket,
build_socat_centos()is required to handle the forwarding from the SSH connection.
install_socat()downloads and compiles socat from source.
- Once you have a socat binary, it can be replicated to other hosts using
- As an alternative to compiling from source and copying, you can use the package manager to install socat.
Currently aforementioned utility tasks are targeted to Ubuntu and CentOS hosts. This may become more flexible in future releases.
General purpose tasks¶
Socat does not terminate after all connections to the host have been closed. Although this can be changed by setting
False, there may be instances where it may be necessary to close the process manually, e.g.
fork setting has just recently been set. The task
reset_socat() finds socat‘s
process id(s) and sends a kill signal.
For configuration between containers and firewalls, the host’s IP address can be obtained using the tasks
get_ipv6(). Without further arguments it returns
the address of the docker0 interface. Specifying a different interface is possible via the first argument:
returns the IPv4 address of the first network adapter. IPv6 addresses can additionally be expanded, e.g.
returns the full address instead of the abbreviated version provided by
The following tasks are directly related to Docker and processed by the service on the remote host.
- Ports and multiple container names (e.g. linking aliases) are broken into multiple lines,
- images are by default shown without their registry prefix (can be changed by passing
- the absolute creation timestamp is printed,
- and by default all containers are shown (can be changed by passing an empty string as the first argument).
In the output of
- parent image ids are shown,
- and also here the absolute creation timestamp is printed.
As of version 0.3.0, container maps are recommended to be set in
env.docker_maps (as list or single entry) and
multiple clients to be configured in
env.docker_clients. In that setup, the lifecycle of containers, including their
dependencies, can be entirely managed from the command line without creating individual tasks for them.
actions contains the following actions:
create()- Creates a container and its dependencies.
start()- Starts a container and its dependencies.
stop()- Stops a container and its dependents.
remove()- Removes a container and its dependents.
startup()- Creates and starts a container and its dependencies.
shutdown()- Stops and removes a container and its dependents.
update()- Updates a container and its dependencies. Creates and starts containers as necessary.
script()- Uploads and runs a script inside a container, which is created specifically for that purpose, along with its dependencies. The container is removed after the script has completed.
single_cmd()- Similar to
script(), but not uploading contents beforehand, for running a self-contained command (e.g. Django migrate, Redis flusdhdb etc.). If this produces files, the results can be downloaded however.
There is also a generic action
perform(). Performs an action on the given container map
and configuration. There needs to be a matching implementation in the policy class.
Given the lines in
from dockerfabric import yaml, actions env.docker_maps = yaml.load_map_file('/path/to/example_map.yaml', 'example_map') env.docker_clients = yaml.load_clients_file('/path/to/example_clients.yaml')
The web server from the YAML import example may be started with
runs the web server and its dependencies. The command
stops, removes, re-creates, and starts the container if the image as specified in the container configuration (e.g.
nginx:latest) has been updated, or mapped volumes virtual filesystems are found to mismatch the dependency
containers’ shared volumes.
cleanup_containers()removes all containers that have the Exited status;
cleanup_images()removes all untagged images, optionally with the argument
Truealso images without a
latesttag. Additional tags can be specified by setting the environment variable
remove_all_containers()stops and removes all containers from the host.
Especially during the initial deployment you may run into a situation where manual image transfer is necessary. For example, when you plan to use your own registry, but would like to use your own web server image for a reverse proxy, the following tasks help to download the image from your build system to the client, and upload it to the production server:
save_image() with two arguments: Image name or id, and file name. If the file name is
omitted, the image is stored in the current working directory, as
<image>.tar.gz. For performance reasons,
save_image() currently relies on the command line client. The compressed tarball is generated
on the host.
load_image() uploads a local image to the Docker host. In this case the Docker
Remote API is used. It accepts plain and gzip-compressed tarballs. The local image file name is the first argument.
Since the API often times out for larger images (default is 60 seconds), the period is extended temporarily to
120 seconds. This can optionally be adjusted with a second argument, e.g.
for an image that might take longer to upload due to a slow connection.