Docker API TypeScript

docker-api-typescript is an open-source TypeScript package that provides a comprehensive client for interacting with the Docker Engine API. This package includes various services to manage Docker containers, images, networks, volumes, and more.

Features

• Container Management: Create, inspect, start, stop, and remove containers.
• Image Management: Pull, tag, and remove Docker images.
• Service Management: Create, update, and remove services in Docker Swarm mode.
• System Operations: Get Docker system information and manage system-wide settings.
• Execution Management: Run commands inside running containers.
• Volume Management: Create, inspect, and remove Docker volumes.
• Network Management: Create, inspect, and remove Docker networks.
• Plugin Management: Install, enable, disable, and remove Docker plugins.
• Node Management: Manage nodes in Docker Swarm.
• Swarm Management: Initialize, join, and leave Docker Swarm.
• Task Management: Inspect tasks in Docker Swarm.
• Secret Management: Create, inspect, and remove Docker secrets.
• Config Management: Create, inspect, and remove Docker configs.

Installation

Install the package from NPM:

npm install @onreza/docker-api-typescript
yarn add @onreza/docker-api-typescript
pnpm add @onreza/docker-api-typescript
bun add @onreza/docker-api-typescript

By default, the package will work in Auto mode. You can change it manually:

// Auto Mode BUN or NodeJS
import Docker from '@onreza/docker-api-typescript';

// Manual Mode - NodeJS
import Docker from '@onreza/docker-api-typescript/node';

// Manual Mode - Bun
import Docker from '@onreza/docker-api-typescript/bun';

Usage

Example Usage

Here is an example of how to use the Docker API TypeScript client:

import Docker from '@onreza/docker-api-typescript';

// Initialize the Docker client
const docker = new Docker({ socketPath: '/var/run/docker.sock' });
//OR
const docker = new Docker({ endpoint: '127.0.0.1', port: 2375 });

// List all containers
const request = docker.containers.containerList();
const justResponse = await request();
const justData = await justResponse.json();
console.log(justData)

// Pull an image
const request = docker.images.imageCreate({ fromImage: 'alpine', tag: 'latest' });

const myHandler = (chunk) => {
  console.log(chunk);
}

const partResponse = await request(myHandler);

Authorizing to the Docker Registry

You can authorize to a Docker registry using the RegistryAuthentication class:

import { RegistryAuthentication } from '@onreza/docker-api-typescript';

const MyRegistry = new RegistryAuthentication({
  username: 'pepega',
  password: 'qwe123',
  serveraddress: 'some.cool.registry',
});

const docker = new Docker({
  endpoint: '127.0.0.1',
  port: 1337,
  registryAuthentication: MyRegistry,
});

API Reference

DockerClient

The DockerClient class provides methods for interacting with the Docker Engine.

request Method

public async request<T = unknown>(
  options: ConnectRequestProperties
): (callback?: ChunkedCallback) => Promise<void> | Promise<DockerResponse<T>>;

• options: An object of type ConnectRequestProperties, specifying the request configuration.
• Returns: A function that accepts an optional callback of type ChunkedCallback. If a callback is provided, the function returns a Promise<void> for handling chunked data. If no callback is provided, it returns a Promise<DockerResponse<T>> with the expected response type T.

RegistryAuthentication

The RegistryAuthentication class is used to manage Docker registry authentication credentials.

Constructor

new RegistryAuthentication({
  username: string,
  password: string,
  serveraddress: string,
})

• username: The username for the Docker registry.
• password: The password for the Docker registry.
• serveraddress: The server address of the Docker registry.

Services

• containers: Instance of ContainerService to manage Docker containers.
• images: Instance of ImageService to manage Docker images.
• services: Instance of ServiceService to manage Docker services.
• system: Instance of SystemService to manage Docker system operations.
• exec: Instance of ExecService to run commands in containers.
• volume: Instance of VolumeService to manage Docker volumes.
• network: Instance of NetworkService to manage Docker networks.
• plugin: Instance of PluginService to manage Docker plugins.
• node: Instance of NodeService to manage Docker Swarm nodes.
• swarm: Instance of SwarmService to manage Docker Swarm operations.
• task: Instance of TaskService to inspect Docker Swarm tasks.
• secret: Instance of SecretService to manage Docker secrets.
• config: Instance of ConfigService to manage Docker configs.

Contributing

We welcome contributions! Please see the CONTRIBUTING.md for details on how to get started.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Incoming Features

• Add unit tests for each service in the package. (Priority: [Medium])
• Write detailed examples for each service in the API reference section. (Priority: [Low])
• Add TLS support. (Priority: [High])