Skip to content

docs: add separate page for each command #309

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AlexZeitler merged 1 commit into from
Jan 23, 2026
Merged

docs: add separate page for each command #309

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 29 additions & 3 deletions docs/.vitepress/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,41 @@ export default defineConfig({
// https://vitepress.dev/reference/default-theme-config
nav: [
{ text: 'Home', link: '/' },
{ text: 'Getting started', link: '/getting-started' }
{ text: 'Getting started', link: '/getting-started' },
{ text: 'API', link: '/api' }
],

sidebar: [
{
text: 'Docs',
text: 'Introduction',
items: [
{ text: 'Getting started', link: '/getting-started' },
{ text: 'API documentation', link: '/api' }
{ text: 'API Overview', link: '/api' }
]
},
{
text: 'Commands',
items: [
{ text: 'up', link: '/commands/up' },
{ text: 'down', link: '/commands/down' },
{ text: 'stop', link: '/commands/stop' },
{ text: 'restart', link: '/commands/restart' },
{ text: 'build', link: '/commands/build' },
{ text: 'create', link: '/commands/create' },
{ text: 'pull', link: '/commands/pull' },
{ text: 'push', link: '/commands/push' },
{ text: 'config', link: '/commands/config' },
{ text: 'ps', link: '/commands/ps' },
{ text: 'images', link: '/commands/images' },
{ text: 'logs', link: '/commands/logs' },
{ text: 'exec', link: '/commands/exec' },
{ text: 'run', link: '/commands/run' },
{ text: 'rm', link: '/commands/rm' },
{ text: 'kill', link: '/commands/kill' },
{ text: 'pause', link: '/commands/pause' },
{ text: 'port', link: '/commands/port' },
{ text: 'version', link: '/commands/version' },
{ text: 'stats', link: '/commands/stats' }
]
}
],
Expand Down
194 changes: 58 additions & 136 deletions docs/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,163 +6,85 @@ outline: deep

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

## Usage

`docker-compose` current supports these commands:

* `buildAll(options)` - Build or rebuild services
* `buildMany(services, options)` - Build or rebuild services
* `buildOne(service, options)` - Build or rebuild service
* `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
* `createAll(options)` - Create or recreate services
* `createMany(services, options)` - Create or recreate services
* `createOne(service, options)` - Create or recreate service
* `down(options)` - Stops containers and removes containers, networks, volumes, and images created by `up`
* `exec(container, command, options)` - Exec `command` inside `container` - uses `-T` to properly handle stdin & stdout
* `kill(options)` - Force stop service containers
* `images(options)` - Show all created images
* `logs(services, options)` - Show logs of service(s) - use `options.follow` `true|false` to turn on `--follow` flag
* `pauseOne(service, options)` - Pause the specified service
* `port(service, containerPort, options)` - Returns the public port of the given service and internal port.
* `ps(options)` - Lists containers information
* `pullAll(options)` - Pull all service images
* `pullMany(services, options)` - Pull service images specified
* `pullOne(service, options)` - Pull a service image
* `restartAll(options)` - Restart all services
* `restartMany(services, options)` - Restart services
* `restartOne(service, options)` - Restart service
* `rm(options, services)` - Remove stopped service containers - always uses the `-f` flag due to non interactive mode - `services` can optionally be used to select the containers to remove
* `run(service, command, options)` - Run a one-off `command` on a service - uses `-T` to properly handle stdin & stdout
* `stop(options)` - Stop running containers without removing them
* `stopOne(service, options)` - Stops one container without removing it
* `stopMany(options,services)` - Stops containers without removing them
* `unpauseOne(service, options)` - Resume the specified service
* `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
* `version(options)` - Show `docker-compose` version strings
* `stats(service)` - Show service container stats
## Commands

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

## Return Type

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

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

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

### Example

To start service containers based on the `docker-compose.yml` file in your current directory, just call `compose.up` like this:
## Progress Callback

```javascript
compose.upAll({ cwd: path.join(__dirname), log: true })
.then(
() => { console.log('done')},
err => { console.log('something went wrong:', err.message)}
);
```

To get process progress
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.

```typescript
compose.upAll({
cwd: path.join(__dirname),
callback: (chunk: Buffer) => {
console.log('job in progres: ', chunk.toString())
}
})
.then(
() => { console.log('job done')},
err => { console.log('something went wrong:', err.message)}
);
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) }
)
```

To execute command inside a running container:

```javascript
compose.exec('node', 'npm install', { cwd: path.join(__dirname) })
```

### Options
## Options

`docker-compose` accepts these params:

* `cwd {string}`: mandatory folder path to the `docker-compose.yml`
* `executablePath {string}`: optional path to docker-compose executable in case it's not located in $PATH `/path/to/docker-compose`
* `config {(string|string[])}`: custom and/or multiple yml files can be specified (relative to `cwd`)
* `configAsString {string}`: configuration can be provided as is, instead of relying on a file. In case `configAsString` is provided `config` will be ignored.
* `[log] {boolean}`: optional setting to enable console logging (output of `docker-compose` `stdout`/`stderr` output)
* `[composeOptions] string[]|Array<string|string[]`: pass optional compose options like `"--verbose"` or `[["--verbose"], ["--log-level", "DEBUG"]]` or `["--verbose", ["--loglevel", "DEBUG"]]` for *all* commands.
* `[callback] (chunk: Buffer, sourceStream?: 'stdout' | 'stderr') => void`: optional callback function, that provides infromation about the process while it is still runing.
* `[commandOptions] string[]|Array<string|string[]`: pass optional command options like `"--build"` or `[["--build"], ["--timeout", "5"]]` or `["--build", ["--timeout", "5"]]` for the `up` command. Viable `commandOptions` depend on the command (`up`, `down` etc.) itself

### `ps`

`ps(options)` - Lists containers for a Compose project, with current status and exposed ports.

`ps` returns a `Promise` of `TypedDockerComposeResult<DockerComposePsResult>`.
| 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) |
| `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 |

A basic example looks like this:
### Example with options

```javascript
const result = await compose.ps({ cwd: path.join(__dirname) })
result.data.services.forEach((service) => {
console.log(service.name, service.command, service.state, service.ports)
// state is e.g. 'Up 2 hours'
})
```

The resolved `result` might look like this (for v2):

```javascript
{
exitCode: 0,
err: '',
out: 'NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS\n' +
`compose_test_proxy nginx:1.19.9-alpine "/docker-entrypoint.sh nginx -g 'daemon off;'" proxy 1 second ago Up Less than a second 80/tcp\n` +
`compose_test_web nginx:1.16.0 "nginx -g 'daemon off;'" web 1 second ago Up Less than a second 0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp\n`,
data: {
services: [
{
name: 'compose_test_proxy',
command: `"/docker-entrypoint.sh nginx -g 'daemon off;'"`,
state: 'Up Less than a second',
ports: [ { exposed: { port: 80, protocol: 'tcp' } } ]
},
{
name: 'compose_test_web',
command: `"nginx -g 'daemon off;'"`,
state: 'Up Less than a second',
ports: [
{
exposed: { port: 80, protocol: 'tcp' },
mapped: { port: 80, address: '0.0.0.0' }
},
{
exposed: { port: 443, protocol: 'tcp' },
mapped: { port: 443, address: '0.0.0.0' }
}
]
}
]
}
}
```

**Only v2**: If you need a defined state, you can use the `--format json` command option.
This will return one of the defined states `paused | restarting | removing | running | dead | created | exited` as the state of a service.
```typescript
import * as compose from 'docker-compose'
import * as path from 'path'

```javascript
const result = await compose.ps({ cwd: path.join(__dirname), commandOptions: [["--format", "json"]] })
result.data.services.forEach((service) => {
console.log(service.name, service.command, service.state, service.ports)
// state is one of the defined states: paused | restarting | removing | running | dead | created | exited
compose.upAll({
cwd: path.join(__dirname),
config: 'docker-compose.prod.yml',
log: true,
composeOptions: ['--verbose'],
commandOptions: ['--build', ['--timeout', '30']]
})
```
63 changes: 63 additions & 0 deletions docs/commands/build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# build

Build or rebuild services.

## buildAll

Build or rebuild all services.

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

compose.buildAll({ cwd: path.join(__dirname), log: true })
.then(
() => { console.log('done') },
err => { console.log('something went wrong:', err.message) }
)
```

## buildMany

Build or rebuild specified services.

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

compose.buildMany(['service1', 'service2'], { cwd: path.join(__dirname), log: true })
.then(
() => { console.log('done') },
err => { console.log('something went wrong:', err.message) }
)
```

## buildOne

Build or rebuild a single service.

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

compose.buildOne('service1', { cwd: path.join(__dirname), log: true })
.then(
() => { console.log('done') },
err => { console.log('something went wrong:', err.message) }
)
```

## Options

In addition to the [common options](/api#options), `build` commands support these command options:

- `--no-cache` - Do not use cache when building the image
- `--pull` - Always attempt to pull a newer version of the image
- `--parallel` - Build images in parallel

```typescript
compose.buildAll({
cwd: path.join(__dirname),
commandOptions: ['--no-cache', '--pull']
})
```
Loading
Loading