# docker-run

> Start a docker image and attach to it

Latest version **3.1.0** (published 2017-09-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install docker-run
pnpm add docker-run
yarn add docker-run
bun add docker-run
```

Provides the command `docker-run`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.1.0 |
| Published | 2017-09-27 |
| First published | 2014-10-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 6 |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 58 |
| Author | Mathias Buus |
| Maintainers | maxogden, mafintosh |
| Keywords | docker, run |

## Links

- npm: https://www.npmjs.com/package/docker-run
- Repository: https://github.com/mafintosh/docker-run
- Issues: https://github.com/mafintosh/docker-run/issues
- npm.io page: https://npm.io/package/docker-run

## Dependencies (6)

- [pump](https://npm.io/package/pump.md) ^1.0.0
- [debug](https://npm.io/package/debug.md) ^1.0.2
- [minimist](https://npm.io/package/minimist.md) ^1.1.0
- [through2](https://npm.io/package/through2.md) ^0.6.2
- [docker-raw-stream](https://npm.io/package/docker-raw-stream.md) ^1.3.0
- [docker-remote-api](https://npm.io/package/docker-remote-api.md) ^4.4.0

## Alternatives

- [@mce/gif](https://npm.io/package/@mce/gif.md) — 2.6K weekly downloads
- [cleanse](https://npm.io/package/cleanse.md) — 173 weekly downloads
- [str](https://npm.io/package/str.md) — 127 weekly downloads
- [naming](https://npm.io/package/naming.md) — 95 weekly downloads
- [tap-telco-api](https://npm.io/package/tap-telco-api.md) — 19 weekly downloads

## Recent versions

- 3.1.0 (latest) — 2017-09-27
- 3.0.0 — 2016-11-21
- 2.4.0 — 2016-01-23
- 2.3.0 — 2015-11-15
- 2.2.0 — 2015-07-26
- 2.1.0 — 2015-07-15
- 2.0.0 — 2014-10-25
- 1.3.0 — 2014-10-23
- 1.2.3 — 2014-10-19
- 1.2.2 — 2014-10-08
- 1.2.1 — 2014-10-08
- 1.2.0 — 2014-10-08
- 1.1.1 — 2014-10-08
- 1.1.0 — 2014-10-08
- 1.0.1 — 2014-10-07
- … 2 more at https://npm.io/package/docker-run/versions

## README

# docker-run

Start a docker image and attach to it

```
npm install docker-run
```

[There is also a command line tool available](https://github.com/mafintosh/docker-run#command-line-usage)

## Usage

``` js
var run = require('docker-run')

var child = run('mafintosh/dev', {tty:true})

process.stdin.setRawMode(true)
process.stdin.pipe(child.stdin)
child.stdout.pipe(process.stdout)
child.stderr.pipe(process.stderr)
```

## API

* `child = run(image, [options])`

Where options can be

``` js
{
  net: 'bridge',    // network mode (auto | host | bridge). defaults to bridge
  tty: true,        // be a tty. defaults to false
  fork: true,       // fork (do not attach stdio). defaults to false
  remove: true,     // remove the container on stop. defaults to true
  dns: ['8.8.8.8'], // set custom dns servers
  ports: {
    8080: 8081      // expose container 8080 to host 8081
  },
  volumes: {
    '/root': '/tmp', // expose container /root to host /tmp
    '/root': '/tmp2:ro' // expose container /root to host /tmp2 as read only
  },
  links: {
    'container-name': 'alias' // link container-name as alias
  },
  env: {
    FOO: 'bar'      // set env vars
  },
  entrypoint: '/bin/bash' // override entrypoint on container,
  beforeCreate: function (remoteOpts, instance) {} // remoteOpts is the generated docker remote JSON
}
```

* `child.stdin`, `child.stderr`, `child.stdout`

The stdio streams for the container. Is `null` if `fork: true`

* `child.destroy()`

Destroy the child container

* `child.resize(wid, hei)`

Resize the container pty (if `tty: true`)

## Events

* `child.on('exit', exitCode)`

Emitted when the container exits

* `child.on('spawn', containerId)`

Emitted when the container is spawned

* `child.on('error', error)`

Emitted if the container experiences a fatal error

## Command line usage

To install the command line tool do

```
npm install -g docker-run
```

And then run

```
docker-run --help
```

To view the help. In general to run an image do

```
docker-run [image]
```

## License

MIT

---
_Source: https://npm.io/package/docker-run · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._