Simple-Dockerode

• Dockerode Compatibility
• Usage
• Properties and Methods
  • exec()
  • execRaw()
• Testing

Wraps Dockerode container exec function to make it easier to use.

Wrangling streams and four levels of callbacks on exec is a pain. This makes it simpler, hopefully.

master:

dev:

Dockerode Compatibility

Version	Pull And Launch	Get Output	Send Input	Tests Pass
1.0.0	No	No	No	No
1.1.0 - 2.0.0	Yes	No	No	No
2.1.0 - 2.2.0	Yes	Yes	No	No
2.3.0 - 2.5.5	Yes	Yes	Yes	Yes

Usage

Use this package just like you would Dockerode. The only difference is exec().

The first argument is your command, in exec array form. The second is an object of options. The third is a callback.

const Dockerode = require('simple-dockerode');

const docker = new Dockerode({protocol: 'http', host: 'localhost', port: 2375});

const myContainer = docker.getContainer('hello-world');

// Simple to grab the stdout and stderr.
myContainer.exec(['echo', 'goodbye world'], {stdout: true}, (err, results) => {
  console.log(results.stdout);
  // goodbye world
});

The results contain your exec's inspect values too, for the exit code and other information.

myContainer.exec(['stat', '/non-existent-file'], {stdout: true, stderr: true})
  .catch(console.error)
  .then(results => {
    if( results.inspect.ExitCode !== 0 ) {
      // This file obviously doesn't exist, we get an exit code of 1
      console.error(results.stderr);
      // stat: cannot stat '/non-existent-file': No such file or directory
    } else {
      console.log(results.stdout);
    }
  })
;

Stdin can be either a string or a Stream:

myContainer.exec(['tee', '/non-existent-file'], {stdin: 'this is impossible!'}, (err, results) => { ... });

myContainer.exec(['cat', '/non-existent-file'], {stdout: true, stderr: true}, (err, results) => {
  if( results.inspect.ExitCode !== 0 ) {
    console.error(results.stderr);
  } else {
    console.log(results.stdout);
    // this is impossible!
  }
});

// Set up a nonsense little stream
const sender = new Stream.Readable();
sender.push('this is impossible!');
sender.push(null);
myContainer.exec(['tee', '/non-existent-file'], {stdin: sender}, (err, results) => { ... });

In live mode ({live: true} in the options), it allows you to play with the streams yourself. The results in the callback become a function that you can use to plug in to Dockerode's demuxer. It also returns the main stream object.

myContainer.exec(['someInteractiveCommand'], {live: true, stdin: true}, (err, streamLink) => {
  const stream = streamLink(process.stdout, process.stderr);
  myStream.pipe(stream);
  stream.on('end', () => console.log('done!'));
});

// I haven't tested this since I have no idea why you would want to do it, but you probably could.
myContainer.exec(['cat', '/non-existent-file'], {live: true, stdout: true}, (err, streamLink) => {
  myContainer.exec(['tee', '/another-file'], {stdin: streamLink()}, (err, results) => { ... });
});

Properties and Methods

exec()

Arguments:

• Cmd: an array of the command you want to run, exec style.

  This should look the same as normal Dockerode's Cmd option.

• options: Optional. An object of options.

  See below for an explanation of the options.

• callback: Optional. A function to be called when your exec is done.

  Called with (err, results), where results is an object containing inspect. If stdout or stderr are true, the object contains stdout and stderr as well.

  Or, if live is true, see live option below.

  If omitted, a Promise is returned instead.

Options

stdout

Default: false

When set to true, the exec's stdout will be returned to you in results.

stderr

Default: false

When set to true, the exec's stderr will be returned to you in results.

Actually, setting either stdout or stderr will return both of them anyway.

stdin

Default: null

This option supports either a string or a Readable Stream. The contents will be sent to the exec's stdin pipe.

If you're using live mode (live: true), then you should also set stdin if you want to be able to pipe into the returned stream object. It will not pipe the content for you, so you can just set stdin: true, or any other truthy value.

live

Default: false

This mode will allow you to manipulate the streams yourself. You must add stdout: true, stderr: true, stdin: true, or any combination.

Instead of calling your callback with (err, results), it calls it with (err, streamLink), where streamLink is a function that can be called with up to two arguments. These arguments are directly fed to Dockerode's modem demuxer, and must be Writeable Stream objects. streamLink() returns the (possibly) muxed stream object, allowing you to attach events like .on('end').

createOpts

Default: null

This option is a direct interface to Dockerode's options on the normal exec function. Anything specified here will override other options.

Be careful when using this option, as you may override something that one of the simple-dockerode options has already set.

execOpts

Default: null

This option is a direct interface to Dockerode's options on the normal start function. Anything specified here will override other options.

Be careful when using this option, as you may override something that one of the simple-dockerode options has already set.

execRaw()

The original exec function in Dockerode, preserved under this name if you want to use it.

Testing

Run npm test to execute the test suite. You may need sudo if your user does not have permissions to access Docker.

The tests require that your local machine is running an instance of Docker, can pull an image from Docker Hub, and is not already running a container called simple-dockerode-test.