docker-spoon 0.8.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 44d1699d5dfe6932ecb60d0c9ab0da39f7d8aa9a
-  data.tar.gz: a8552620c5ee5b7ad52d08231f42ef7ad74d337f
+  metadata.gz: 033dbf20fbef7f0928d4ecf21632ec43ec3a5442
+  data.tar.gz: 6768b4fd3b7283562cb1b77be7a360459fb5fe8a
 SHA512:
-  metadata.gz: 2849495539fe5b88f718b2125d23251006142355bda39980d5c0eaa3d4065072ca6f50bdbc6a9653fc59b9dd9485fc2c76b287d4048fbb2b9a1de9501b0dd8c3
-  data.tar.gz: 00fea86de864e662b76ca61791e4a24cf7a6f62c39316fdd0f8219c7071cd0ddddba277f0091e581117d21e6ac23e7683eb12adae643fba6cf3060f1aae763e2
+  metadata.gz: f9f30ba5548d9a2b09497028b6325f2ba863559f42fe2c01dc3ee2710e95e2ef33da7c13bcb0811d1a7fe8a1c431d579caa3f6a05e67a9dac2abfcc148a0ddae
+  data.tar.gz: 350108d5bb47fc7ebc6ae54855167117999ebee2d2972b5c601682213ba38f2e255480b468ae14d5b5066c129d81a7c2c795592d92af1cf3ef40636be92a93de

data/.gitignore

@@ -5,3 +5,4 @@ html
 *.gem
 .spoonrc
 spoonrc
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile.lock

@@ -1,9 +1,8 @@
 PATH
   remote: .
   specs:
-    docker-spoon (0.8.0)
-      docker-api (~> 1.13)
-      methadone (~> 1.4.0)
+    docker-spoon (1.0.0)
+      docker-api (~> 1.17.0)
       rainbow (~> 2.0)
 
 GEM
@@ -24,22 +23,20 @@ GEM
       multi_json (>= 1.7.5, < 2.0)
       multi_test (>= 0.1.1)
     diff-lcs (1.2.5)
-    docker-api (1.13.6)
+    docker-api (1.17.0)
       archive-tar-minitar
       excon (>= 0.38.0)
       json
-    excon (0.40.0)
+    excon (0.42.1)
     ffi (1.9.6)
     gherkin (2.12.2)
       multi_json (~> 1.3)
     json (1.8.1)
-    methadone (1.4.0)
-      bundler
     multi_json (1.10.1)
     multi_test (0.1.1)
     rainbow (2.0.0)
     rake (0.9.6)
-    rdoc (4.1.2)
+    rdoc (4.2.0)
       json (~> 1.4)
     rspec-expectations (3.1.2)
       diff-lcs (>= 1.2.0, < 2.0)

data/README.md

@@ -16,13 +16,19 @@ Spoon is intended to make this process as easy as possible.
 #### Why Spoon?
 [Learn more about spooning](https://www.youtube.com/watch?v=dYBjVTMUQY0)
 
-## Installation
+
+## Getting Started
+These are the basics of how to get started. When you want to get into
+more detail see the [full usage](#full-usage) documentation.
+
+### Installation
 
 ```
 $ gem install docker-spoon
 ```
+(NOTE: if installing on Ubuntu this requires the installation of ruby-dev)
 
-## Configuration
+### 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
@@ -38,27 +44,41 @@ options["pre-build-commands"] = [
 ]
 ```
 
-All of the `options[]` parameters should map directly to the long form
-of options on the command line. They may be defined as either the
-`:symbol` form or as a string. The limitation is that ruby doesn't
-permit a dash in symbols, so when an option has a dash in it, it must be
-specified as a string.
+The spoon configuration is described in more detail in the [spoon config
+page](README_config.md)
+
+### 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.
 
-You may also specify a different config file with the `--config`
-argument.
+## Full Usage
 
-## Usage
+Spoon has a number of operations it can perform:
 
-Spoon has 5 major operations it can perform:
+- [Create and Connect](#create-and-connect) to containers
+- [List](#list) existing containers
+- [List Images](#list-images) on the Docker host
+- [Network](#network) to show a containers network configuration
+- [Destroy](#destroy) a container
+- [Kill](#kill) containers
+- [Restart](#restart) containers
+- [Build](#build) an image from a Dockerfile for use with spoon
 
-- Connect/Create, Connect to an existing spoon container or create a new
-  container
-- List, List existing containers
-- Network, Show ports forwarded to existing containers
-- Build, Build an image for use as a spoon container
-- Destroy, Destroy an existing spoon container
+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](#command-line-options) for a list of tunables
 
-### Connect/Create
+### 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,
@@ -68,7 +88,7 @@ the host. This will shell out to ssh and should honor your ssh
 configuration locally.
 
 Example (container doesn't exist):
-```shell
+```
 $ spoon fortesting
 The `spoon-fortesting` container doesn't exist, creating...
 Connecting to `spoon-fortesting`
@@ -76,30 +96,14 @@ pairing@dockerhost's password:
 ```
 
 Example (container exists):
-```shell
+```
 $ spoon fortesting
 Connecting to `spoon-fortesting`
 pairing@dockerhost's password:
 ```
 
-NOTE: If a container has been stopped due to a machine restart or other
-reason, spoon will issue a start to the container & then attempt to ssh
-in.
-
-#### Options
-
-- `--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.
-- `--image`, The image name to use when starting a spoon container.
-- `--prefix`, The prefix to use for creating, listing & destroying
-  containers.
-- `--portforwards`, This is a space 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.
-	Multiple port forwards may be separated by spaces, for exampe
-	`--portforwards '8080 8081:9090'`
+NOTE: If a container has been stopped or killed, spoon will issue a
+start to the container & then attempt to ssh in.
 
 ### List
 
@@ -119,21 +123,18 @@ List of available spoon containers:
 You can connect to Stopped containers in the same way as Running
 containers, spoon will re-start them as necessary.
 
-### Destroy
+### List Images
 
-The `--destroy NAME` option will destroy the specified spoon container.
+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.
 
-```shell
-$ spoon -d fortesting
-Are you sure you want to destroy spoon-fortesting? (y/n) y
-Destroying spoon-fortesting
-Done!
+```
+$ spoon --list-images
+Image: ["spoon_test:latest"]
 ```
 
-To skip any confirmations:
-
-  * add `-f` or `--force` to the command-line
-  * add `options[:force] = true` to your `.spoonrc`.
+To use this image you would set `options[:image] = 'spoon_test'`
 
 ### Network
 
@@ -148,79 +149,77 @@ $ spoon -n jake
 22 -> 49213
 ```
 
-### Build
+### Destroy
 
-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](https://docs.docker.com/reference/commandline/cli/#build)
-command.
+The `--destroy NAME` option will destroy the specified spoon container.
 
-#### Options
+```shell
+$ spoon -d fortesting
+Are you sure you want to destroy spoon-fortesting? (y/n) y
+Destroying spoon-fortesting
+Done!
+```
 
-- `--builddir`, This is the directory where the build process will look
-  for a Dockerfile and any content added to the container using `ADD`.
+To skip any confirmations:
 
-- `--pre-build-commands`, This is a list of commands to run before
-  actually kicking off the build process (see below).
+  * add `--force` to the command-line
+  * add `options[:force] = true` to your `.spoonrc`.
 
-pre-build-commands:
+### Kill
 
-Because docker-spoon is special, we also support running some
-commands in advance of the build process. This allows for things like
-copying stuff into the container which you don't want to have committed
-to the repository. An example of this is that in our environment we need
-chef credentials inside of our container & we use this mechanism to copy
-those credentials into the builddir at build time without adding them to
-our repository containing the Dockerfile.
+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.
 
-Here's an example of how we copy our chef configuration into place:
-```ruby
-options["pre-build-commands"] = [
-  "cp -rp #{ENV['HOME']}/.chef #{options[:builddir]}/chef"
-]
-```
+### Restart
 
-- `copy_on_create`, - This is a config-only value, there is no command
-  line argument for it. The idea is that you can specify a list of files
-  to copy into place on the destination container upon creation. This is
-  useful if you want to copy in place configs that you keep on your
-  workstation but don't want them as part of the image.
+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. 
 
-Example:
-```
-options[:copy_on_create] = [
-  ".gitconfig",
-  ".ssh",
-  ".ssh/config"
-]
-```
-NOTE: this does not create any required parent directories on the
-destination system unless they are copied into place, for example like
-the .ssh directory in the example above.
+### Build
 
-- `add_authorized_keys` - This is a config-only value. This allows you
-  to specify an ssh public key that should reside in your own `~/.ssh`
-  directory to be placed in authorized_keys on the destination system
-  upon container creation.
+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](https://docs.docker.com/reference/commandline/cli/#build)
+command.
 
-Example:
-```
-options[:add_authorized_keys] = "id_rsa.pub"
-```
+## Command Line Options
 
-  `run_on_create` - This is a list of commands to run on a spoon container
-  once it has been started. This allows you to quickly and automatically
-  modify a spoon environment upon creation to meet any needs you have
-  which aren't baked into the Docker image. This is a config-only
-	option, there is no command line for this. Commands are run one at a
-	time over ssh - enabling :add_authorized_keys makes this option more
-	tolerable.
+The following options may be specified either on the command line or in
+the spoon [configuration file](README_config.md). Note that command line
+options take precedence over options in the configuration file. 
 
-Example:
-```
-options[:run_on_create] = [ "sudo apt-get -y install emacs" ]
-```
+- `--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](README_config.md) documentation.
 
 #### Container expectations
 
@@ -233,7 +232,8 @@ directory inside this repository
 
 1. Fork it ( https://github.com/adnichols/docker-spoon/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+3. Make your changes, add tests and make sure all tests pass (`rake`)
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create a new Pull Request
 

data/README_config.md

@@ -0,0 +1,248 @@
+# docker-spoon
+
+## Configuration
+
+All spoon options available on the command line may be specified in the
+configuration file as well. For action type options it doesn't make much
+sense to place them in the config file, but for many other options it
+does. Further, there are some configurations which are only available as
+configuration file options to keep the cli options cleaner.
+
+The spoon configuration file is evaled as ruby so you can do all the
+things you could normally do in a ruby program. Abuse with caution.
+
+The precedence of options, from most to least preferred are:
+- Command line options
+- Configuration file options
+- Default options
+
+The exception to this is the `--config` option, which is completely
+ignored inside the configuration file.
+
+Here is an example of a simple .spoonrc:
+```ruby
+options[:url] = "tcp://192.168.1.3:4243"
+options[:image] = 'spoon-pairing'
+```
+
+All of the `options[]` parameters should map directly to the long form
+of options on the command line. They are all expected to be presented as
+symbols. The limitation is that ruby doesn't permit a dash in symbols,
+so when an option has a dash in it, it must be specified as a string.
+
+You may also specify a different config file with the `--config`
+argument.
+
+### Options
+
+#### cpu
+Forms:
+- `options[:cpu] = 1`
+
+Default: 0
+
+Configures priority of [CPU
+shares](https://docs.docker.com/reference/run/#runtime-constraints-on-cpu-and-memory).
+
+#### memory
+Forms:
+- `options[:memory] = "50m"`
+
+Default: unlimited
+
+Configures [memory
+constraints](https://docs.docker.com/reference/run/#runtime-constraints-on-cpu-and-memory).
+
+#### dns
+Forms:
+- `options[:dns] = [ "8.8.8.8", "8.8.4.4" ]`
+
+Default: (Docker default)
+
+Configures DNS servers for the container to use.
+
+#### volume
+Forms:
+- `options[:volume] = [ '/vol1', '/hostdir:/vol2' ]`
+
+Default: none
+
+This creates a volume mapping in the container to a directory on the
+Docker host. This should work much like the `-v` argument in the docker
+cli
+
+#### url
+Forms:
+- `--url URL`
+- `options[:url] = "tcp://127.0.0.1:2375"`
+
+Default: `ENV['DOCKER_HOST']`
+
+The url of the Docker API endpoint. This is in the format supported by
+the docker -H option. If this option is not specified in either the
+config or the command line then spoon will rely upon the value of
+`DOCKER_HOST`.
+
+#### image
+Forms:
+- `--image IMAGE`
+- `options[:image] = "image"`
+
+Default: `spoon-pairing`
+
+The image name to use when starting a new spoon container. Note that
+despite both default `--prefix` and `--image` beginning with `spoon-`
+the two options are unrelated.
+
+#### prefix
+Forms:
+- `--prefix PREFIX`
+- `options[:prefix] = "prefix"`
+
+Default: `spoon-`
+
+The prefix to use for naming containers. Container names are central to
+the way spoon works so that developers may choose simple names that are
+easy to remember for their containers. The prefix allows different
+groups to use different prefixes to lower the risk of name collisions.
+
+#### portforwards
+Forms:
+- `--portforwards PORT[:PORT][,PORT]`
+- `options[:portforwards] = [ "1234", "1234:4321" ]`
+
+Default: none
+
+Sometimes you are developing in a spoon container and need to expose a
+new port without destroying the container & starting over. This option
+enables this by using ssh port forwarding.
+
+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.  Multiple port forwards
+may be separated by commas, for exampe `--portforwards '8080,8081:9090'`
+
+#### ports
+Forms:
+- `--ports PORT[:PORT][,PORT]`
+- `options[:ports] = [ "1234", "1234:4321" ] `
+
+Default: none
+
+This option exposes additional ports using Docker when the container is
+created. By default any ports defined by `EXPOSE` in the Dockerfile are
+exposed to the container. This options allows you to both expose
+additional ports via Docker, or map those exposed ports to specific
+ports instead of using the dynamic Docker assigned ports.
+
+Default: none
+
+#### privileged
+Forms:
+- `--privileged`
+- `options[:privileged] = true`
+
+Default: false
+
+This is a boolean which enables
+[Privileged](https://docs.docker.com/reference/run/#runtime-privilege-linux-capabilities-and-lxc-configuration)
+mode on container creation.  This may be necessary for some operations
+to succeed inside the container.
+
+#### builddir
+Forms:
+- `--builddir DIRECTORY`
+- `options[:builddir] = "directory"`
+
+Default: `.`
+
+This is the directory where the build process will look for a Dockerfile
+and any content added to the container using `ADD`. The directory name
+is relative to the directory from which spoon is being called - not the
+directory in which the spoon executable resides.
+
+#### pre-build-commands
+Forms:
+- `options["pre-build-commands"] = [ 'cmd1', 'cmd2' ]`
+
+Default: none
+
+This is a list of commands to run before actually kicking off the build
+process.
+
+Because docker-spoon is special, we also support running some
+commands in advance of the build process. This allows for things like
+copying stuff into the container which you don't want to have committed
+to the repository. An example of this is that in our environment we need
+chef credentials inside of our container & we use this mechanism to copy
+those credentials into the builddir at build time without adding them to
+our repository containing the Dockerfile.
+
+Here's an example of how we copy our chef configuration into place:
+```ruby
+options["pre-build-commands"] = [
+  "cp -rp #{ENV['HOME']}/.chef #{options[:builddir]}/chef"
+]
+```
+
+NOTE: This option is NOT in symbol form like all others - a legacy issue
+I need to get around to fixing and deprecating this format.
+
+#### copy_on_create
+Forms:
+- `options[:copy_on_create] = [ 'somefile', 'otherfile' ]`
+
+Default: none
+
+This command will copy the list of specified files into the destionation
+container upon container creation. These will be copied from the source
+system relative to your home directory and placed in the destination
+container at the same location (relative to your home directory).
+
+This is handy for adding any custom configurations you require which you
+may not want to bake into your Docker image.
+
+Example:
+```
+options[:copy_on_create] = [
+  ".gitconfig",
+  ".ssh/config"
+]
+```
+
+NOTE: this does not create any required parent directories on the
+destination system unless they are copied into place, for example the
+.ssh directory in the example above.
+
+#### add_authorized_keys
+Forms:
+- `options[:add_authorized_keys] = "id_rsa.pub"`
+
+Default: none
+
+This allows you to specify an ssh public key that should reside in your
+own `~/.ssh` directory to be placed in authorized_keys on the
+destination system upon container creation. It copies the filename
+specified out of your local `~/.ssh` directory into
+`~/.ssh/authorized_keys` on the spoon container so that public key auth
+works.
+
+NOTE: This option WILL create a `~/.ssh` directory on the spoon
+container if it doesn't already exist.
+
+#### run_on_create
+Forms:
+- `options[:run_on_create] = [ 'cmd1', 'cmd2' ]`
+
+Default: none
+
+This is a list of commands to run on a spoon container once it has been
+started. This allows you to quickly and automatically modify a spoon
+environment upon creation to meet any needs you have which aren't baked
+into the Docker image. Commands are run one at a time over ssh - enabling
+:add_authorized_keys makes this option more tolerable.
+
+Example:
+```
+options[:run_on_create] = [ "sudo apt-get -y install emacs" ]
+```