Makes building docker containers in javascript a breeze

Usage no npm install needed!

<script type="module">
  import ezdocker from 'https://cdn.skypack.dev/ezdocker';



license:mit Build Status Coverage Status npm npm

EZDocker provides an easy and intuitive way to build docker images in JavaScript. This builds upon Dockerode to provide build patterns and output formatting to improve ease of use.

Although this was built to be used in a Gulp build environment, it can be used in any NodeJS-based build environment or even directly in NodeJS.

This README does not describe what exactly you should put into your Dockerfile or how to setup your project. This simply gives instructions on how to invoke Docker's build process.

Naming Conventions

EZDocker utilizes a standard naming convention for tagging images that follows the RedHat Image-Naming Conventions.
The naming convention is as follows:


This allows for convenient, explicit and easy pushing of images to the registry after they have been built.

Gulp Example Usage (ES5)

This example shows using EZDocker to build an image with multiple source folders and pulling the connection configuration from command line arguments:

(function() {

  var gulp = require('gulp'),
      EZDocker = require('ezdocker').default; // Note that in ES5, EZDocker is bound to ".default"

  gulp.task('docker:build-image', function() {
    return EZDocker.createFromArgs()
      .and.path('dist/production', 'dist')
      .and.path('other/files', '.')


NodeJS Example Usage (ES6)

The example below shows how to use EZDocker to build an image with a single folder.

import EZDocker from 'ezdocker';

return EZDocker.createFromArgs()
  .and.path('dist/production', 'dist')
  .and.path('other/files', '.')

Configuring Connection to Docker Host

Ultimately under the covers, this is communicating with a Docker host to do the building of the images. By default EZDocker will try to communicate with a host running on the local machine. If the docker host is running remotely, these parameters must be passed in as connection options when constructing an instance of EZDocker.

let ezdocker = new EZDocker({host: '', port: 3000});

Below are all of the possible configuration parameters you could send. For more details, see Dockerode's Getting Started section.

  • No Parameters -- Defaults to connecting to socket at /var/run/docker.sock
  • socketPath -- local socket to connect to (should be a file path)
  • host -- host domain or IP with optional protocol
  • port -- port
  • protocol -- https or http
  • ca, cert, key -- used to authenticate with host

Connection Configuration from Command Line

Configuration parameters can be obtained from the command line too by calling EZDocker.createFromArgs(). Any command line arguments prefixed with docker. will be used as connection parameters. So to build using the docker host running at using the Gulp example above, this would be the command:

$ npm docker:build-image --docker.host= --docker.port=3000 --docker.protocol=https

Other Docker Tasks

EZDocker also supports pushing and removing images.

import EZDocker from 'ezdocker';

let repository = new EZDocker().repository('docker.registry.my.company.com:5000/my-team/my-project');

  .then(() => {
    console.log('Images pushed, time to clean up the local repository');
    return repository.removeImages();
  .then(() => {
    console.log('Great Success!');
  .catch(() => {
    console.error('Great Failure!');


$ npm install --save-dev ezdocker

Submitting Issues

Please file a github issue for any problems or feature requests.

Thank You

Huge thanks to Dockerode on which this is built.


See Contributing


Licensed under MIT