API Docs

This page demonstrates the usage of docker-compose for Node.js.

Commands

Command	Description
up	Builds, (re)creates, starts, and attaches to containers
down	Stops and removes containers, networks, volumes, and images
stop	Stops running containers without removing them
restart	Restart services
build	Build or rebuild services
create	Create containers without starting them
pull	Pull service images
push	Push service images
config	Validate and view configuration
ps	List containers
images	List images
logs	View container logs
exec	Execute a command in a running container
run	Run a one-off command
rm	Remove stopped containers
kill	Force stop containers
pause	Pause and unpause services
port	Print public port for a port binding
version	Show version information
stats	Display container resource usage

Return Type

All commands return a Promise({object}) with stdout and stderr strings and an exit code:

{
  out: 'stdout contents',
  err: 'stderr contents',
  exitCode: 0, // !== 0 in case of an error
  truncated: { out: false, err: false },
}

truncated.out and truncated.err indicate whether any output was dropped from the corresponding stream, including when buffering is disabled. These flags are also present on results rejected for a nonzero exit code and on typed results with a data field. Commands that parse stdout (config, configServices, configVolumes, ps, images, port, version, and stats) reject with an error mentioning maxOutputLength if stdout was truncated. Truncating only stderr does not prevent parsing stdout.

Progress Callback

Although the return type is a Promise, it is still possible to get the process progress before the Promise resolves, by passing a callback function to the optional callback parameter.

compose.upAll({
  cwd: path.join(__dirname),
  callback: (chunk: Buffer) => {
    console.log('job in progress: ', chunk.toString())
  }
}).then(
  () => { console.log('job done') },
  err => { console.log('something went wrong:', err.message) }
)

Output buffering

Use maxOutputLength to limit how much output is retained independently for stdout and stderr. The limit counts UTF-16 code units, as measured by JavaScript's string.length, and defaults to Node.js's buffer.constants.MAX_STRING_LENGTH. Stdout retains the beginning of the output; stderr retains a trailing window so the most recent error messages remain available. Reaching the limit does not stop the command, and callback and log still receive all output.

Set maxOutputLength: 0 to disable buffering completely and process output only as it arrives. out and err remain empty strings, and each truncation flag becomes true if its stream emits nonempty output:

await compose.logs('web', {
  cwd: path.join(__dirname),
  follow: true,
  maxOutputLength: 0,
  callback: (chunk, streamSource) => {
    const stream = streamSource === 'stderr' ? process.stderr : process.stdout
    stream.write(chunk)
  }
})

Finite limits are rounded down and clamped between 0 and buffer.constants.MAX_STRING_LENGTH. Non-finite values use the default limit.

Options

docker-compose accepts these params:

Option	Type	Description
cwd	string	Required. Folder path to the docker-compose.yml
executablePath	string	Path to docker-compose executable if not in $PATH
config	string | string[]	Custom yml file(s), relative to cwd
configAsString	string	Configuration as string (ignores config if set)
compose	ComposeSpecification	Typed compose configuration object (converted to YAML internally)
log	boolean	Enable console logging
composeOptions	string[] | Array<string | string[]>	Options for all commands (e.g., --verbose)
commandOptions	string[] | Array<string | string[]>	Options for specific command
maxOutputLength	number	Maximum UTF-16 code units retained per stream; defaults to buffer.constants.MAX_STRING_LENGTH. 0 disables buffering.
callback	(chunk: Buffer, sourceStream?: 'stdout' | 'stderr') => void	Progress callback

Example with options

import * as compose from 'docker-compose'
import * as path from 'path'

compose.upAll({
  cwd: path.join(__dirname),
  config: 'docker-compose.prod.yml',
  log: true,
  composeOptions: ['--verbose'],
  commandOptions: ['--build', ['--timeout', '30']]
})

Example with typed compose object

Instead of using a YAML file, you can pass a typed ComposeSpecification object directly. This gives you full TypeScript autocompletion and type checking for the Docker Compose configuration.

import { upAll, ComposeSpecification } from 'docker-compose'

const compose: ComposeSpecification = {
  services: {
    web: {
      image: 'nginx:latest',
      ports: ['8080:80']
    },
    db: {
      image: 'postgres:16',
      environment: {
        POSTGRES_PASSWORD: 'secret'
      }
    }
  }
}

await upAll({ compose })

The ComposeSpecification type is generated from the official Compose Specification JSON Schema, so it covers all valid compose file options.