Docker Remote API for Node.js

1.1.22 · active · verified Sun Apr 19

node-docker-api is a Node.js driver for the Docker Remote API, offering a promisified interface for interacting with the Docker daemon's containers, images, networks, and other resources. It distinguishes itself from alternatives like dockerode by providing a promise-based API and a different syntax, while internally relying on the same robust modem for communication. The library fully supports essential Docker functionalities including stream handling (e.g., for logs and stats), stream demultiplexing, entity management, and offers full ES6 support. It aims to cover the complete Docker Engine API reference, including experimental features, and provides TypeScript type definitions. As of version 1.1.22, the package is officially in a 'beta state,' indicating that users should expect potential API adjustments or minor instabilities, although core functionality is generally stable. Release cadence is not explicitly defined but follows development during its beta phase.

Common errors

```
Error: connect ECONNREFUSED /var/run/docker.sock
```
cause The Docker daemon is either not running, or the specified socket path is incorrect for your operating system or Docker setup.

fix Start the Docker daemon. Verify the `socketPath` in your Docker constructor (e.g., `/var/run/docker.sock` for Linux/macOS, `//./pipe/docker_engine` for Windows via WSL2, or check Docker Desktop settings for alternative paths).
```
TypeError: Cannot read properties of undefined (reading 'create')
```
cause The `docker` object was not correctly initialized, or a method like `container` was accessed before the `Docker` client was properly instantiated.

fix Ensure `new Docker({ /* config */ })` is called and assigned to the `docker` variable before attempting to use its properties and methods like `docker.container.create`.
```
Error: (HTTP code 404) no such container - No such container: [container-id]
```
cause The specified container ID or name does not exist on the Docker daemon, or it has already been removed.

fix Check that the container ID or name is correct and that the container is currently running or exists. List active containers using `docker.container.list()` to verify its presence.

Warnings

gotcha Despite a 1.x version number, the package explicitly states it is in 'beta state'. This implies the API might not be fully stable, and minor breaking changes could occur in future minor versions.
Fix: Review the GitHub repository's release notes and changelog regularly. Pin dependencies to exact versions to prevent unexpected updates in production environments.
gotcha The Docker daemon connection parameters (e.g., `socketPath`, `host`, `port`) are crucial for proper functionality. Incorrect settings or an unreachable Docker daemon will result in connection errors.
Fix: Ensure the Docker daemon is running. Verify `socketPath` (e.g., `/var/run/docker.sock` on Linux, `//./pipe/docker_engine` on Windows via WSL2, or a custom path), `host`, and `port` configurations match your Docker environment. For remote connections, ensure proper authentication and firewall rules.
gotcha When working with Docker streams (e.g., for logs or stats), proper event handling (`on('data')`, `on('error')`, `on('end')`) is critical to consume data and prevent memory leaks. Streams must be explicitly closed or allowed to end.
Fix: Always attach `data`, `error`, and `end` listeners to streams returned by methods like `container.logs()` or `container.stats()`. Ensure streams are properly consumed or unsubscribed from when no longer needed.

Install

npm install node-docker-api npm
yarn add node-docker-api yarn
pnpm add node-docker-api pnpm

Imports

Docker
wrong:
```
import Docker from 'node-docker-api';
```
correct:
```
import { Docker } from 'node-docker-api';
```
The main Docker client class is a named export. TypeScript users will prefer this.
Docker (CommonJS)
wrong:
```
const Docker = require('node-docker-api');
```
correct:
```
const { Docker } = require('node-docker-api');
```
CommonJS environments use named destructuring for the main Docker client.

Quickstart

This example demonstrates the full lifecycle of a Docker container: creation, start, stop, restart, and forced removal, utilizing async/await with the promisified API.

import { Docker } from 'node-docker-api';

const docker = new Docker({ socketPath: '/var/run/docker.sock' });

async function manageContainer() {
  let containerInstance;
  try {
    console.log('Creating container...');
    const container = await docker.container.create({
      Image: 'ubuntu',
      name: 'test-node-api-container',
      Cmd: ['tail', '-f', '/dev/null'] // Keep container running
    });
    containerInstance = container;
    console.log(`Container '${container.id}' created.`);

    console.log('Starting container...');
    await container.start();
    console.log(`Container '${container.id}' started.`);

    console.log('Stopping container...');
    await container.stop();
    console.log(`Container '${container.id}' stopped.`);

    console.log('Restarting container...');
    await container.restart();
    console.log(`Container '${container.id}' restarted.`);

  } catch (error) {
    console.error('An error occurred:', error);
  } finally {
    if (containerInstance) {
      console.log('Deleting container...');
      await containerInstance.delete({ force: true });
      console.log(`Container '${containerInstance.id}' deleted.`);
    }
  }
}

manageContainer();

view raw JSON →