{"id":13076,"library":"docker-modem","title":"Docker Remote API Network Layer","description":"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.","status":"active","version":"5.0.7","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/apocas/docker-modem","tags":["javascript","containers","api","docker"],"install":[{"cmd":"npm install docker-modem","lang":"bash","label":"npm"},{"cmd":"yarn add docker-modem","lang":"bash","label":"yarn"},{"cmd":"pnpm add docker-modem","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for SSH connection functionality to the Docker daemon. A minimum version bump to 1.15.0 was critical to address CVE-2023-48795.","package":"ssh2","optional":false}],"imports":[{"note":"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.","wrong":"const { Modem } = require('docker-modem');","symbol":"Modem","correct":"import Modem from 'docker-modem'; // For ESM"},{"note":"The `Modem` class is the default export. Destructuring `Modem` from a `require` call in CommonJS environments will result in `undefined`.","wrong":"import { Modem } from 'docker-modem';","symbol":"Modem","correct":"const Modem = require('docker-modem'); // For CJS"},{"note":"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.","wrong":"import { ModemOptions } from 'docker-modem';","symbol":"ModemOptions","correct":"import type { ModemOptions } from 'docker-modem';"}],"quickstart":{"code":"const Modem = require('docker-modem');\n\n// Connect via Unix socket (common on Linux/macOS)\nconst modemSocket = new Modem({ socketPath: '/var/run/docker.sock' });\nmodemSocket.dial({ method: 'GET', path: '/_ping' }, (err, data) => {\n  if (err) console.error('Ping socket error:', err.message);\n  else console.log('Ping socket success:', data.toString());\n});\n\n// Connect via HTTP to a remote Docker host\nconst modemHttp = new Modem({ host: 'http://127.0.0.1', port: 2375 }); // Assuming a Docker daemon exposed on 2375\nmodemHttp.dial({ method: 'GET', path: '/_ping' }, (err, data) => {\n  if (err) console.error('Ping HTTP error:', err.message);\n  else console.log('Ping HTTP success:', data.toString());\n});\n\n// Connect via SSH (requires SSH agent or credentials)\n// Note: This example uses a simplified host. Real-world usage requires proper SSH config.\nconst modemSsh = new Modem({\n  protocol: 'ssh',\n  host: 'ssh://localhost', // Replace with your SSH host\n  port: 22,\n  // sshOptions: { username: 'user', privateKey: '...' } // Uncomment and configure for real use\n});\nmodemSsh.dial({ method: 'GET', path: '/_ping' }, (err, data) => {\n  if (err) console.error('Ping SSH error:', err.message);\n  else console.log('Ping SSH success:', data.toString());\n});","lang":"javascript","description":"Demonstrates initializing `docker-modem` with different connection methods (socket, HTTP, SSH) and performing a basic Docker API ping request."},"warnings":[{"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\"`.","message":"Version 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.","severity":"breaking","affected_versions":"<5.0.3"},{"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.","message":"Connecting to the Docker daemon requires correct configuration of `socketPath`, `host`/`port`, or `protocol`/`agent`. Incorrectly configured parameters will lead to connection failures.","severity":"gotcha","affected_versions":">=3.0.0"},{"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' } }`.","message":"When 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.","severity":"gotcha","affected_versions":">=5.0.7"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=5.0.6"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`).","cause":"The Docker daemon is not running, or the Unix socket path is incorrect, or the current user lacks permissions to access the socket.","error":"Error: connect ECONNREFUSED /var/run/docker.sock"},{"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.","cause":"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.","error":"Error: socket hang up"},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'dial')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}