Shed

Protect containers under the roof.

Overview

Shed is a wrapper around the Docker client. This means that most commands just call the corresponding Docker command, but for all related containers. Additionally, there are some new commands. Shed is written in Bash and it works reading some configurations files that are also Bash scripts, declaring parameters with string, list or dictionary values.

Scripts

For easy management, the Shed commands are divided in several separated scripts. Each script has a reference document:

• reference-hub.md: documentation for shed-hub commands.

• reference-image.md: documentation for shed-image commands.

• reference-container.md: documentation for shed-container commands.

• reference-network.md: documentation for shed-network commands.

• reference-volume.md: documentation for shed-volume commands.

shed-hub

The shed-hub script provides access to the most general Docker commands. Two commands are not in Docker, and the modified commands send output lo less.

Command	New	Modified
build [OPTIONS]	x
events [OPTIONS]
info		x
inspect [OPTIONS] CONTAINER|IMAGE [CONTAINER|IMAGE...]
login [OPTIONS] [SERVER]
logout [SERVER]
pull [OPTIONS] NAME[:TAG|@DIGEST]
push NAME[:TAG]
query [OPTIONS] CONTAINER|IMAGE [QUERY]	x
search [OPTIONS] TERM
version		x

shed-image

The shed-image script provides access to the image related Docker commands. The new command purge remove dangling images, and the modified command rm is an alias to the Doker rmi command.

Command	New	Modified
build [OPTIONS] PATH | URL | -
commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]
history [OPTIONS] IMAGE
images [OPTIONS] [REPOSITORY]
import URL|- [REPOSITORY[:TAG]]
load [OPTIONS]
purge [OPTIONS]	x
rm [OPTIONS] IMAGE [IMAGE...]		x
save [OPTIONS] IMAGE [IMAGE...]
tag [OPTIONS] IMAGE[:TAG] [REGISTRYHOST/][USERNAME/]NAME[:TAG]

shed-container

The shed-container script provides access to the container related Docker commands. Most of the commands accept options to extend the command to sets of containers:

-a, --all       Apply command to all containers
-l, --latest    Apply command to the latest created container
-p, --propagate Propagate command to linked containers

For clarity, the shed-container commands are presented in two lists.

General commands

Sets	Command	New	Modified
	build [FILE]	x
	cp [OPTIONS] CONTAINER:PATH LOCALPATH | -
	cp [OPTIONS] LOCALPATH | - CONTAINER:PATH
	create [OPTIONS] IMAGE [COMMAND] [ARG...]
-l	diff CONTAINER
-l	export CONTAINER
-l	links [OPTIONS] CONTAINER	x
-l	port CONTAINER [PRIVATE_PORT[/PROTO]]
	ps [OPTIONS]
	rename OLD_NAME NEW_NAME
-alp	rm [OPTIONS] CONTAINER [CONTAINER...]
-alp	status CONTAINER	x

Runtime commands

Sets	Command	New	Modified
-l	attach [OPTIONS] CONTAINER
	exec [OPTIONS] CONTAINER COMMAND [ARG...]		x
-alp	kill [OPTIONS] CONTAINER [CONTAINER...]
-l	logs [OPTIONS] CONTAINER		x
-alp	pause CONTAINER
-alp	restart [OPTIONS] CONTAINER [CONTAINER...]
	run [OPTIONS] IMAGE [COMMAND] [ARG...]
	ship [OPTIONS]	x
-alp	start [OPTIONS] CONTAINER [CONTAINER...]
	stats [OPTIONS] CONTAINER
-alp	stop [OPTIONS] CONTAINER [CONTAINER...]
-l	top CONTAINER [list OPTIONS]		x
-alp	unpause CONTAINER
-alp	wait CONTAINER [CONTAINER...]

shed-network

The shed-network script provides access to the network related Docker commands.

Command	New	Modified
create [OPTIONS] NETWORK-NAME
connect [OPTIONS] NETWORK CONTAINER
disconnect [OPTIONS] NETWORK CONTAINER
inspect [OPTIONS] NETWORK [NETWORK...]
ls [OPTIONS]
rm [OPTIONS] NETWORK [NETWORK...]

shed-volume

The shed-volume script provides access to the volume related Docker commands. The new command purge remove dangling volumes.

Command	New	Modified
create [OPTIONS]
inspect [OPTIONS] VOLUME [VOLUME...]
ls [OPTIONS]
purge [OPTIONS]	x
rm [OPTIONS] VOLUME [VOLUME...]

Shedfiles

For every project managed with Shed you must write two configuration files, one for the whole project named Shedfile and one for each container named like the container and with the shed extension, for example container.shed.

Also, if you want to configure the implicit call to docker build made by shed-hub, you can define a file called Dockerfile.shed for each image to build.

These files are Bash files, and all the power of Bash is available. The files define parameters, with string, list o dictionary values.

Strings, lists and dictionaries in Bash:

STRING='Hello'                          # 'declare' or 'local', optional
declare -a LIST=( a b c )               # 'declare' or 'local', optional
declare -A DICTIONARY=( [k]=v [j]=w )   # 'declare' or 'local' mandatory

Lists usage:

$ echo ${LIST[0]}
a
$ echo ${LIST[@]}
a b c
$ echo ${!LIST[@]}
0 1 2

Dictionaries usage:

$ echo ${DICTIONARY[k]}
v
$ echo ${DICTIONARY[@]}
w v
$ echo ${!DICTIONARY[@]}
j k

Project shedfile

This is a project Shedfile example:

# prefixed to image names if defined
PROJECT=	# null project

# images to pull
IMAGES=(
    'busybox:latest'
)

# images to build
BUILDS=(
    '.'
)

# containers to create (order is significant)
CONTAINERS=(
    'echo'
    'receiver'
)

Container shedfile

This is a container Shedfile example:

# Base image
IMAGE='busybox:latest'

# Set environment variables
ENVIRON=(
    [PATH]='/bin:/usr/bin'
)

# Container host name
HOSTNAME=$(basename $BASH_SOURCE .shed)

# Add link to another container in the form of name:alias
LINK=(
    'echo:echo.domain.com'
)

# Keep STDIN open even if not attached
INTERACTIVE='true'

# Allocate a pseudo-TTY
TTY='true'

All the parameters in the container Shedfile are forwarded to the docker create command, and the names are the same (but adapted to the Bash syntax). The file docs/container.shed contains all available parameters with default values if defined.

Dockerfile shedfile

This is a dockerfile Shedfile example:

# Names and values of a buildarg(s)
BUILD_ARG=( 'user=admin' )

# Always remove intermediate containers
FORCE_RM='true'

# Suppress the build output and print image ID on success
QUIET='true'

# Additional tags
TAG=(
    'mary/docker-whale:1.3'
    'private.com/docker-whale:1.3'
)

All the parameters in the dockerfile Shedfile are forwarded to the docker build command, and the names are the same (but adapted to the Bash syntax). The file docs/dockerfile.shed contains all available parameters with default values if defined.

Names for images and containers

Shed will choose names for images and containers using the following algorithms.

Images

The full syntax for the string defining images in the project Shedfile parameter BUILDS is

[REGISTRYHOST/][USERNAME/]NAME[#ALT][:TAG]

This is an extension to the Docker tag syntax, with the added [#ALT] used to define an alternative Dockerfile filename.

Image name algorithm:

1. If an alternative Dockerfile has been provided, this filename is choosen as the image name (without extension); if not, the basename of the image path will be the image name.

2. If the PROJECT parameter is defined and is not equal to the image name, this is prefixed with the PROJECT value and an underscore.

Image tags

Tagging algorithm:

1. All built images will be tagged with the latest tag.

2. If a tag is provided in the string that defines the image, a second tag will be added.

3. Additional tags can be defined in the TAG parameter in the dockerfile Shedfile.

Containers

Container name algorithm:

1. The names used in the CONTAINERS project Shedfile parameter are converted to lowercase. The corresponding .shed file must exist.

2. If the PROJECT parameter is defined and is not equal to the container name, this is prefixed with the PROJECT value and an underscore.

Configuration

Shed will try to load several configuration files, in this order:

• /usr/local/etc/shed.conf
• $HOME/.shed
• .shed

At this moment the only parameter you can define is TAGS_PREFIX, used to set default prefix for image names (without the ending /):

[REGISTRYHOST/][USERNAME/]NAME[#ALT][:TAG]
^^^^^^^^^^^^^^^^^^^^^^^^^^

The default value for TAGS_PREFIX is shed.

Installation

Simply put the scripts in your PATH, or run make install in the scripts source directory (just in case, read before the Makefile).

Documentation and tests

The directories docs and tests contains several files you can read and test.