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
}

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) }
)

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
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.