Protect containers under the roof.

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.

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.

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.

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.

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.

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

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

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

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'
)

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.

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.

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

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.

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.

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.

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.

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

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