or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

container.md docker-client.md image.md index.md plugin.md swarm.md volume-network.md

tile.json

Image Operations

Image management operations including pulling, building, pushing, tagging, and inspection. Image instances are obtained through the Docker client factory methods and provide comprehensive image lifecycle management.

Capabilities

Image Instance

Image objects are created through Docker client factory methods and represent individual Docker images.

/**
 * Image instance representing a Docker image
 */
class Image {
  /** Image ID or name */
  id: string;
  /** Docker modem instance for API communication */
  modem: any;
  
  constructor(modem: any, id: string);
}

Usage Examples:

const Docker = require('dockerode');
const docker = new Docker();

// Get image instance by name or ID
const image = docker.getImage('ubuntu:latest');
const imageById = docker.getImage('sha256:3c7b2c5e8f9a...');
const imageByRepo = docker.getImage('my-registry.com/my-image:v1.0');

Inspection and Information

Get detailed image information and metadata.

/**
 * Get detailed image information
 * @param opts - Inspection options
 * @param callback - Optional callback
 * @returns Promise resolving to image details
 */
inspect(opts?: InspectOptions, callback?: Function): Promise<ImageInspectInfo>;

/**
 * Get image layer history
 * @param callback - Optional callback
 * @returns Promise resolving to layer history
 */
history(callback?: Function): Promise<ImageHistoryInfo[]>;

/**
 * Get image distribution information from registry
 * @param opts - Distribution options
 * @param callback - Optional callback
 * @returns Promise resolving to distribution info
 */
distribution(opts?: DistributionOptions, callback?: Function): Promise<DistributionInfo>;

interface InspectOptions {
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface ImageInspectInfo {
  Id: string;
  RepoTags: string[];
  RepoDigests: string[];
  Parent: string;
  Comment: string;
  Created: string;
  Container: string;
  ContainerConfig: ContainerConfig;
  DockerVersion: string;
  Author: string;
  Config: ContainerConfig;
  Architecture: string;
  Os: string;
  OsVersion: string;
  Size: number;
  VirtualSize: number;
  GraphDriver: GraphDriver;
  RootFS: RootFS;
  Metadata: {
    LastTagTime: string;
  };
}

interface ImageHistoryInfo {
  Id: string;
  Created: number;
  CreatedBy: string;
  Tags: string[];
  Size: number;
  Comment: string;
}

interface DistributionInfo {
  Descriptor: {
    mediaType: string;
    digest: string;
    size: number;
    urls?: string[];
  };
  Platforms: Platform[];
}

interface Platform {
  architecture: string;
  os: string;
  'os.version'?: string;
  'os.features'?: string[];
  variant?: string;
}

interface GraphDriver {
  Data: object;
  Name: string;
}

interface RootFS {
  Type: string;
  Layers: string[];
  BaseLayer?: string;
}

Usage Examples:

// Get image details
const imageInfo = await image.inspect();
console.log(`Image ID: ${imageInfo.Id}`);
console.log(`Size: ${imageInfo.Size} bytes`);
console.log(`Architecture: ${imageInfo.Architecture}`);
console.log(`OS: ${imageInfo.Os}`);

// Get layer history
const history = await image.history();
history.forEach((layer, index) => {
  console.log(`Layer ${index}: ${layer.CreatedBy}`);
  console.log(`Size: ${layer.Size} bytes`);
});

// Get distribution information
const distribution = await image.distribution();
console.log(`Media Type: ${distribution.Descriptor.mediaType}`);
console.log(`Digest: ${distribution.Descriptor.digest}`);

Image Operations

Core image manipulation operations.

/**
 * Push image to registry
 * @param opts - Push options
 * @param callback - Optional callback
 * @param auth - Registry authentication
 * @returns Promise resolving to push stream
 */
push(opts?: PushOptions, callback?: Function, auth?: AuthConfig): Promise<Stream>;

/**
 * Tag image with new name
 * @param opts - Tag options
 * @param callback - Optional callback
 * @returns Promise resolving to tag result
 */
tag(opts: TagOptions, callback?: Function): Promise<object>;

/**
 * Remove image and return deleted images
 * @param opts - Remove options
 * @param callback - Optional callback
 * @returns Promise resolving to deleted images info
 */
remove(opts?: RemoveOptions, callback?: Function): Promise<ImageDeleteResponse[]>;

/**
 * Export image as tar archive
 * @param callback - Optional callback
 * @returns Promise resolving to export stream
 */
get(callback?: Function): Promise<Stream>;

interface PushOptions {
  /** Tag to push */
  tag?: string;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface TagOptions {
  /** Target repository name */
  repo: string;
  /** Target tag (default: latest) */
  tag?: string;
  /** Force tag creation */
  force?: boolean;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface RemoveOptions {
  /** Force removal of image */
  force?: boolean;
  /** Do not delete untagged parent images */
  noprune?: boolean;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

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

interface ImageDeleteResponse {
  /** Untagged image reference */
  Untagged?: string;
  /** Deleted image ID */
  Deleted?: string;
}

Usage Examples:

// Push image to registry
const pushStream = await image.push({}, undefined, {
  username: 'myuser',
  password: 'mypassword',
  serveraddress: 'https://index.docker.io/v1/'
});

pushStream.on('data', chunk => {
  const progress = JSON.parse(chunk.toString());
  if (progress.status) {
    console.log(progress.status);
  }
});

// Tag image
await image.tag({
  repo: 'my-registry.com/my-app',
  tag: 'v1.0.0'
});

// Remove image
const deleteInfo = await image.remove({ force: true });
deleteInfo.forEach(item => {
  if (item.Deleted) {
    console.log(`Deleted: ${item.Deleted}`);
  }
  if (item.Untagged) {
    console.log(`Untagged: ${item.Untagged}`);
  }
});

// Export image as tar
const exportStream = await image.get();
exportStream.pipe(fs.createWriteStream('image-export.tar'));

Registry Operations

Operations involving Docker registries for image distribution.

/**
 * Pull image from registry (available on Docker client)
 * @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
 */
docker.pull(repoTag: string, opts?: PullOptions, callback?: Function, auth?: AuthConfig): Promise<Stream>;

/**
 * Create/pull image from registry (available on Docker client)
 * @param auth - Registry authentication
 * @param opts - Image creation options
 * @param callback - Optional callback
 * @returns Promise resolving to creation stream
 */
docker.createImage(auth?: AuthConfig, opts?: CreateImageOptions, callback?: Function): Promise<Stream>;

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

interface PullOptions {
  /** Registry authentication */
  authconfig?: AuthConfig;
  /** Tag to pull */
  tag?: string;
  /** Platform for multi-platform images */
  platform?: string;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface CreateImageOptions {
  /** Image name */
  fromImage?: string;
  /** Image source */
  fromSrc?: string;
  /** Repository name */
  repo?: string;
  /** Tag name */
  tag?: string;
  /** Registry authentication */
  authconfig?: AuthConfig;
  /** Platform for multi-platform images */
  platform?: string;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface SearchOptions {
  /** Search term */
  term: string;
  /** Limit number of results */
  limit?: number;
  /** Only show automated builds */
  filters?: {
    'is-automated'?: boolean;
    'is-official'?: boolean;
    stars?: number;
  };
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface SearchResult {
  description: string;
  is_official: boolean;
  is_automated: boolean;
  name: string;
  star_count: number;
}

Usage Examples:

// Pull image from registry
const pullStream = await docker.pull('ubuntu:20.04', {}, undefined, {
  username: 'myuser',
  password: 'mypassword'
});

pullStream.on('data', chunk => {
  const progress = JSON.parse(chunk.toString());
  console.log(progress.status || progress.progress || '');
});

// Search for images
const searchResults = await docker.searchImages({
  term: 'node',
  limit: 10,
  filters: { 'is-official': true }
});

searchResults.forEach(result => {
  console.log(`${result.name}: ${result.description} (${result.star_count} stars)`);
});

Image Building

Build images from Dockerfiles and build contexts.

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

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

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

interface BuildOptions {
  /** Tag for built image */
  t?: string | string[];
  /** Suppress verbose build output */
  q?: boolean;
  /** Do not use cache */
  nocache?: boolean;
  /** Remove intermediate containers */
  rm?: boolean;
  /** Always remove intermediate containers */
  forcerm?: boolean;
  /** Set memory limit for build */
  memory?: number;
  /** Total memory (memory + swap) limit */
  memswap?: number;
  /** CPU shares */
  cpushares?: number;
  /** CPU quota */
  cpuquota?: number;
  /** CPU period */
  cpuperiod?: number;
  /** CPUs allowed to use */
  cpusetcpus?: string;
  /** MEMs allowed to use */
  cpusetmems?: string;
  /** Size of /dev/shm */
  shmsize?: number;
  /** Build arguments */
  buildargs?: { [key: string]: string };
  /** Labels to add to image */
  labels?: { [key: string]: string };
  /** Dockerfile name */
  dockerfile?: string;
  /** Target build stage */
  target?: string;
  /** Platform for multi-platform builds */
  platform?: string;
  /** Network mode for RUN instructions */
  networkmode?: string;
  /** Ulimit options */
  ulimits?: Ulimit[];
  /** Registry authentication */
  authconfig?: { [registry: string]: AuthConfig };
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface LoadOptions {
  /** Suppress verbose output */
  quiet?: boolean;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface ImportOptions {
  /** Repository name */
  repo?: string;
  /** Tag name */
  tag?: string;
  /** Commit message */
  message?: string;
  /** Apply Dockerfile instruction */
  changes?: string[];
  /** Platform for imported image */
  platform?: string;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface Ulimit {
  Name: string;
  Soft: number;
  Hard: number;
}

Usage Examples:

const tar = require('tar-fs');
const fs = require('fs');

// Build image from directory
const buildStream = await docker.buildImage(tar.pack('./my-app'), {
  t: 'my-app:latest',
  dockerfile: 'Dockerfile',
  buildargs: {
    NODE_VERSION: '18',
    BUILD_ENV: 'production'
  },
  labels: {
    'com.example.version': '1.0.0',
    'com.example.build-date': new Date().toISOString()
  }
});

buildStream.on('data', chunk => {
  const buildInfo = JSON.parse(chunk.toString());
  if (buildInfo.stream) {
    process.stdout.write(buildInfo.stream);
  }
});

// Load image from tar file
const loadStream = fs.createReadStream('image.tar');
const loadResult = await docker.loadImage(loadStream);

loadResult.on('data', chunk => {
  const loadInfo = JSON.parse(chunk.toString());
  console.log(loadInfo);
});

// Import filesystem as image
const importStream = fs.createReadStream('rootfs.tar');
const importResult = await docker.importImage(importStream, {
  repo: 'my-imported-image',
  tag: 'latest',
  message: 'Imported from filesystem'
});

Multi-Image Operations

Operations that work with multiple images.

/**
 * Export multiple images as tar archive (available on Docker client)
 * @param opts - Export options
 * @param callback - Optional callback
 * @returns Promise resolving to export stream
 */
docker.getImages(opts?: GetImagesOptions, callback?: Function): Promise<Stream>;

/**
 * Pull all tags for repository (available on Docker client)
 * @param repoTag - Repository name
 * @param opts - Pull options
 * @param callback - Optional callback
 * @param auth - Registry authentication
 * @returns Promise resolving to pull stream
 */
docker.pullAll(repoTag: string, opts?: object, callback?: Function, auth?: AuthConfig): Promise<Stream>;

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

Usage Examples:

// Export multiple images
const exportStream = await docker.getImages({
  names: ['ubuntu:latest', 'node:18', 'my-app:v1.0']
});
exportStream.pipe(fs.createWriteStream('multiple-images.tar'));

// Pull all tags for repository
const pullAllStream = await docker.pullAll('ubuntu');
pullAllStream.on('data', chunk => {
  const progress = JSON.parse(chunk.toString());
  console.log(progress.status);
});

Version

Tile

Files

image.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Image Operations

Capabilities

Image Instance

Inspection and Information

Image Operations

Registry Operations

Image Building

Multi-Image Operations

image.mddocs/