Docker Client Operations

/**
 * Create a Docker client instance
 * @param opts - Connection and configuration options
 */
constructor(opts?: DockerOptions);

interface DockerOptions {
  /** Path to Docker socket (default: /var/run/docker.sock) */
  socketPath?: string;
  /** Docker daemon host */
  host?: string;
  /** Docker daemon port */
  port?: number;
  /** CA certificate for TLS */
  ca?: string;
  /** Client certificate for TLS */
  cert?: string;
  /** Client private key for TLS */
  key?: string;
  /** Protocol (http/https) */
  protocol?: string;
  /** Request timeout in milliseconds */
  timeout?: number;
  /** Docker API version */
  version?: string;
  /** Promise library to use */
  Promise?: any;
  /** Docker modem instance to reuse */
  modem?: any;
}

const Docker = require('dockerode');

// Default connection (Unix socket)
const docker = new Docker();

// TCP connection
const docker = new Docker({host: 'localhost', port: 2376});

// TLS connection
const docker = new Docker({
  host: 'localhost',
  port: 2376,
  ca: fs.readFileSync('ca.pem'),
  cert: fs.readFileSync('cert.pem'),
  key: fs.readFileSync('key.pem'),
  protocol: 'https'
});

/**
 * Get container instance by ID or name
 * @param id - Container ID or name
 * @returns Container instance
 */
getContainer(id: string): Container;

/**
 * Get image instance by name, ID, or tag
 * @param name - Image name, ID, or repository:tag
 * @returns Image instance
 */
getImage(name: string): Image;

/**
 * Get volume instance by name
 * @param name - Volume name
 * @returns Volume instance
 */
getVolume(name: string): Volume;

/**
 * Get network instance by ID
 * @param id - Network ID
 * @returns Network instance
 */
getNetwork(id: string): Network;

/**
 * Get service instance by ID or name
 * @param id - Service ID or name
 * @returns Service instance
 */
getService(id: string): Service;

/**
 * Get plugin instance by name
 * @param name - Plugin name
 * @param remote - Whether plugin is remote
 * @returns Plugin instance
 */
getPlugin(name: string, remote?: boolean): Plugin;

/**
 * Get secret instance by ID or name
 * @param id - Secret ID or name
 * @returns Secret instance
 */
getSecret(id: string): Secret;

/**
 * Get config instance by ID or name
 * @param id - Config ID or name
 * @returns Config instance
 */
getConfig(id: string): Config;

/**
 * Get task instance by ID
 * @param id - Task ID
 * @returns Task instance
 */
getTask(id: string): Task;

/**
 * Get node instance by ID
 * @param id - Node ID
 * @returns Node instance
 */
getNode(id: string): Node;

/**
 * Get exec instance by ID
 * @param id - Exec ID
 * @returns Exec instance
 */
getExec(id: string): Exec;

/**
 * List containers with filtering options
 * @param opts - Filtering and query options
 * @param callback - Optional callback
 * @returns Promise resolving to container list
 */
listContainers(opts?: ListContainersOptions, callback?: Function): Promise<ContainerInfo[]>;

/**
 * List images with filtering options
 * @param opts - Filtering and query options
 * @param callback - Optional callback
 * @returns Promise resolving to image list
 */
listImages(opts?: ListImagesOptions, callback?: Function): Promise<ImageInfo[]>;

/**
 * List volumes with filtering options
 * @param opts - Filtering and query options
 * @param callback - Optional callback
 * @returns Promise resolving to volumes response
 */
listVolumes(opts?: ListVolumesOptions, callback?: Function): Promise<VolumeListResponse>;

/**
 * List networks with filtering options
 * @param opts - Filtering and query options
 * @param callback - Optional callback
 * @returns Promise resolving to network list
 */
listNetworks(opts?: ListNetworksOptions, callback?: Function): Promise<NetworkInfo[]>;

/**
 * List services with filtering options
 * @param opts - Filtering and query options
 * @param callback - Optional callback
 * @returns Promise resolving to service list
 */
listServices(opts?: ListServicesOptions, callback?: Function): Promise<ServiceInfo[]>;

/**
 * List plugins with filtering options
 * @param opts - Filtering and query options
 * @param callback - Optional callback
 * @returns Promise resolving to plugin list
 */
listPlugins(opts?: ListPluginsOptions, callback?: Function): Promise<PluginInfo[]>;

/**
 * List secrets with filtering options
 * @param opts - Filtering and query options
 * @param callback - Optional callback
 * @returns Promise resolving to secret list
 */
listSecrets(opts?: ListSecretsOptions, callback?: Function): Promise<SecretInfo[]>;

/**
 * List configs with filtering options
 * @param opts - Filtering and query options
 * @param callback - Optional callback
 * @returns Promise resolving to config list
 */
listConfigs(opts?: ListConfigsOptions, callback?: Function): Promise<ConfigInfo[]>;

/**
 * List tasks with filtering options
 * @param opts - Filtering and query options
 * @param callback - Optional callback
 * @returns Promise resolving to task list
 */
listTasks(opts?: ListTasksOptions, callback?: Function): Promise<TaskInfo[]>;

/**
 * List nodes with filtering options
 * @param opts - Filtering and query options
 * @param callback - Optional callback
 * @returns Promise resolving to node list
 */
listNodes(opts?: ListNodesOptions, callback?: Function): Promise<NodeInfo[]>;

interface ListContainersOptions {
  /** Show all containers (default: false, only running) */
  all?: boolean;
  /** Return container size information */
  size?: boolean;
  /** Show containers created before this container ID */
  before?: string;
  /** Show containers created since this container ID */
  since?: string;
  /** Limit number of containers returned */
  limit?: number;
  /** Filter containers by key=value */
  filters?: object;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface ContainerInfo {
  Id: string;
  Names: string[];
  Image: string;
  ImageID: string;
  Command: string;
  Created: number;
  Ports: PortInfo[];
  Labels: object;
  State: string;
  Status: string;
  HostConfig: object;
  NetworkSettings: object;
  Mounts: MountInfo[];
}

// List all containers (running and stopped)
const containers = await docker.listContainers({ all: true });

// List only running containers
const running = await docker.listContainers();

// List containers with filtering
const filtered = await docker.listContainers({
  filters: { 
    status: ['running'],
    label: ['app=web'] 
  }
});

// List images
const images = await docker.listImages();

// List volumes
const volumes = await docker.listVolumes();

/**
 * Create a new container
 * @param opts - Container creation options
 * @param callback - Optional callback
 * @returns Promise resolving to Container instance
 */
createContainer(opts: ContainerCreateOptions, callback?: Function): Promise<Container>;

/**
 * Create a new volume
 * @param opts - Volume creation options
 * @param callback - Optional callback
 * @returns Promise resolving to Volume instance
 */
createVolume(opts: VolumeCreateOptions, callback?: Function): Promise<Volume>;

/**
 * Create a new network
 * @param opts - Network creation options
 * @param callback - Optional callback
 * @returns Promise resolving to Network instance
 */
createNetwork(opts: NetworkCreateOptions, callback?: Function): Promise<Network>;

/**
 * Create a new service
 * @param auth - Registry authentication
 * @param opts - Service creation options
 * @param callback - Optional callback
 * @returns Promise resolving to Service instance
 */
createService(auth?: object, opts?: ServiceCreateOptions, callback?: Function): Promise<Service>;

/**
 * Create a new secret
 * @param opts - Secret creation options
 * @param callback - Optional callback
 * @returns Promise resolving to Secret instance
 */
createSecret(opts: SecretCreateOptions, callback?: Function): Promise<Secret>;

/**
 * Create a new config
 * @param opts - Config creation options
 * @param callback - Optional callback
 * @returns Promise resolving to Config instance
 */
createConfig(opts: ConfigCreateOptions, callback?: Function): Promise<Config>;

/**
 * Create a new plugin
 * @param opts - Plugin creation options
 * @param callback - Optional callback
 * @returns Promise resolving to Plugin instance
 */
createPlugin(opts: PluginCreateOptions, callback?: Function): Promise<Plugin>;

interface ContainerCreateOptions {
  /** Container image name */
  Image: string;
  /** Container name */
  name?: string;
  /** Command to run */
  Cmd?: string[];
  /** Environment variables */
  Env?: string[];
  /** Exposed ports */
  ExposedPorts?: object;
  /** Host configuration */
  HostConfig?: object;
  /** Network configuration */
  NetworkingConfig?: object;
  /** Working directory */
  WorkingDir?: string;
  /** Entry point */
  Entrypoint?: string[];
  /** Labels */
  Labels?: object;
  /** Registry authentication */
  authconfig?: object;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

/**
 * Get comprehensive Docker system information
 * @param opts - Query options
 * @param callback - Optional callback
 * @returns Promise resolving to system info
 */
info(opts?: object, callback?: Function): Promise<SystemInfo>;

/**
 * Get Docker version information
 * @param opts - Query options
 * @param callback - Optional callback
 * @returns Promise resolving to version info
 */
version(opts?: object, callback?: Function): Promise<VersionInfo>;

/**
 * Ping Docker daemon to check connectivity
 * @param opts - Query options
 * @param callback - Optional callback
 * @returns Promise resolving to ping response
 */
ping(opts?: object, callback?: Function): Promise<string>;

/**
 * Get Docker system disk usage information
 * @param opts - Query options
 * @param callback - Optional callback
 * @returns Promise resolving to disk usage info
 */
df(opts?: object, callback?: Function): Promise<DiskUsageInfo>;

/**
 * Get Docker events stream with filtering
 * @param opts - Event filtering options
 * @param callback - Optional callback
 * @returns Promise resolving to events stream
 */
getEvents(opts?: EventsOptions, callback?: Function): Promise<Stream>;

interface SystemInfo {
  ID: string;
  Containers: number;
  ContainersRunning: number;
  ContainersPaused: number;
  ContainersStopped: number;
  Images: number;
  Driver: string;
  DriverStatus: string[][];
  SystemStatus: string[][];
  Plugins: object;
  MemoryLimit: boolean;
  SwapLimit: boolean;
  KernelMemory: boolean;
  CpuCfsPeriod: boolean;
  CpuCfsQuota: boolean;
  CPUShares: boolean;
  CPUSet: boolean;
  PidsLimit: boolean;
  IPv4Forwarding: boolean;
  BridgeNfIptables: boolean;
  BridgeNfIp6tables: boolean;
  Debug: boolean;
  NFd: number;
  OomKillDisable: boolean;
  NGoroutines: number;
  SystemTime: string;
  LoggingDriver: string;
  CgroupDriver: string;
  NEventsListener: number;
  KernelVersion: string;
  OperatingSystem: string;
  OSType: string;
  Architecture: string;
  IndexServerAddress: string;
  RegistryConfig: object;
  NCPU: number;
  MemTotal: number;
  GenericResources: any[];
  DockerRootDir: string;
  HttpProxy: string;
  HttpsProxy: string;
  NoProxy: string;
  Name: string;
  Labels: string[];
  ExperimentalBuild: boolean;
  ServerVersion: string;
  ClusterStore: string;
  ClusterAdvertise: string;
  Runtimes: object;
  DefaultRuntime: string;
  Swarm: object;
  LiveRestoreEnabled: boolean;
  Isolation: string;
  InitBinary: string;
  ContainerdCommit: object;
  RuncCommit: object;
  InitCommit: object;
  SecurityOptions: string[];
}

interface EventsOptions {
  /** Filter events since timestamp */
  since?: string | number;
  /** Filter events until timestamp */
  until?: string | number;
  /** Event filters */
  filters?: object;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

// Get system information
const info = await docker.info();
console.log(`Docker version: ${info.ServerVersion}`);
console.log(`Running containers: ${info.ContainersRunning}`);

// Get version details
const version = await docker.version();
console.log(version.Version);

// Check connectivity
await docker.ping(); // Returns "OK"

// Get disk usage
const usage = await docker.df();
console.log(usage.LayersSize);

// Monitor events
const eventStream = await docker.getEvents({
  since: Math.floor(Date.now() / 1000) - 3600, // Last hour
  filters: { type: ['container'] }
});

eventStream.on('data', chunk => {
  const event = JSON.parse(chunk.toString());
  console.log(`${event.Type}: ${event.Action} on ${event.Actor.ID}`);
});

/**
 * Create/pull image from registry
 * @param auth - Registry authentication
 * @param opts - Image creation options
 * @param callback - Optional callback
 * @returns Promise resolving to creation stream
 */
createImage(auth?: object, opts?: ImageCreateOptions, callback?: Function): Promise<Stream>;

/**
 * Load image from tar archive
 * @param file - Tar archive stream
 * @param opts - Load options
 * @param callback - Optional callback
 * @returns Promise resolving to load stream
 */
loadImage(file: Stream, opts?: object, callback?: Function): Promise<Stream>;

/**
 * Import image from tar archive
 * @param file - Tar archive stream
 * @param opts - Import options
 * @param callback - Optional callback
 * @returns Promise resolving to import stream
 */
importImage(file: Stream, opts?: ImportImageOptions, callback?: Function): Promise<Stream>;

/**
 * Build image from Dockerfile
 * @param file - Build context (string path or stream)
 * @param opts - Build options
 * @param callback - Optional callback
 * @returns Promise resolving to build stream
 */
buildImage(file: string | Stream, opts?: BuildImageOptions, callback?: Function): Promise<Stream>;

/**
 * Pull image from registry
 * @param repoTag - Repository and tag (e.g., 'ubuntu:latest')
 * @param opts - Pull options
 * @param callback - Optional callback
 * @param auth - Registry authentication
 * @returns Promise resolving to pull stream
 */
pull(repoTag: string, opts?: object, callback?: Function, auth?: object): Promise<Stream>;

/**
 * Pull all tags for an image from registry
 * @param repoTag - Repository name (without tag)
 * @param opts - Pull options
 * @param callback - Optional callback
 * @param auth - Registry authentication
 * @returns Promise resolving to pull stream
 */
pullAll(repoTag: string, opts?: object, callback?: Function, auth?: object): Promise<Stream>;

/**
 * Export multiple images as tar stream
 * @param opts - Export options with image names
 * @param callback - Optional callback
 * @returns Promise resolving to tar stream
 */
getImages(opts: GetImagesOptions, callback?: Function): Promise<Stream>;

interface GetImagesOptions {
  /** Array of image names to export */
  names: string[];
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

/**
 * Search for images in registry
 * @param opts - Search options
 * @param callback - Optional callback
 * @returns Promise resolving to search results
 */
searchImages(opts: SearchImagesOptions, callback?: Function): Promise<SearchResult[]>;

/**
 * Check authentication credentials against registry
 * @param opts - Authentication credentials
 * @param callback - Optional callback
 * @returns Promise resolving to authentication response
 */
checkAuth(opts: AuthConfig, callback?: Function): Promise<object>;

interface AuthConfig {
  /** Username for registry authentication */
  username: string;
  /** Password for registry authentication */
  password: string;
  /** Email for registry authentication */
  email?: string;
  /** Registry server address */
  serveraddress: string;
  /** Registry auth token */
  auth?: string;
  /** Identity token */
  identitytoken?: string;
  /** Registry token */
  registrytoken?: string;
}

interface BuildImageOptions {
  /** Tag for built image */
  t?: string;
  /** Suppress verbose build output */
  q?: boolean;
  /** Do not use cache */
  nocache?: boolean;
  /** Remove intermediate containers */
  rm?: boolean;
  /** Always remove intermediate containers */
  forcerm?: boolean;
  /** Build arguments */
  buildargs?: object;
  /** Dockerfile name */
  dockerfile?: string;
  /** Target build stage */
  target?: string;
  /** Platform for multi-platform builds */
  platform?: string;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

/**
 * Remove unused images
 * @param opts - Prune options
 * @param callback - Optional callback
 * @returns Promise resolving to pruned resources info
 */
pruneImages(opts?: PruneOptions, callback?: Function): Promise<PruneResult>;

/**
 * Remove unused containers
 * @param opts - Prune options
 * @param callback - Optional callback
 * @returns Promise resolving to pruned resources info
 */
pruneContainers(opts?: PruneOptions, callback?: Function): Promise<PruneResult>;

/**
 * Remove unused volumes
 * @param opts - Prune options
 * @param callback - Optional callback
 * @returns Promise resolving to pruned resources info
 */
pruneVolumes(opts?: PruneOptions, callback?: Function): Promise<PruneResult>;

/**
 * Remove unused networks
 * @param opts - Prune options
 * @param callback - Optional callback
 * @returns Promise resolving to pruned resources info
 */
pruneNetworks(opts?: PruneOptions, callback?: Function): Promise<PruneResult>;

/**
 * Clear build cache
 * @param opts - Prune options
 * @param callback - Optional callback
 * @returns Promise resolving to cleared cache info
 */
pruneBuilder(opts?: PruneOptions, callback?: Function): Promise<PruneResult>;

interface PruneOptions {
  /** Prune filters */
  filters?: object;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface PruneResult {
  /** List of deleted items */
  ObjectsDeleted?: string[];
  /** Amount of disk space reclaimed in bytes */
  SpaceReclaimed?: number;
}

/**
 * Run container equivalent to 'docker run' command
 * @param image - Image name to run
 * @param cmd - Command to execute
 * @param stream - Output stream (optional)
 * @param createOpts - Container creation options
 * @param startOpts - Container start options
 * @param callback - Optional callback
 * @returns EventEmitter for container execution
 */
run(
  image: string, 
  cmd: string[], 
  stream?: Stream, 
  createOpts?: ContainerCreateOptions, 
  startOpts?: object, 
  callback?: Function
): EventEmitter;

// Simple container run
const stream = await docker.run('ubuntu:latest', ['echo', 'hello world'], process.stdout);

// Run with options
const stream = await docker.run('ubuntu:latest', ['ls', '-la'], process.stdout, {
  Env: ['NODE_ENV=production'],
  WorkingDir: '/app'
});

stream.on('exit', (statusCode) => {
  console.log(`Container exited with status ${statusCode}`);
});