Registry / devops / docker-modem

docker-modem

JSON →
library5.0.7jsnpmunverified

docker-modem is a foundational Node.js module that implements the network strategies necessary for interacting with the Docker Remote API. It provides a robust layer for managing connections to the Docker daemon, supporting various protocols including Unix sockets, HTTP, and SSH. This module is the underlying networking engine for popular libraries like `dockerode`. Currently at stable version 5.0.7, it receives maintenance updates to address dependencies and minor bug fixes, as evidenced by recent patch releases bumping dependencies and fixing callback issues. It differentiates itself by offering comprehensive connection options and handling the complexities of Docker's API communication, making it a reliable choice for building Docker-integrated applications in Node.js.

devopshttp-networking
npm install docker-modem
github ↗package ↗
INSTALL
IMPORT
SIG · DOCKER-MODEM
D
docker-modem
devopsjavascriptv5.0.7
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Modem
✓ import Modem from 'docker-modem'; // For ESM
✗ const { Modem } = require('docker-modem');
The library's primary export is a default class `Modem`. For CommonJS, use `require('docker-modem')` directly, which returns the Modem class. For ESM, a default import is appropriate.
Modem
✓ const Modem = require('docker-modem'); // For CJS
✗ import { Modem } from 'docker-modem';
The `Modem` class is the default export. Destructuring `Modem` from a `require` call in CommonJS environments will result in `undefined`.
ModemOptions
✓ import type { ModemOptions } from 'docker-modem';
✗ import { ModemOptions } from 'docker-modem';
When using TypeScript, configuration options for the `Modem` constructor are typically defined by an interface like `ModemOptions`. This should be imported as a type for correctness and to avoid runtime errors.

Demonstrates initializing `docker-modem` with different connection methods (socket, HTTP, SSH) and performing a basic Docker API ping request.

const Modem = require('docker-modem'); // Connect via Unix socket (common on Linux/macOS) const modemSocket = new Modem({ socketPath: '/var/run/docker.sock' }); modemSocket.dial({ method: 'GET', path: '/_ping' }, (err, data) => { if (err) console.error('Ping socket error:', err.message); else console.log('Ping socket success:', data.toString()); }); // Connect via HTTP to a remote Docker host const modemHttp = new Modem({ host: 'http://127.0.0.1', port: 2375 }); // Assuming a Docker daemon exposed on 2375 modemHttp.dial({ method: 'GET', path: '/_ping' }, (err, data) => { if (err) console.error('Ping HTTP error:', err.message); else console.log('Ping HTTP success:', data.toString()); }); // Connect via SSH (requires SSH agent or credentials) // Note: This example uses a simplified host. Real-world usage requires proper SSH config. const modemSsh = new Modem({ protocol: 'ssh', host: 'ssh://localhost', // Replace with your SSH host port: 22, // sshOptions: { username: 'user', privateKey: '...' } // Uncomment and configure for real use }); modemSsh.dial({ method: 'GET', path: '/_ping' }, (err, data) => { if (err) console.error('Ping SSH error:', err.message); else console.log('Ping SSH success:', data.toString()); });
Debug
Known issues
breakingVersion 5.0.3 introduced a critical security update for the underlying `ssh2` dependency. Older versions might be vulnerable to CVE-2023-48795, a Terrapin attack that could lead to prefix truncation.
fix
Upgrade to `docker-modem@5.0.3` or higher immediately to mitigate the `ssh2` CVE. Ensure your `package.json` allows for this patch version or directly specify `"docker-modem": ">=5.0.3"`.
affects: <5.0.3
gotchaConnecting to the Docker daemon requires correct configuration of `socketPath`, `host`/`port`, or `protocol`/`agent`. Incorrectly configured parameters will lead to connection failures.
fix
Always verify your Docker daemon's listening configuration. For Unix sockets, `socketPath` (e.g., `/var/run/docker.sock`) is common. For TCP/HTTP, ensure the `host` and `port` are accessible. For SSH, provide valid `protocol: 'ssh'` and host/port, possibly with `sshOptions` for authentication.
affects: >=3.0.0
gotchaWhen constructing API requests, ensure the `Content-Type` header is correctly specified, especially for requests that send a body (e.g., POST requests for image builds). The `Modem#dial` method now prefers provided `Content-Type` headers, which might change behavior if previous versions silently ignored it.
fix
Explicitly set the `Content-Type` header in your request options for methods that send a body, if it's not being correctly inferred. For example, `{ method: 'POST', path: '/build', headers: { 'Content-Type': 'application/tar' } }`.
affects: >=5.0.7
gotchaThe `buildQuerystring` utility now correctly handles root-level arrays. If your application previously relied on a different serialization behavior for arrays in querystrings, this change could alter API request parameters.
fix
Review any API calls that construct querystrings from JavaScript arrays using `docker-modem`'s internal utilities, or if you're passing arrays directly in the `querystring` option. Test to ensure the generated URLs match the expected Docker API format.
affects: >=5.0.6
Errors
Common errors & fixes
Error: connect ECONNREFUSED /var/run/docker.sock
The Docker daemon is not running, or the Unix socket path is incorrect, or the current user lacks permissions to access the socket.
fix
Ensure the Docker daemon is running (`sudo systemctl start docker` or `docker start`). Verify the `socketPath` in your Modem configuration matches the daemon's listening socket. Check file permissions on the socket (e.g., add user to `docker` group: `sudo usermod -aG docker $USER && newgrp docker`).
Error: socket hang up
This often indicates that the Docker daemon closed the connection unexpectedly, possibly due to an invalid API request, a long-running process being terminated, or a network issue.
fix
Inspect the Docker daemon logs (`journalctl -u docker` or `docker logs <container_id>`). Verify your API request payload and headers are correct. For long-running operations (like image builds or logs), ensure proper handling of streams and timeouts.
TypeError: Cannot read properties of undefined (reading 'dial')
This typically means `Modem` was not correctly instantiated or `require('docker-modem')` did not return the expected class, often due to incorrect CommonJS/ESM import patterns or typos.
fix
Ensure `const Modem = require('docker-modem');` is used for CommonJS and `new Modem(...)` is called. For ESM, ensure `import Modem from 'docker-modem';` is used. Do not attempt `const { Modem } = require('docker-modem');` as `Modem` is the default export.
Upgrade
Version history
5.0.7latest on npm
Audit
Dependencies
ssh2requiredRequired for SSH connection functionality to the Docker daemon. A minimum version bump to 1.15.0 was critical to address CVE-2023-48795.
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
githubhttps://github.com/apocas/docker-modem ↗
packagehttps://www.npmjs.com/package/docker-modem ↗
docker-modem — npm install docker-modem · libregistry