docker-spoon

Overview

Spoon creates on demand pairing environments using Docker.

We pair a lot using tmux & emacs / vim and wanted a way to create pairing environments which met a few criteria:

Would contain all the updates folks have contributed to the dev setup
Can be created on-demand as needed instead of having dedicated pairing environments and asking who's using what
Are console based to enable low latency remote pairing

Spoon is intended to make this process as easy as possible.

Why Spoon?

Learn more about spooning

Getting Started

These are the basics of how to get started. When you want to get into more detail see the full usage documentation.

Installation

$ gem install docker-spoon

(NOTE: if installing on Ubuntu this requires the installation of ruby-dev)

Configuration

Spoon has a number of options which you probably do not want to have to specify on the command line every time. The easiest way to set these for your environment is to add them to ~/.spoonrc. This file is just parsed as ruby, so you can put all kinds of stuff in here, but the basics should look something like this:

options[:url] = "tcp://192.168.1.3:4243"
options[:image] = 'spoon-pairing'
options["pre-build-commands"] = [
  "cp -rp #{ENV['HOME']}/.chef #{options[:builddir]}/chef"
]

The spoon configuration is described in more detail in the spoon config page

Building a compatible image

The spoon repository contains a functional spoon image. To build that just follow these steps:

git clone git@github.com:adnichols/docker-spoon.git
cd docker-spoon/docker
spoon -b

This creates an image that matches the default image name for spoon. If you specify a different image name in the configuration then that will be used when spoon builds an image.

Full Usage

Spoon has a number of operations it can perform:

Create and Connect to containers
List existing containers
List Images on the Docker host
Network to show a containers network configuration
Destroy a container
Kill containers
Restart containers
Build an image from a Dockerfile for use with spoon

In addition to these operations there are configuration values which are supported on the command line or in the configuration file. See Command Line Options for a list of tunables

Create and Connect

By default when you call spoon with no options it will try to connect to the spoon container that you specify. If that container doesn't exist, spoon will create it for you. Once spoon either creates a container or determines that one already exists it will start an ssh connection to the host. This will shell out to ssh and should honor your ssh configuration locally.

Example (container doesn't exist):

$ spoon fortesting
The `spoon-fortesting` container doesn't exist, creating...
Connecting to `spoon-fortesting`
pairing@dockerhost's password:

Example (container exists):

$ spoon fortesting
Connecting to `spoon-fortesting`
pairing@dockerhost's password:

NOTE: If a container has been stopped or killed, spoon will issue a start to the container & then attempt to ssh in.

List

The --list argument will list any containers on the destination Docker host which have the same prefix as specified by --prefix (default 'spoon-'). Images are listed without the prefix specified so that you can see only the containers you are interested in.

$ spoon -l
List of available spoon containers:
                      booger [ Stopped ]
                        jake [ Running ]
                        test [ Stopped ]

You can connect to Stopped containers in the same way as Running containers, spoon will re-start them as necessary.

List Images

The --list-images argument is conventient for listing the images available on the server. The image names should be exactly what you would use in the options[:image] configuration value.

$ spoon --list-images
Image: ["spoon_test:latest"]

To use this image you would set options[:image] = 'spoon_test'

Network

The --network NAME option will show the forwarded ports for a spoon instance. Any ports listed via EXPOSE in your Dockerfile should be exposed when a spoon container is started. If you are working with applications in a spoon container you can use this to forward ports & view what public ports are forwarded for your spoon container.

$ spoon -n jake
22 -> 49213

Destroy

The --destroy NAME option will destroy the specified spoon container.

$ spoon -d fortesting
Are you sure you want to destroy spoon-fortesting? (y/n) y
Destroying spoon-fortesting
Done!

To skip any confirmations:

add --force to the command-line
add options[:force] = true to your .spoonrc.

Kill

The --kill NAME option will kill a spoon container without destroying it. This is useful if you want to leave a container around but not in use for a period of time. Containers may be started again simply by connecting to them.

Restart

The --restart NAME option will kill and then start a container. This is useful if you have a container which has gotten into a bad state or where you've started processes you simply want to easily kill off.

Build

The --build option will build a docker image from the build directory specified by --builddir (default '.'). This has the same expectations as the docker build command.

Command Line Options

The following options may be specified either on the command line or in the spoon configuration file. Note that command line options take precedence over options in the configuration file.

--builddir, This is the directory where the build process will look for a Dockerfile and any content added to the container using ADD.
--config, configuration file to read, defaults to ~/.spoonrc
--image, The image name to use when starting a spoon container.
--portforwards, This is a comma separated list of ports to forward over ssh. The format is either sourceport:destport or just sourceport in which case the same port will be used for source & destination. This may be used after container creation to add ports ad-hoc
--ports, Comma separated list of ports to expose upon container creation by Docker. Unlike --portforwards this is only available at container creation
--prefix, The prefix to use for creating, listing & destroying containers.
--privileged, Starts a new container in with Privileged mode true, only applicable on container creation.
--url, The url of the Docker API endpoint. This is in the format supported by the docker -H option. This will also read from the environment variable DOCKER_HOST if this argument is not specified and that env var exists.
--nologin, This option is used for testing. It performs all actions up to the point of executing an ssh connection and then returns.
--debug, Enables some debugging
--debugssh, Enables SSH debugging
--version, Shows the version

These options and others are described in greater detail in the configuration file documentation.

Container expectations

When building an image for use with docker-spoon you must build an image which runs an ssh daemon. An example of a Dockerfile which creates an image which runs ssh is included in the docker/ directory inside this repository

Contributing

Fork it ( https://github.com/adnichols/docker-spoon/fork )
Create your feature branch (git checkout -b my-new-feature)
Make your changes, add tests and make sure all tests pass (rake)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request