grunt-dock

A Grunt dock for Docker.

Grunt plugin to manage your Docker images & containers.

The main goal of this plugin is to accelerate the development flow with Docker. But it can also be used to deploy your app in a production environment.

Last but not least, Grunt-dock is based on the module Dockerode. Input options can be passed to this module and return values are unchanged.

Why a Grunt plugin?

The idea came when I was developping a Docker container. I used to enter a lot of commands like build/start/kill then cleaning all the stuff and restarting the workflow.

Before Grunt-Dock, to clean Docker images/containers:

docker ps -a -q --filter "status=exited" | xargs docker rm
docker rmi `docker images -q --filter "dangling=true"`

After:

grunt dock:clean

Installation

npm install grunt-dock

Commands

Grunt-dock supports these commands:

list images or containers
build images
push push built images to a Docker registry
pull pull images from a Docker registry to one or more hosts
clean dangling images and exited containers
start/stop/restart/kill/pause/unpause containers
logs containers

Grunt configuration

Grunt-Dock supports main and targets level configuration.

Here is a basic Grunt configuration:

dock: {
  options: {

    registry: <Docker registry URL>,
    auth : {
      email : <email to use to connect to Docker registry>,
      username : <Docker registry username>,
      password : <Docker registry password>
    }

    docker: {
      // docker connection
      // See Dockerode for options
    }

    // It is possible to define images in the 'default' grunt option
    // The command will look like 'grunt dock:build'
    images: {
      'dockerapp': { // Name to use for Docker
        dockerfile: 'Dockerfile',
        options: { 
          build:   { /* extra options to docker build   */ },
          create:  { /* extra options to docker create  */ },
          start:   { /* extra options to docker start   */ },
          stop:    { /* extra options to docker stop    */ },
          kill:    { /* extra options to docker kill    */ },
          logs:    { /* extra options to docker logs    */ },
          pause:   { /* extra options to docker pause   */ },
          unpause: { /* extra options to docker unpause */ },
          push:    { /* extra options to docker push */ },
          pull:    [/* Docker connections (one for every node from which to pull */],
          run:     {
                     docker: [/* Docker connections (one for every node from which 
                              the container has to run */],
                     cmd : [/* Commands to execute upon running the container */],
                     create : /* Container create options */,
                     start : /* Containder start options */
          }
        }
      }
    }
  }, // options

  dev: {
    options: {

      // You can also define images by target
      // This case, to invoke a command: 'grunt dock:dev:build'
      images: {
      'appname': { // Name to use for Docker
           dockerfile: 'Dockerfile',
           options: { 
             build:   { /* extra options to docker build   */ },
             create:  { /* extra options to docker create  */ },
             start:   { /* extra options to docker start   */ },
             stop:    { /* extra options to docker stop    */ },
             kill:    { /* extra options to docker kill    */ },
             logs:    { /* extra options to docker logs    */ },
             pause:   { /* extra options to docker pause   */ },
             unpause: { /* extra options to docker unpause */ }
           }
        }
      }
    }
  } // dev env
} // dock

The property 'dockerfile' supports:

tar archive any tarballs supported by Docker (.tar, .tar.gz, .tar.bz2, .tar.xz). It will be passed directly to the Docker server.
directory Grunt-Dock will create a tarball (gz compressed) of this directory before sending it to Docker.
plain file Grunt-Dock will create a tarball containing 1 "Dockerfile" file.

You can define some specifics options to pass for each commands of each images (start, stop, build, etc.). See Docker API/Dockerode documentations.

To use it, simply enter these commands:

# Build
grunt dock:build
grunt dock:dev:build

# Start, stop, restart, kill, pause, unpause, logs (replace sample action by right one)
grunt dock:start
grunt dock:dev:start

# List
grunt dock:list
grunt dock:dev:list

# Clean
grunt dock:clean
grunt dock:dev:clean

It is possible to only apply a command for a specific image. For instance, to only start the container 'appname', enter:

# Start only appname container
grunt dock:start:appname
# for 'dev' target:
grunt dock:dev:start:appname

list and clean commands allow a third param: image or container to only list/clean this type:

# List only images
grunt dock:list:image
grunt dock:dev:list:image

# List only containers
grunt dock:list:container
grunt dock:dev:list:container

Samples

See the examples directory.

Coming next

Add some better tests
Add or create some Docker useful features!

Contributing

Pull requests are welcome.

Please update the tests and the documentation.

License

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

JoTrdl / grunt-dock

readme