DOCSEARCHbyAlgolia
Submit Docs

dockerode

repository·master·Indexed 26 days ago

https://github.com/apocas/dockerode

A Node.js module for interacting with the Docker Remote API (version 5.0.1). It provides robust stream handling, stream demultiplexing, and treats Docker entities such as containers, images, networks, and Swarm services as first-class objects. The library supports both callbacks and Promises, allowing for the management of the Docker Engine lifecycle, including building images, pulling images, and executing commands in containers.

Tokens
5K
Snippets
17
Records
35
Agent score
89%

What's inside dockerode

  1. Instantiate the Docker client

    master

    To use dockerode, you must first instantiate the Docker class. You can connect via a local Unix socket, a remote host via HTTP/HTTPS, or use environment variables for defaults. You can also specify a custom Promise library like bluebird.

    var Docker = require('dockerode');

// Connect via local Unix socket
var docker = new Docker({socketPath: '/var/run/docker.sock'});

// Connect to a remote host
var docker2 = new Docker({host: 'http://192.168.1.10', port: 3000});

// Connect using HTTPS with certificates
var docker5 = new Docker({
  host: '192.168.1.10',
  port: 2375,
  ca: fs.readFileSync('ca.pem'),
  cert: fs.readFileSync('cert.pem'),
  key: fs.readFileSync('key.pem'),
  version: 'v1.25'
});

// Use a custom Promise library
var docker7 = new Docker({
  Promise: require('bluebird')
});

  2. Run tests for dockerode

    master

    To run the project tests, ensure you have the ubuntu:latest image available by running docker pull ubuntu:latest. The tests are implemented using mocha and chai. Execute them using the following command:

    npm test

  4. Execute the equivalent of `docker run`

    master

    The run method allows you to seamlessly run commands in a container. It accepts an image name, an array of commands, and output streams. If a callback is provided, it returns an EventEmitter (events: container, stream, data). If no callback is provided, it returns a Promise. You can pass create_options and start_options to configure the run behavior.

    // Using a callback (returns EventEmitter)
docker.run('ubuntu', ['bash', '-c', 'uname -a'], process.stdout, function (err, data, container) {
  console.log(data.StatusCode);
}).on('container', function (container) {
  // ...
});

// Using a Promise
docker.run('ubuntu', ['bash', '-c', 'uname -a'], process.stdout).then(function(data) {
  var output = data[0];
  var container = data[1];
  console.log(output.StatusCode);
  return container.remove();
});

// Splitting stdout and stderr (requires {Tty: false})
docker.run('ubuntu', ['bash', '-c', 'uname -a'], [process.stdout, process.stderr], {Tty:false}, function (err, data, container) {
  // ...
});

  5. Build a Docker image

    master
    Use buildImage to build an image from a context. The context provides the path to the Dockerfile. Any files required for the build (e.g., for COPY commands) must be explicitly listed in the src array. buildImage returns a Promise of a NodeJS stream. To detect when the build is complete, use dockerode.modem.followProgress.

  6. Execute the equivalent of `docker pull`

    master

    Use pull to pull an image from a repository. It returns a stream of the pull progress. For private repositories, pass an authconfig object within the options.

    // Standard pull
docker.pull('myrepo/myname:tag', function (err, stream) {
  // streaming output from pull...
});

// Pull from private repo
var auth = {
  username: 'username',
  password: 'password',
  auth: '',
  email: 'your@email.email',
  serveraddress: 'https://index.docker.io/v1'
};

docker.pull('tag', {'authconfig': auth}, function (err, stream) {
  // ...
});

  7. Manipulate container entities

    master

    Containers are treated as entities. You can retrieve a container instance using getContainer(id) without querying the API immediately. Once you have the entity, you can perform operations like inspect(), start(), stop(), resize(), and remove(). These methods support both callbacks and Promises. You can also set defaultOptions for specific operations on a container instance.

    // Create a container entity (does not query API)
var container = docker.getContainer('71501a8ab0f8');

// Set default options for a specific operation
container.defaultOptions.start.Binds = ["/tmp:/tmp:rw"];

// Example using Promises
docker.createContainer({
  Image: 'ubuntu',
  Tty: true,
  Cmd: ['/bin/bash', '-c', 'tail -f /var/log/dmesg']
}).then(function(container) {
  return container.start();
}).then(function(data) {
  return container.stop();
}).then(function(data) {
  return container.remove();
}).catch(function(err) {
  console.log(err);
});

  8. Manage Docker Engine resources via the Docker object

    master
    The main docker object provides access to high-level Docker Engine operations including container and image lifecycle management, system information, and Swarm orchestration. Many methods map directly to Docker API endpoints.

  10. Use helper functions: `followProgress` and `demuxStream`

    master

    The modem instance provides helper functions for stream management:

    • followProgress(stream, onFinished, [onProgress]): Fires a callback only when a stream-based process (like build or pull) has finished.
    • demuxStream(stream, stdout, stderr): Demultiplexes a single stream into separate stdout and stderr outputs (useful when Tty is false).

  11. Manage Networks via the Network object

    master

    Use the network object to inspect, remove, or connect/disconnect containers from networks.

    ### Network

- network.inspect()
- network.remove(options)
- network.connect(options)
- network.disconnect(options)