Skip to content

api.md

Latest commit

 

History

History
119 lines (97 loc) · 3.96 KB

api.md

File metadata and controls

119 lines (97 loc) · 3.96 KB
outline deep
category Reference

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.