Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    grunt-docker-composepublic

    grunt-docker-compose

    docker-compose interface for Grunt

    Getting Started

    This plugin requires:

    - grunt: "^1.0.1"
    - grunt-shell
    

    Important: grunt-shell is a peerDependency. as NPM v3+ deprecates peerDependencies, you need to explicitly specify grunt-shell in your project's devDependencies:

    npm install grunt-shell --save-dev

    If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin and its dependencies with this command:

    npm install grunt grunt-docker-compose grunt-shell grunt-concurrent --save-dev

    Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

    grunt.loadNpmTasks('grunt-docker-compose');

    Prerequisite: Docker

    It is assumed you already have your Docker toolchain installed and working:

    • docker-compose: >1.7.1,
    • docker: >1.11.1

    You should have at least a docker-compose.yml file in the working directory.

    If you are not familiar with Docker, please see http://docker.io to get started.

    Tasks setup

    Add this to your Gruntfile.js to register all of the tasks as aliases to your grunt command:

    // register all dockerCompose targets 
    ['up','down','stop','restart','logs','build','pull','exec','config'].forEach(function (target) {
        grunt.registerTask(target, function () {
            var args = '';
            if (this.args.length > 0) {
                args += ':' + this.args.join(':')
            }
            grunt.task.run('dockerCompose:' + target + args);
        });
    })

    Now you can:

    • grunt up will execute docker-compose up
    • grunt down will execute docker-compose down
    • etc...

    The "dockerCompose" task

    Overview

    In your project's Gruntfile, add a section named dockerCompose to the data object passed into grunt.initConfig().

    Example
    grunt.initConfig({
        // ....... stuff ....... 
        dockerCompose: {
        options: {
        mappedComposeFile: 'docker-compose-mapped.yml',
        dockerRegistryNamespace: 'my-web-app'
        }
        }
    });

    Options

    To use the tag, dockerRegistry, and dockerRegistryNamespace options, you must utilize environment variable interpolation in your docker-compose.yml:

    version: '2'
    services:
      redis:
        image: redis
     
      my-web-app:
        build: .
        image: ${DOCKER_REGISTRY}/${DOCKER_REGISTRY_NAMESPACE}/my-web-app:${TAG}
        ports:
          - 80:80
    .....
    Order of precedence (higher options override lower ones)
    1. sane defaults set by the plugin
    2. Gruntfile
    3. environment variables
    4. command line arguments

    E.g.:

    • grunt up:foo will set the foo tag instead of default latest,
    • TAG=foobar grunt up will set the foobar tag instead of default latest,
    • TAG=baz grunt up:foo will set the foo tag instead of default latest. Note that TAG is overridden, being lower precedence.

    options.dockerRegistry

    Docker Registry. Defaults to an empty string, which corresponds to DockerHub. If set, this option will set a DOCKER_REGISTRY environment variable before running each command. Use it by interpolation in your docker-compose.yml file, e.g.:

    myapp:
        image: ${DOCKER_REGISTRY}/myNamespace/myapp:some-tag

    If you aren't using it this way in your docker-compose files, setting this option has no effect.

    options.dockerRegistryNamespace

    Docker Registry Namespace. If using this option, you should specify your DockerHub username or organization here. Defaults to an empty string.

    Used in the same way as dockerRegistry:

    myapp:
        image: ${DOCKER_REGISTRY}/${DOCKER_REGISTRY_NAMESPACE}/myapp:some-tag

    options.tag

    Image tag. Defaults to 'latest'. Use by interpolation in your docker-compose files.

    myapp:
        image: ${DOCKER_REGISTRY}/${DOCKER_REGISTRY_NAMESPACE}/myapp:${TAG}

    options.mainService

    The name of your "main" service in the docker-compose file. This is the service whose logs will be tailed by default (and piped through bunyan) when doing grunt logs

    options.logTail

    How many lines of log to tail initially when starting to tail the logs. Defaults to 10.

    options.mappedComposeFile

    An optional docker-compose YAML file that extends the default, and allows for mounting host directories into the container for development. Defaults to docker-compose.yml (functionally identical to not using any extra docker-compose files).

    You would use this option if your docker-compose.yml doesn't mount any volumes into your container by default, and you had another file like docker-compose-volumes.yml extending it and specifying mounted volumes, e.g.:

    docker-compose.yml:

    myapp:
        build: .
        ports: 80:80
        ...

    docker-compose-mapped-volumes.yml:

    myapp:
        extends:
            file: docker-compose.yml
            service: myapp
        volumes: 
            - ./src:/usr/local/src/myapp

    options.debugComposeFile

    Another optional docker-compose YAML file that extends the default and uses a different Dockerfile or other options for debug use (or whatever other purpose you may have). Same idea as above.

    options.composeFile (NOT YET IMPLEMENTED)

    Name of the docker-compose file to use. Defaults to docker-compose.yml.

    Usage Examples

    grunt dockerCompose:up
    grunt dockerCompose:up:v1.0-tag
    grunt dockerCompose:up:v1.0-tag --baked
    grunt dockerCompose:up --debug
     
    grunt dockerCompose:down
     
    grunt dockerCompose:restart
    grunt dockerCompose:restart:my-app
     
    grunt dockerCompose:logs
    grunt dockerCompose:logs:my-app
    grunt dockerCompose:logs --raw
     
    grunt dockerCompose:build
    grunt dockerCompose:build:my-app
    grunt dockerCompose:build:my-app:v1.0-tag
    grunt dockerCompose:build:my-app:v1.0-tag --no-cache
    grunt dockerCompose:build:my-app:v1.0-tag --debug
     
    grunt dockerCompose:pull
    grunt dockerCompose:pull:my-app
    grunt dockerCompose:pull:my-app:v1.0-tag
     
    grunt dockerCompose:exec
    grunt dockerCompose:exec:some-service
    grunt dockerCompose:exec:some-service:some-executable
    grunt dockerCompose:exec:redis:redis-cli
     
    grunt dockerCompose:config

    Contributing

    In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

    Release History

    06/15/2016 0.1.0 Initial release

    install

    npm i grunt-docker-compose

    Downloadslast 7 days

    175

    version

    0.2.1

    license

    MIT

    repository

    github.com

    last publish

    collaborators

    • avatar