@fnet/container-cmd-builder

This project provides a straightforward utility to help you generate Docker or Podman command-line instructions for managing containers. It takes a set of parameters as input and outputs command strings that you can use to create, control, and interact with containers using either Docker or Podman.

How It Works

The utility accepts an object with various configuration options such as the container image, name, port and volume mappings, environment variables, and more. Based on these inputs, it constructs commands that cater to different lifecycle operations for a container, like running, starting, stopping, or inspecting it. The focus is on automating the generation of these commands to streamline the container management process.

Key Features

Container Runtime Support: Works with both Podman (default) and Docker.
Command Generation: Produces a variety of management commands including run, start, stop, pause, exec, inspect, and more.
Customizable Options: Allows detailed configuration with options for ports, volumes, environment variables, network settings, resource limits, and security settings.
Lifecycle Management: Provides commands for controlling the full lifecycle of a container.

Conclusion

This utility simplifies the process of generating command-line instructions for managing containers with Docker or Podman. It enables users to efficiently configure and control container environments by automating command creation, thus making container management less error-prone and more accessible.

@fnet/container-cmd-builder Developer Guide

Overview

The @fnet/container-cmd-builder library assists developers in generating command-line instructions for managing container lifecycles using either Docker or Podman. It simplifies the creation of commands needed to run, manage, and interact with containers. This library is designed for developers who want to automate container operations programmatically with ease.

Installation

To include the @fnet/container-cmd-builder library in your project, use npm or yarn as follows:

npm install @fnet/container-cmd-builder

yarn add @fnet/container-cmd-builder

Usage

Here's a step-by-step guide to using the library with real-world applications. The library allows for the configuration and generation of commands based on user inputs, making container management straightforward.

Example Usage

Below is an example of how to use the library to create commands for container operations:

import createContainerCommands from '@fnet/container-cmd-builder';

// Configuration object for the container
const config = {
  image: 'nginx', // Container image
  containerName: 'my-nginx-container', // Name of the container
  ports: [[8080, 80]], // Port mapping
  volumes: [['/local/path', '/container/path']], // Volume mapping
  env: { ENV_VAR: 'value' }, // Environment variables
  detached: true, // Run in detached mode
  runtime: 'docker', // Use Docker as the runtime
};

// Generate container commands
const commands = createContainerCommands(config);

// Output the 'run' command
console.log(commands.run); // Output: docker run -d --name my-nginx-container -p 8080:80 -v "/local/path":"/container/path" -e ENV_VAR="value" nginx

Examples

Running a Container

To run a container using the generated command:

const runCommand = commands.run;
console.log(runCommand); // Outputs the complete 'run' command for execution

Stopping a Container

To stop the running container:

const stopCommand = commands.stop;
console.log(stopCommand); // Outputs 'docker stop my-nginx-container'

Removing a Container

To remove the container:

const removeCommand = commands.remove;
console.log(removeCommand); // Outputs 'docker rm my-nginx-container'

Customizing Commands

You can customize commands using additional options:

const pauseCommand = commands.pauseWith('--time=5');
console.log(pauseCommand); // Outputs 'docker pause --time=5 my-nginx-container'

Acknowledgement

This library provides a straightforward API for developers to interact with containers using common runtime environments like Docker and Podman. Contributions from the community and the maintainers have ensured that this tool remains concise and useful for everyday container management tasks.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  image:
    type: string
    description: The container image to be used.
  containerName:
    type: string
    description: Optional name for the container.
  ports:
    type: array
    description: Array of port mappings as [hostPort, containerPort].
    items:
      type: array
      minItems: 2
      maxItems: 2
      items:
        type: number
  volumes:
    type: array
    description: Array of volume mappings as [hostPath, containerPath].
    items:
      type: array
      minItems: 2
      maxItems: 2
      items:
        type: string
  env:
    type: object
    description: Environment variables as key-value pairs.
    additionalProperties:
      type: string
  labels:
    type: object
    description: Labels as key-value pairs.
    additionalProperties:
      type: string
  detached:
    type: boolean
    description: Run the container in detached mode if true.
    default: true
  command:
    type: array
    description: Additional commands to run inside the container.
    items:
      type: string
  runtime:
    type: string
    description: Container runtime, either 'podman' (default) or 'docker'.
    default: podman
  restartPolicy:
    type: string
    description: Restart policy for the container (e.g., 'always', 'on-failure').
  network:
    type: string
    description: Network mode to use (e.g., 'bridge', 'host').
  logDriver:
    type: string
    description: Log driver to use for the container.
  logOptions:
    type: object
    description: Logging options with key-value pairs.
    additionalProperties:
      type: string
  cpuLimit:
    type: number
    description: CPU limit for the container.
  memoryLimit:
    type: string
    description: Memory limit for the container.
  securityOptions:
    type: array
    description: Security options for the container.
    items:
      type: string
required:
  - image
  - containerName