compose2spec

Convert Docker Compose files to Docker Engine API ServiceSpec objects for use with Docker Swarm.

Overview

compose2spec is a TypeScript library that converts Docker Compose YAML files (v2 and v3) into an array of Docker Engine API ServiceSpec objects. These objects can be directly used with dockerode.createService() to deploy services to a Docker Swarm cluster.

Features

• ✅ Converts Docker Compose v2/v3 to Docker Swarm ServiceSpec
• ✅ Full TypeScript support with type definitions
• ✅ Supports environment variables, ports, volumes, networks
• ✅ Handles resource limits (CPU, memory)
• ✅ Supports deploy configurations (replicas, resources)
• ✅ ESM and CommonJS module support
• ✅ Comprehensive test coverage

Installation

npm install compose2spec

Usage

Basic Usage

import { parseComposeToServiceSpecs } from 'compose2spec';
import Dockerode from 'dockerode';

// Create Dockerode instance
const docker = new Dockerode();

// Parse compose file
const specs = await parseComposeToServiceSpecs('./docker-compose.yml');

// Create services in Docker Swarm
await Promise.all(specs.map(spec => docker.createService(spec)));

Using with string input

import { parseComposeToServiceSpecs } from 'compose2spec';

const composeYaml = `
version: "3.9"
services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    environment:
      - FOO=bar
    deploy:
      replicas: 2
      resources:
        limits:
          memory: 512M
          cpus: "0.5"
`;

const specs = await parseComposeToServiceSpecs(composeYaml);

Synchronous parsing

import { parseComposeToServiceSpecsSync } from 'compose2spec';

const specs = parseComposeToServiceSpecsSync('./docker-compose.yml');

Supported Compose Features

• Services - image, command, entrypoint, environment
• Ports - published/target port mappings
• Volumes - bind, volume, and tmpfs mounts
• Networks - service network attachments
• Deploy - replicas, resource limits (CPU/memory)
• Environment - both array and object formats

API

parseComposeToServiceSpecs(input: string | object): Promise<ServiceSpec[]>

Async function to parse Docker Compose file to ServiceSpec array.

• input: Path to compose file, YAML string, or parsed object

parseComposeToServiceSpecsSync(input: string | object): ServiceSpec[]

Synchronous version of the parser.

composeServiceToSpec(serviceName: string, serviceDef: object): ServiceSpec

Convert a single service definition to a ServiceSpec.

Example

Input (docker-compose.yml):

version: "3.9"
services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    environment:
      - FOO=bar
      - BAZ=qux
    deploy:
      replicas: 2
      resources:
        limits:
          memory: 512M
          cpus: "0.5"
    volumes:
      - data:/usr/share/nginx/html
    networks:
      - frontend

networks:
  frontend:
volumes:
  data:

Output:

[
  {
    "Name": "web",
    "TaskTemplate": {
      "ContainerSpec": {
        "Image": "nginx:latest",
        "Env": ["FOO=bar", "BAZ=qux"],
        "Mounts": [{
          "Type": "volume",
          "Source": "data",
          "Target": "/usr/share/nginx/html"
        }]
      },
      "Resources": {
        "Limits": {
          "NanoCPUs": 500000000,
          "MemoryBytes": 536870912
        }
      }
    },
    "Mode": {
      "Replicated": {
        "Replicas": 2
      }
    },
    "Networks": [{
      "Target": "frontend"
    }],
    "EndpointSpec": {
      "Ports": [{
        "Protocol": "tcp",
        "PublishedPort": 8080,
        "TargetPort": 80
      }]
    }
  }
]

License

MIT