---
layout: default
title: README
nav_order: 99
---
# Manage Docker-Compose via Node.js
`docker-compose` is a small library that allows you to run [docker-compose](https://docs.docker.com/compose/)(which is still required) via Node.js. This is useful to bootstrap test environments. You might also generate your `docker-compose.yml` files using [composefile](https://www.npmjs.com/package/composefile).
## Existing user? We need your help
First of all: thanks for using the `docker-compose` module.
As described in [#44][i44], we're planning to provide more guidance for CI/CD when using the `docker-compose` module and it would be great if you could support us here. More details in [#44][i44].
[i44]: https://github.com/PDMLab/docker-compose/issues/44
## Installation
```
npm install --save-dev docker-compose
```
## Usage
`docker-compose` current supports these commands:
* `upAll(options)` - Builds, (re)creates, starts, and attaches to containers for all services - always uses the `-d` flag due to non interactive mode
* `upMany(services, options)` - Builds, (re)creates, starts, and attaches to containers for the services specified in `services` - always uses the `-d` flag due to non interactive mode
* `upOne(service, options)` - Builds, (re)creates, starts, and attaches to containers for a service specified in `service` - always uses the `-d` flag due to non interactive mode
* `down(options)` - Stops containers and removes containers, networks, volumes, and images created by `up`
* `kill(options)` - Force stop service containers
* `stop(options)` - Stop running containers without removing them
* `rm(options)` - Remove stopped service containers - always uses the `-f` flag due to non interactive mode
* `exec(container, command, options)` - Exec `command` inside `container`, uses `-T` to properly handle stdin & stdout
* `logs(container, command, options)` - Show logs of service. Use `options.follow` `true|false` to turn on `--follow` flag.
* `run(service, command, options)` - Run a one-off `command` on a service, uses `-T` to properly handle stdin & stdout
* `buildAll(options)` - Build or rebuild services
* `buildMany(services, options)` - Build or rebuild services
* `buildOne(service, options)` - Build or rebuild service
* `restartAll(options)` - Restart all services
* `restartMany(services, options)` - Restart services
* `restartOne(service, options)` - Restart service
* `ps(options)` - Lists containers information
* `config(options)` - Validates configuration files and returns configuration yaml
* `configServices(options)` - Returns list of services defined in configuration files
* `configVolumes(options)` - Returns list of volumes defined in configuration files
All commands return a `Promise({object})` with stdout and stderr strings and an exit code:
```javascript
{
out: 'stdout contents',
err: 'stderr contents',
exitCode: 0, // !== 0 in case of an error
}
```
### Example
To start service containers based on the `docker-compose.yml` file in your current directory, just call `compose.up` like this:
```javascript
compose.upAll({ cwd: path.join(__dirname), log: true })
.then(
() => { console.log('done')},
err => { console.log('something went wrong:', err.message)}
);
```
To execute command inside a running container
```javascript
compose.exec('node', 'npm install', { cwd: path.join(__dirname) })
```
### Options
`docker-compose` accepts these params:
* `cwd {string}`: mandatory folder path to the `docker-compose.yml`
* `config {(string|string[])}`: custom and/or multiple yml files can be specified (relative to `cwd`)
* `[log] {boolean}`: optional setting to enable console logging (output of `docker-compose` `stdout`/`stderr` output)
* `[composeOptions] string[]|Array