Docker Machine CLI Wrapper

Common errors

• Error: spawn docker-machine ENOENT

  cause The `docker-machine` command-line tool is not installed or is not accessible in the system's PATH environment variable.
  fix Install `docker-machine` on your system according to the official Docker documentation. After installation, verify it's available by running `docker-machine version` in your terminal. If installed but not found, ensure its executable directory is added to your system's PATH.

• TypeError: DockerMachineCLI.Options is not a constructor

  cause This error typically occurs when attempting to instantiate `Options` directly from `DockerMachineCLI` in an ESM context where named imports are expected, or if an older CommonJS pattern is mixed with newer ESM imports.
  fix For TypeScript/ESM, use named imports: `import { DockerMachine, Options } from 'dockermachine-cli-js';` then `new Options(...)`. For CommonJS, ensure `const DockerMachineCLI = require('dockermachine-cli-js');` is used and then `new DockerMachineCLI.Options(...)`.

• UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: X): Error: ...

  cause The Promise returned by `dockerMachine.command()` was not handled with a `.catch()` block, leading to an unhandled rejection if the underlying `docker-machine` command fails.
  fix Always append a `.catch(error => { console.error('Command failed:', error); })` to your `dockerMachine.command()` calls to properly handle errors and prevent unhandled promise rejections.

Warnings

• gotcha The `docker-machine` command-line tool must be installed separately on the system where this Node.js package is run. This package is a wrapper, not an installer or bundler, of the `docker-machine` CLI. Ensure it's in your system's PATH.
  Fix: Install `docker-machine` via official Docker documentation for your operating system (e.g., Docker Desktop or standalone installation). Verify installation by running `docker-machine version` in your terminal.
• breaking In version 3.0.2, the constructor for `Options` was changed to directly accept a `keyValueObject` as its first argument. Previous versions might have used a different structure or relied on implicit argument handling.
  Fix: Ensure that the first argument passed to the `Options` constructor is an object containing key-value pairs representing `docker-machine` command line flags (e.g., `{ 'driver': 'amazonec2', 'amazonec2-access-key': 'XYZ' }`).
• breaking Version 2.0 introduced TypeScript support. While this generally improves type safety, it might have involved changes to the module's internal structure or export patterns. Users migrating from pre-2.0 versions might need to update their import statements or how they access `DockerMachineCLI` components, especially in TypeScript projects.
  Fix: For TypeScript projects, use `import { DockerMachine, Options } from 'dockermachine-cli-js';`. For CommonJS, `const DockerMachineCLI = require('dockermachine-cli-js');` should still work, but be aware that `Options` and `DockerMachine` are properties of the exported object.

Install

• npm install dockermachine-cli-js npm
• yarn add dockermachine-cli-js yarn
• pnpm add dockermachine-cli-js pnpm

Imports

• DockerMachine, Options

  import { DockerMachine, Options } from 'dockermachine-cli-js';

  Preferred import for TypeScript and ESM environments.
• DockerMachineCLI
  wrong:

  import DockerMachineCLI from 'dockermachine-cli-js';

  correct:

  const DockerMachineCLI = require('dockermachine-cli-js');

  CommonJS require pattern. The main export is an object containing `DockerMachine` and `Options`.
• Options
  wrong:

  const options = new Options(...);

  correct:

  const options = new DockerMachineCLI.Options(...);

  When using CommonJS `require`, `Options` is a property of the main `DockerMachineCLI` export.

Quickstart

This quickstart demonstrates how to initialize `DockerMachine` with AWS EC2 driver options, create a new Docker Machine, list existing machines, and then clean up by removing the created machine, using TypeScript and Promises.

import { DockerMachine, Options } from 'dockermachine-cli-js';

// Placeholder for configuration, replace with actual values or environment variables
const config = {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? 'YOUR_AWS_ACCESS_KEY_ID',
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? 'YOUR_AWS_SECRET_ACCESS_KEY'
};

const keyValueObject = {
  'driver': 'amazonec2',
  'amazonec2-access-key': config.accessKeyId,
  'amazonec2-secret-key': config.secretAccessKey,
  'amazonec2-ami': 'ami-b59ce48f', // Example AMI, choose appropriate for your region
  'amazonec2-region': 'ap-southeast-2',
  'amazonec2-zone': 'a',
  'amazonec2-instance-type': 't2.micro',
  'amazonec2-root-size': 8
};

const options = new Options(
  /* keyValueObject */ keyValueObject,
  /* currentWorkingDirectory */ null
);

const dockerMachine = new DockerMachine(options);

console.log('Attempting to create a Docker Machine...');

dockerMachine.command('create my-test-machine')
  .then(function (data) {
    console.log('Machine creation command output:', data);
    return dockerMachine.command('ls');
  })
  .then(function (data) {
    console.log('List of Docker Machines:', data.machineList);
    // Clean up: Delete the created machine
    console.log('Attempting to remove the Docker Machine...');
    return dockerMachine.command('rm -f my-test-machine');
  })
  .then(function (data) {
    console.log('Machine removal command output:', data);
    console.log('Cleanup complete.');
  })
  .catch(function (err) {
    console.error('An error occurred:', err);
  });