From 32ffd64236b48e5aab6abc4474554047ad411276 Mon Sep 17 00:00:00 2001 From: David Worms Date: Sun, 30 Jul 2017 13:00:37 +0200 Subject: [PATCH] docker: doc cleanup #119 --- CHANGELOG.md | 2 + src/docker/build.coffee.md | 93 ++++++++++++++-------------- src/docker/checksum.coffee.md | 20 +++--- src/docker/compose/index.coffee.md | 4 +- src/docker/cp.coffee.md | 15 ++--- src/docker/exec.coffee.md | 34 +++++------ src/docker/kill.coffee.md | 26 +++----- src/docker/load.coffee.md | 34 +++++------ src/docker/login.coffee.md | 4 +- src/docker/logout.coffee.md | 24 +++----- src/docker/pause.coffee.md | 24 +++----- src/docker/pull.coffee.md | 20 +++--- src/docker/restart.coffee.md | 20 +++--- src/docker/rm.coffee.md | 26 +++++--- src/docker/rmi.coffee.md | 15 +++-- src/docker/run.coffee.md | 98 ++++++++++++++---------------- src/docker/save.coffee.md | 44 ++++++-------- src/docker/service.coffee.md | 1 + src/docker/start.coffee.md | 52 +++++++--------- src/docker/status.coffee.md | 28 ++++----- src/docker/stop.coffee.md | 24 +++----- src/docker/unpause.coffee.md | 22 +++---- src/docker/volume_create.coffee.md | 19 ++++-- src/docker/volume_rm.coffee.md | 21 ++++--- src/docker/wait.coffee.md | 24 +++----- src/misc/docker.coffee.md | 1 + 26 files changed, 321 insertions(+), 374 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 073f60092..b90d61540 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,8 @@ ## Trunk +* docker: doc cleanup #119 +* misc: merge support null as first argument * rubygem: source support glob expression * rubygem: improve test suport and resilience * rubygem: new fetch, install and remove actions diff --git a/src/docker/build.coffee.md b/src/docker/build.coffee.md index f8b789f5b..adef928c9 100644 --- a/src/docker/build.coffee.md +++ b/src/docker/build.coffee.md @@ -3,39 +3,41 @@ Build docker repository from Dockerfile, from content or from current working directory (exclusive options). + The user can choose whether the build is local or on the remote. Options are the same than docker build command with nikita's one. Be aware than you can not use ADD with content option because docker build from STDIN does not support a context. + By default docker always run the build and overwrite existing repositories. Status unmodified if the repository is identical to a previous one ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. + Whether to use boot2docker or not, default to false. * `image` (string) - Name of the image. __Mandatory__ + Name of the image, required. * `tag` (string) - Tag of the image + Tag of the image. * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine + Name of the docker-machine, required if using docker-machine. * `file` - Dockerfile path + Path to Dockerfile. * `content` (string | [string]) - Use this text to build the repository. + Use this text to build the repository. * `quiet` (boolean) - Suppress the verbose output generated by the containers. Default to false + Suppress the verbose output generated by the containers. Default to false * `rm` (boolean) - Remove intermediate containers after build. Default to true + Remove intermediate containers after build, default to true. * `force_rm` (boolean) - Always remove intermediate containers during build. Default to false + Always remove intermediate containers during build, default to false. * `no_cache` (boolean) - Do not use cache when building the repository. Default to false + Do not use cache when building the repository, default to false. * `build_arg` ("k=v" | []) - Send arguments to the build (Must match an ARG command). + Send arguments to the build (Must match an ARG command). * `cwd` (string) - change the working directory for the build. + change the working directory for the build. ## Callback parameters @@ -52,37 +54,36 @@ Status unmodified if the repository is identical to a previous one ## Example -1- builds a repository from dockerfile without any resourcess +### Builds a repository from dockerfile without any resourcess ```javascript nikita.docker.build({ - image: 'ryba/targe-build' + image: 'ryba/targe-build', source: '/home/ryba/Dockerfile' -}, function(err, is_true, stdout, stderr){ - if(err){ - console.log(err.message); - }else if(is_true){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } -}) +}, function(err, status, stdout, stderr){ + console.log( err ? err.message : 'Container built: ' + status); +}); ``` -2- builds an repository from dockerfile with external resources +### Builds an repository from dockerfile with external resources In this case nikita download all the external files into a resources directory in the same location -than the Dockerfile. -The Dockerfile content: " - FROM centos6 - ADD resources/package.tar.gz /tmp/ - ADD resources/configuration.sh /tmp/ - " +than the Dockerfile. The Dockerfile content: + +```dockerfile +FROM centos7 +ADD resources/package.tar.gz /tmp/ +ADD resources/configuration.sh /tmp/ +``` + Build directory tree : - ├── Dockerfile - ├── resources - │   ├── package.tar.gz - │   ├── configuration.sh + +``` +├── Dockerfile +├── resources +│   ├── package.tar.gz +│   ├── configuration.sh +``` ```javascript nikita.docker.build({ @@ -90,32 +91,28 @@ nikita.docker.build({ tag: 'ryba/target-build' source: '/home/ryba/Dockerfile' resources: ['http://url.com/package.tar.gz/','/home/configuration.sh'] -}, function(err, is_built, stdout, stderr){ - if(err){ - console.log(err.message); - }else if(is_built){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } -}) +}, function(err, status, stdout, stderr){ + console.log( err ? err.message : 'Container built: ' + status); +}); ``` -3- builds an repository from stdin +### Builds an repository from stdin ```javascript nikita.docker.build({ - ssh: ssh + ssh: ssh, tag: 'ryba/target-build' content: "FROM ubuntu\nRUN echo 'helloworld'" -}, function(err, is_built, stdout, stderr){}) -`` +}, function(err, is_built, stdout, stderr){ + console.log( err ? err.message : 'Container built: ' + status); +}); +``` ## Source Code module.exports = (options, callback) -> options.log message: "Entering Docker build", level: 'DEBUG', module: 'nikita/lib/docker/build' - # Validate parameters and __Mandatory__ conditions + # Validation options.docker ?= {} options[k] ?= v for k, v of options.docker return callback Error 'Required option "image"' unless options.image? diff --git a/src/docker/checksum.coffee.md b/src/docker/checksum.coffee.md index 6c6904766..8e58c762a 100644 --- a/src/docker/checksum.coffee.md +++ b/src/docker/checksum.coffee.md @@ -6,32 +6,32 @@ Return the checksum of repository:tag, if it exists. Function not native to dock ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. + Whether to use boot2docker or not, default to false. * `cwd` (string) - change the working directory for the build. + change the working directory for the build. * `image` (string) - Name of the image, required. + Name of the image, required. * `repository` (string) - Alias of image. + Alias of image. * `machine` (string) - Name of the docker-machine, required if using docker-machine. + Name of the docker-machine, required if using docker-machine. * `tag` (string) - Tag of the image, default to latest. + Tag of the image, default to latest. ## Callback parameters * `err` - Error object if any. + Error object if any. * `status` - True if command was executed. + True if command was executed. * `checksum` - Image cheksum if it exist, false otherwise. + Image cheksum if it exist, false otherwise. ## Source Code module.exports = (options, callback) -> options.log message: "Entering Docker checksum", level: 'DEBUG', module: 'nikita/lib/docker/checksum' - # Validate parameters and __Mandatory__ conditions + # Validation options.docker ?= {} options[k] ?= v for k, v of options.docker options.image ?= options.repository diff --git a/src/docker/compose/index.coffee.md b/src/docker/compose/index.coffee.md index 1447d1af4..a827bdd48 100644 --- a/src/docker/compose/index.coffee.md +++ b/src/docker/compose/index.coffee.md @@ -9,7 +9,7 @@ Create and start containers according to a docker-compose file * `boot2docker` (boolean) Whether to use boot2docker or not, default to false. * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine + Name of the docker-machine, required if using docker-machine * `content` (string) The content of the docker-compose.yml to write if not exist. * `eof` (string) @@ -24,7 +24,7 @@ Create and start containers according to a docker-compose file * `services` (string|array) Specify specific services to create. * `target` (string) - The docker-compose.yml absolute's file's path. Mandatory if no content is + The docker-compose.yml absolute's file's path, required if no content is specified. * `code` (int|array) Expected code(s) returned by the command, int or array of int, default to 0. diff --git a/src/docker/cp.coffee.md b/src/docker/cp.coffee.md index daa2eaa45..4360c3728 100644 --- a/src/docker/cp.coffee.md +++ b/src/docker/cp.coffee.md @@ -16,13 +16,13 @@ Note, stream are not yet supported. ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. + Whether to use boot2docker or not, default to false. * `machine` (string) - Name of the docker-machine, required if using docker-machine or boot2docker. + Name of the docker-machine, required if using docker-machine or boot2docker. * `source` (string) - The path to upload or the container followed by the path to download. + The path to upload or the container followed by the path to download. * `target` (string) - The path to download or the container followed by the path to upload. + The path to download or the container followed by the path to upload. ## Uploading a file @@ -37,9 +37,11 @@ nikita.docker({ ```javascript nikita.docker({ - source: 'my_container:/path/to/source' + source: 'my_container:/path/to/source', target: writable_stream or '/path/to/target' -}, function(err, status){}) +}, function(err, status){ + console.log( err ? err.message : 'Container copied: ' + status); +}); ``` ## Source Code @@ -92,7 +94,6 @@ nikita.docker({ ## Modules Dependencies - # file = require('../misc').file path = require 'path' ssh2fs = require 'ssh2-fs' docker = require '../misc/docker' diff --git a/src/docker/exec.coffee.md b/src/docker/exec.coffee.md index 23dc8ea3b..31285c82b 100644 --- a/src/docker/exec.coffee.md +++ b/src/docker/exec.coffee.md @@ -6,27 +6,27 @@ Run a command in a running container ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. + Whether to use boot2docker or not, default to false. * `container` (string) - Name/ID of the container. __Mandatory__ + Name/ID of the container, required. * `code_skipped` (int | array) - The exit code(s) to skip. + The exit code(s) to skip. * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine. + Name of the docker-machine, required using docker-machine. * `service` (boolean) - if true, run container as a service, else run as a command, true by default. + if true, run container as a service, else run as a command, true by default. * `uid` (name | uid) - Username or uid. + Username or uid. * `gid` (name | gid) - Groupname or gid. + Groupname or gid. ## Callback parameters * `err` Error object if any. -* `executed` - if command was executed +* `status` + True if command was executed in container. * `stdout` Stdout value(s) unless `stdout` option is provided. * `stderr` @@ -36,18 +36,12 @@ Run a command in a running container ```javascript nikita.docker({ - ssh: ssh - container: 'myContainer' + ssh: ssh, + container: 'myContainer', cmd: '/bin/bash -c "echo toto"' -}, function(err, is_true, stdout, stderr){ - if(err){ - console.log(err.message); - }else if(is_true){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } -}) +}, function(err, status, stdout, stderr){ + console.log( err ? err.message : 'Command executed: ' + status); +}); ``` ## Source Code diff --git a/src/docker/kill.coffee.md b/src/docker/kill.coffee.md index 1f3a0bbae..1019d25e0 100644 --- a/src/docker/kill.coffee.md +++ b/src/docker/kill.coffee.md @@ -9,35 +9,29 @@ SIGNAL is not sent. ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. + Whether to use boot2docker or not, default to false. * `container` (string) - Name/ID of the container. __Mandatory__ + Name/ID of the container, required. * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine. + Name of the docker-machine, required if using docker-machine. * `signal` (int|string) - Use a specified signal. SIGKILL by default + Use a specified signal. SIGKILL by default. ## Callback parameters * `err` - Error object if any. -* `executed` - if command was executed + Error object if any. +* `status` + True if container was killed. ## Example ```javascript nikita.docker.kill({ - container: 'toto' + container: 'toto', signal: 9 -}, function(err, is_true){ - if(err){ - console.log(err.message); - }else if(is_true){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } +}, function(err, status){ + console.log( err ? err.message : 'Container killed: ' + status); }) ``` diff --git a/src/docker/load.coffee.md b/src/docker/load.coffee.md index ddb7dadc6..ace71f0aa 100644 --- a/src/docker/load.coffee.md +++ b/src/docker/load.coffee.md @@ -1,32 +1,32 @@ # `nikita.docker.load(options, [callback])` -Load Docker images +Load Docker images. ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. + Whether to use boot2docker or not, default to false. * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine + Name of the docker-machine, required if using docker-machine. * `input` (string) - TAR archive file to read from + TAR archive file to read from. * `source` (string) - Alias for the "input" option. + Alias for the "input" option. * `checksum` (string) - If provided, will check if attached input archive to checksum already exist. - Not native to docker. But implemented to get better performance. + If provided, will check if attached input archive to checksum already exist, + not native to docker but implemented to get better performance. ## Callback parameters * `err` - Error object if any. -* `executed` - if command was executed + Error object if any. +* `status` + True if container was loaded. * `stdout` - Stdout value(s) unless `stdout` option is provided. + Stdout value(s) unless `stdout` option is provided. * `stderr` - Stderr value(s) unless `stderr` option is provided. + Stderr value(s) unless `stderr` option is provided. ## Example @@ -35,14 +35,8 @@ nikita.docker.load({ image: 'nikita/load_test:latest', machine: machine, source: source + "/nikita_load.tar" -}, function(err, loaded, stdout, stderr) { - if(err){ - console.log(err.message); - }else if(is_true){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } +}, function(err, status, stdout, stderr) { + console.log( err ? err.message : 'Container loaded: ' + status); }) ``` diff --git a/src/docker/login.coffee.md b/src/docker/login.coffee.md index a0ab97682..783229841 100644 --- a/src/docker/login.coffee.md +++ b/src/docker/login.coffee.md @@ -1,5 +1,5 @@ -# `nikita.docker.build(options, [callback])` +# `nikita.docker.login(options, [callback])` Register or log in to a Docker registry server. @@ -10,7 +10,7 @@ Register or log in to a Docker registry server. * `registry` (string) Address of the registry server. "https://index.docker.io/v1/" by default * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine + Name of the docker-machine, require if using docker-machine * `email` (string) Email * `user` (string) diff --git a/src/docker/logout.coffee.md b/src/docker/logout.coffee.md index 4f7188e5b..4f7cf3341 100644 --- a/src/docker/logout.coffee.md +++ b/src/docker/logout.coffee.md @@ -7,37 +7,31 @@ specified is the default. ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. + Whether to use boot2docker or not, default to false. * `registry` (string) - Address of the registry server. "https://index.docker.io/v1/" by default + Address of the registry server, default to "https://index.docker.io/v1/". * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine + Name of the docker-machine, required if using docker-machine. * `code` (int|array) - Expected code(s) returned by the command, int or array of int, default to 0. + Expected code(s) returned by the command, int or array of int, default to 0. * `code_skipped` Expected code(s) returned by the command if it has no effect, executed will - not be incremented, int or array of int. + not be incremented, int or array of int. ## Callback parameters * `err` Error object if any. -* `executed` - if command was executed +* `status` + True if logout. ## Example ```javascript nikita.docker.pause({ container: 'toto' -}, function(err, is_true){ - if(err){ - console.log(err.message); - }else if(is_true){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } +}, function(err, status){ + console.log( err ? err.message : 'Logout: ' + status); }) ``` diff --git a/src/docker/pause.coffee.md b/src/docker/pause.coffee.md index 024a3931f..14f1d6dda 100644 --- a/src/docker/pause.coffee.md +++ b/src/docker/pause.coffee.md @@ -8,35 +8,29 @@ Pause all processes within a container * `boot2docker` (boolean) Whether to use boot2docker or not, default to false. * `container` (string) - Name/ID of the container. __Mandatory__ + Name/ID of the container, required. * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine + Name of the docker-machine, required. * `code` (int|array) - Expected code(s) returned by the command, int or array of int, default to 0. + Expected code(s) returned by the command, int or array of int, default to 0. * `code_skipped` Expected code(s) returned by the command if it has no effect, executed will - not be incremented, int or array of int. + not be incremented, int or array of int. ## Callback parameters * `err` - Error object if any. -* `executed` - if command was executed + Error object if any. +* `status` + True if container was pulled. ## Example ```javascript nikita.docker.pause({ container: 'toto' -}, function(err, is_true){ - if(err){ - console.log(err.message); - }else if(is_true){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } +}, function(err, status){ + console.log( err ? err.message : 'Container paused: ' + status); }) ``` diff --git a/src/docker/pull.coffee.md b/src/docker/pull.coffee.md index fe653f8e7..64caf681c 100644 --- a/src/docker/pull.coffee.md +++ b/src/docker/pull.coffee.md @@ -17,13 +17,13 @@ Pull a container ## Callback parameters * `err` - Error object if any. -* `executed` - if command was executed + Error object if any. +* `status` + True if container was pulled. * `stdout` - Stdout value(s) unless `stdout` option is provided. + Stdout value(s) unless `stdout` option is provided. * `stderr` - Stderr value(s) unless `stderr` option is provided. + Stderr value(s) unless `stderr` option is provided. ## Example @@ -32,14 +32,8 @@ Pull a container ```javascript nikita.docker_pull({ tag: 'postgres' -}, function(err, is_true, stdout, stderr){ - if(err){ - console.log(err.message); - }else if(is_true){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } +}, function(err, status, stdout, stderr){ + console.log( err ? err.message : 'Container pulled: ' + status); }) ``` diff --git a/src/docker/restart.coffee.md b/src/docker/restart.coffee.md index 96eceafe3..6bb08dd2f 100644 --- a/src/docker/restart.coffee.md +++ b/src/docker/restart.coffee.md @@ -1,16 +1,16 @@ # `nikita.docker.start(options, [callback])` -Start stopped containers. Or stop/starts started container +Start stopped containers or restart (stop + starts) a started container. ## Options * `boot2docker` (boolean) Whether to use boot2docker or not, default to false. * `container` (string) - Name/ID of the container. __Mandatory__ + Name/ID of the container, required. * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine + Name of the docker-machine, required if using docker-machine * `timeout` (int) Seconds to wait for stop before killing it * `code` (int|array) @@ -23,22 +23,16 @@ Start stopped containers. Or stop/starts started container * `err` Error object if any. -* `executed` - if command was executed +* `status` + True if container was restarted. ## Example ```javascript nikita.docker.restart({ container: 'toto' -}, function(err, is_true){ - if(err){ - console.log(err.message); - }else if(is_true){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } +}, function(err, status){ + console.log( err ? err.message : 'Container restarted: ' + status); }) ``` diff --git a/src/docker/rm.coffee.md b/src/docker/rm.coffee.md index 1fb17f43a..066d545cc 100644 --- a/src/docker/rm.coffee.md +++ b/src/docker/rm.coffee.md @@ -7,27 +7,35 @@ force options is set. ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. + Whether to use boot2docker or not, default to false. * `container` (string) - Name/ID of the container. __Mandatory__ + Name/ID of the container, required. * `machine` (string) - Name of the docker-machine. __Mandatory__ if docker-machine installed + Name of the docker-machine, required if docker-machine installed. * `link` (boolean) - Remove the specified link + Remove the specified link. * `volumes` (boolean) - Remove the volumes associated with the container + Remove the volumes associated with the container. * `force` (boolean) - Force the removal of a running container (uses SIGKILL) + Force the removal of a running container (uses SIGKILL). ## Callback parameters * `err` - Error object if any. -* `executed` - if command was executed + Error object if any. +* `status` + True if container was removed. ## Example Code +```javascript +nikita.docker.rm({ + container: 'toto' +}, function(err, status){ + console.log( err ? err.message : 'Container removed: ' + status); +}) +``` + ## Source Code module.exports = (options, callback) -> diff --git a/src/docker/rmi.coffee.md b/src/docker/rmi.coffee.md index 85831054c..9664e0879 100644 --- a/src/docker/rmi.coffee.md +++ b/src/docker/rmi.coffee.md @@ -7,13 +7,20 @@ force options is set. ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. + Whether to use boot2docker or not, default to false. * `image` (string) - Name of the image. __Mandatory__ + Name of the image, required. * `machine` (string) - Name of the docker-machine. __Mandatory__ if docker-machine installed + Name of the docker-machine, required if docker-machine installed. * `no_prune` (boolean) - Do not delete untagged parents + Do not delete untagged parents. + +## Callback parameters + +* `err` + Error object if any. +* `status` + True if image was removed. ## Source Code diff --git a/src/docker/run.coffee.md b/src/docker/run.coffee.md index 961e8d7e5..8dbdd3f58 100644 --- a/src/docker/run.coffee.md +++ b/src/docker/run.coffee.md @@ -6,92 +6,92 @@ Run Docker Containers ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. + Whether to use boot2docker or not, default to false. * `container` (string) - Alias of name + Alias of name. * `name` (string) - Assign a name to the container to run. + Assign a name to the container to run. * `image` (string) - Name/ID of base image. __Mandatory__ + Name/ID of base image, required. * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine + Name of the docker-machine, required if using docker-machine. * `cmd` (string) - Overwrite the default ENTRYPOINT of the image - Equivalent to --entrypoint docker parameter + Overwrite the default ENTRYPOINT of the image, equivalent to + `--entrypoint docker parameter` * `hostname` (string) - Hostname in the docker container + Hostname in the docker container. * `port` ( 'int:int' | [] ) - port mapping + Port mapping. * `volume` ( 'path:path' | [] ) - path mapping + Path mapping. * `device` ('path' | [] ) - Send host device(s) to container + Send host device(s) to container. * `dns` (ip-address | [] ) - Set custom DNS server(s) + Set custom DNS server(s). * `dns_search` (ip-address | [] ) - Set custom DNS search domain(s) + Set custom DNS search domain(s). * `expose` ( int | string | [] ) - Export port(s) + Export port(s). * `link` ( containerName | containerID | [] ) - Link to other container(s) + Link to other container(s). * `label` (string | [] ) - Set meta data on a container + Set meta data on a container. * `label_file` (path) - Read in a line delimited file of labels + Read in a line delimited file of labels. * `add_host` ('host:ip' | [] ) - Add a custom host-to-IP mapping (host:ip) + Add a custom host-to-IP mapping (host:ip). * `cap_add` ( | [] ) - Add Linux Capabilities + Add Linux Capabilities. * `cap_drop` ( | [] ) - Drop Linux Capabilities + Drop Linux Capabilities. * `blkio_weight` (int) - Block IO (relative weight), between 10 and 1000 + Block IO (relative weight), between 10 and 1000. * `cgroup_parent` - Optional parent cgroup for the container + Optional parent cgroup for the container. * `cid_file` ( path ) - Write the container ID to the file + Write the container ID to the file. * `cpuset_cpus` (string) - CPUs in which to allow execution (ex: 0-3 0,1 ...) + CPUs in which to allow execution (ex: 0-3 0,1 ...). * `entrypoint` () - Overwrite the default ENTRYPOINT of the image + Overwrite the default ENTRYPOINT of the image. * `ipc` () - IPC namespace to use + IPC namespace to use. * `ulimit` ( | [] ) - Ulimit options + Ulimit options. * `volumes_from` (containerName | containerID | [] ) - Mount volumes from the specified container(s) + Mount volumes from the specified container(s). * `detach` (boolean) - if true, run container in background + if true, run container in background. * `env` ('VAR=value' | [] ) - Environment variables for the container. + Environment variables for the container.. * `env_file` ( path | [] ) - Read in a file of environment variables + Read in a file of environment variables. * `rm` (boolean) - delete the container when it ends. True by default + Delete the container when it ends. True by default. * `cwd` (path) - working directory of container + Working directory of container. * `net` (string) - Set the Network mode for the container + Set the Network mode for the container. * `pid` (string) - PID namespace to use + PID namespace to use. * `publish_all` (boolean) - Publish all exposed ports to random ports + Publish all exposed ports to random ports. * `code` (int|array) - Expected code(s) returned by the command, int or array of int, default to 0. + Expected code(s) returned by the command, int or array of int, default to 0.. * `code_skipped` - Expected code(s) returned by the command if it has no effect, executed will - not be incremented, int or array of int. + Expected code(s) returned by the command if it has no effect, executed will + not be incremented, int or array of int. ## Callback parameters * `err` - Error object if any. -* `executed` - if command was executed + Error object if any. +* `status` + True unless contaianer was already running. * `stdout` - Stdout value(s) unless `stdout` option is provided. + Stdout value(s) unless `stdout` option is provided. * `stderr` - Stderr value(s) unless `stderr` option is provided. + Stderr value(s) unless `stderr` option is provided. ## Example @@ -102,14 +102,8 @@ nikita.docker({ image: 'test-image' env: ["FOO=bar",] entrypoint: '/bin/true' -}, function(err, is_true, stdout, stderr){ - if(err){ - console.log(err.message); - }else if(is_true){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } +}, function(err, status, stdout, stderr){ + console.log( err ? err.message : 'Container state changed to running: ' + status); }) ``` diff --git a/src/docker/save.coffee.md b/src/docker/save.coffee.md index 360afd6eb..e894ca133 100644 --- a/src/docker/save.coffee.md +++ b/src/docker/save.coffee.md @@ -1,38 +1,38 @@ # `nikita.docker.save(options, [callback])` -Save Docker images +Save Docker images. ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. + Whether to use boot2docker or not, default to false. * `image` (string) - Name/ID of base image. __Mandatory__ + Name/ID of base image, required. * `tag` (string) - Tag of the image + Tag of the image. * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine -* `output` (string). __Mandatory__ - TAR archive output path -* `target` (string). __Mandatory__ - Shortcut for "output" option. + Name of the docker-machine, required if using docker-machine. +* `output` (string). + TAR archive output path, required. +* `target` (string). + Shortcut for "output" option, required. * `code` (int | array) - Expected code(s) returned by the command, int or array of int, default to 0. + Expected code(s) returned by the command, int or array of int, default to 0. * `code_skipped` - Expected code(s) returned by the command if it has no effect, executed will - not be incremented, int or array of int. + Expected code(s) returned by the command if it has no effect, executed will + not be incremented, int or array of int. ## Callback parameters * `err` - Error object if any. -* `executed` - if command was executed + Error object if any. +* `status` + True if container was saved. * `stdout` - Stdout value(s) unless `stdout` option is provided. + Stdout value(s) unless `stdout` option is provided. * `stderr` - Stderr value(s) unless `stderr` option is provided. + Stderr value(s) unless `stderr` option is provided. ## Example @@ -43,14 +43,8 @@ nikita.docker({ image: 'test-image' compression: 'gzip' entrypoint: '/bin/true' -}, function(err, is_true, stdout, stderr){ - if(err){ - console.log(err.message); - }else if(is_true){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } +}, function(err, status, stdout, stderr){ + console.log( err ? err.message : 'Container saved: ' + status); }) ``` diff --git a/src/docker/service.coffee.md b/src/docker/service.coffee.md index 65a1c7c6d..be69e59c4 100644 --- a/src/docker/service.coffee.md +++ b/src/docker/service.coffee.md @@ -3,6 +3,7 @@ Run a container in a service mode. This module is just a wrapper for docker.run with correct options. + Indeed, in a service mode, the container must be detached and NOT removed by default after execution. diff --git a/src/docker/start.coffee.md b/src/docker/start.coffee.md index f6db7102d..187c8ff87 100644 --- a/src/docker/start.coffee.md +++ b/src/docker/start.coffee.md @@ -1,34 +1,34 @@ # `nikita.docker.restart(options, [callback])` -Restart containers +Start a container. ## Options -* `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. -* `container` (string) - Name/ID of the container. __Mandatory__ -* `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine -* `attach` (boolean) - attach STDOUT/STDERR. False by default -* `code` (int|array) - Expected code(s) returned by the command, int or array of int, default to 0. -* `code_skipped` - Expected code(s) returned by the command if it has no effect, executed will - not be incremented, int or array of int. +* `boot2docker` (boolean) + Whether to use boot2docker or not, default to false. +* `container` (string) + Name/ID of the container, required. +* `machine` (string) + Name of the docker-machine, required if using docker-machine. +* `attach` (boolean) + attach STDOUT/STDERR, default to false. +* `code` (int|array) + Expected code(s) returned by the command, int or array of int, default to 0. +* `code_skipped` + Expected code(s) returned by the command if it has no effect, executed will + not be incremented, int or array of int. ## Callback parameters -* `err` - Error object if any. -* `executed` - if command was executed -* `stdout` - Stdout value(s) unless `stdout` option is provided. -* `stderr` - Stderr value(s) unless `stderr` option is provided. +* `err` + Error object if any. +* `status` + True unless container was already started. +* `stdout` + Stdout value(s) unless `stdout` option is provided. +* `stderr` + Stderr value(s) unless `stderr` option is provided. ## Example @@ -39,13 +39,7 @@ nikita.docker.start({ container: 'toto', attach: true }, function(err, is_true, stdout, stderr){ - if(err){ - console.log(err.message); - }else if(is_true){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } + console.log( err ? err.message : 'Container state changed to started: ' + status); }) ``` diff --git a/src/docker/status.coffee.md b/src/docker/status.coffee.md index f3a7ed26f..9de47a38d 100644 --- a/src/docker/status.coffee.md +++ b/src/docker/status.coffee.md @@ -6,22 +6,22 @@ Return true if container is running. This function is not native to docker. ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. -* `container` (string|array). __Mandatory__ - Name or Id of the container. + Whether to use boot2docker or not, default to false. +* `container` (string|array) + Name or Id of the container, required. * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine + Name of the docker-machine, required if using docker-machine. ## Callback parameters * `err` - Error object if any. -* `executed` - Wether the container is running or not. + Error object if any. +* `status` + True if container is running. * `stdout` - Stdout value(s) unless `stdout` option is provided. + Stdout value(s) unless `stdout` option is provided. * `stderr` - Stderr value(s) unless `stderr` option is provided. + Stderr value(s) unless `stderr` option is provided. ## Example @@ -32,14 +32,8 @@ nikita.docker({ image: 'test-image' compression: 'gzip' entrypoint: '/bin/true' -}, function(err, is_true, stdout, stderr){ - if(err){ - console.log(err.message); - }else if(is_true){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } +}, function(err, status, stdout, stderr){ + console.log( err ? err.message : 'Container running: ' + status); }) ``` diff --git a/src/docker/stop.coffee.md b/src/docker/stop.coffee.md index 004f32c71..9b91e0ca8 100644 --- a/src/docker/stop.coffee.md +++ b/src/docker/stop.coffee.md @@ -1,25 +1,25 @@ # `nikita.docker.stop(options, [callback])` -Stop started containers +Stop a started container. ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. + Whether to use boot2docker or not, default to false. * `container` (string) - Name/ID of the container. __Mandatory__ + Name/ID of the container, required. * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine + Name of the docker-machine, required if using docker-machine. * `timeout` (int) - Seconds to wait for stop before killing it + Seconds to wait for stop before killing it ## Callback parameters * `err` - Error object if any. -* `executed` - Wether the container was stoped or not. + Error object if any. +* `status` + True unless container was already stopped. ## Example @@ -27,13 +27,7 @@ Stop started containers nikita.docker.stop({ container: 'toto' }, function(err, is_true){ - if(err){ - console.log(err.message); - }else if(is_true){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } + console.log( err ? err.message : 'Container state changed to stopped: ' + status); }) ``` diff --git a/src/docker/unpause.coffee.md b/src/docker/unpause.coffee.md index 34da0f0ef..cacfda63e 100644 --- a/src/docker/unpause.coffee.md +++ b/src/docker/unpause.coffee.md @@ -1,23 +1,23 @@ # `nikita.docker.unpause(options, [callback])` -Unpause all processes within a container +Unpause all processes within a container. ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. + Whether to use boot2docker or not, default to false. * `container` (string) - Name/ID of the container. __Mandatory__ + Name/ID of the container, required. * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine + Name of the docker-machine, required if using docker-machine. ## Callback parameters * `err` - Error object if any. -* `executed` - if command was executed + Error object if any. +* `status` + True if container was unpaused. ## Example @@ -25,13 +25,7 @@ Unpause all processes within a container nikita.docker.pause({ container: 'toto' }, function(err, is_true){ - if(err){ - console.log(err.message); - }else if(is_true){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } + console.log( err ? err.message : 'Container was unpaused: ' + status); }) ``` diff --git a/src/docker/volume_create.coffee.md b/src/docker/volume_create.coffee.md index b7f5f0a77..ac360141d 100644 --- a/src/docker/volume_create.coffee.md +++ b/src/docker/volume_create.coffee.md @@ -6,25 +6,32 @@ Create a volume. ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. + Whether to use boot2docker or not, default to false. * `driver` (string) - Specify volume driver name. + Specify volume driver name. * `label` (string|array) - Set metadata for a volume. + Set metadata for a volume. * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine + Name of the docker-machine, required if using docker-machine. * `name` (string) - Specify volume name. + Specify volume name. * `opt` (string|array) Set driver specific options. +## Callback parameters + +* `err` + Error object if any. +* `status` + True is volume was created. + ## Example ```javascript nikita.docker.pause({ name: 'my_volume' }, function(err, created){ - console.log(err or 'Status: '+created); + console.log( err ? err.message : 'Volume created: ' + status); }) ``` diff --git a/src/docker/volume_rm.coffee.md b/src/docker/volume_rm.coffee.md index c835c0a23..302ab9825 100644 --- a/src/docker/volume_rm.coffee.md +++ b/src/docker/volume_rm.coffee.md @@ -6,21 +6,28 @@ Remove a volume. ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. -* `container` (string|array). __Mandatory__ - Name or Id of the container. + Whether to use boot2docker or not, default to false. +* `container` (string|array). + Name or Id of the container, required. * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine. + Name of the docker-machine, required if using docker-machine. * `name` (string) - Specify volume name. + Specify volume name. + +## Callback parameters + +* `err` + Error object if any. +* `status` + True is volume was removed. ## Example ```javascript nikita.docker.volume_rm({ name: 'my_volume' -}, function(err, removed){ - console.log(err or 'Status'+removed); +}, function(err, status){ + console.log( err ? err.message : 'Volume removed: ' + status); }) ``` diff --git a/src/docker/wait.coffee.md b/src/docker/wait.coffee.md index 27fb20243..c3c01de3c 100644 --- a/src/docker/wait.coffee.md +++ b/src/docker/wait.coffee.md @@ -1,28 +1,28 @@ # `nikita.docker.wait(options, [callback])` -Block until a container stops +Block until a container stops. ## Options * `boot2docker` (boolean) - Whether to use boot2docker or not, default to false. + Whether to use boot2docker or not, default to false. * `container` (string) - Name/ID of the container. __Mandatory__ + Name/ID of the container, optional. * `machine` (string) - Name of the docker-machine. __Mandatory__ if using docker-machine + Name of the docker-machine, optional if using docker-machine. * `code` (int|array) - Expected code(s) returned by the command, int or array of int, default to 0. + Expected code(s) returned by the command, int or array of int, default to 0. * `code_skipped` Expected code(s) returned by the command if it has no effect, executed will - not be incremented, int or array of int. + not be incremented, int or array of int. ## Callback parameters * `err` Error object if any. -* `executed` - if command was executed +* `status` + True unless container was already stopped. ## Example @@ -30,13 +30,7 @@ Block until a container stops nikita.docker.wait({ container: 'toto' }, function(err, is_true){ - if(err){ - console.log(err.message); - }else if(is_true){ - console.log('OK!'); - }else{ - console.log('Ooops!'); - } + console.log( err ? err.message : 'Volume removed: ' + status); }) ``` diff --git a/src/misc/docker.coffee.md b/src/misc/docker.coffee.md index 66c5b089e..353af13e2 100644 --- a/src/misc/docker.coffee.md +++ b/src/misc/docker.coffee.md @@ -58,5 +58,6 @@ eval $docker #{docker.opts} #{cmd} """ # Reformat error message if any + # TODO: rename this function as format_error module.exports.callback = (err, executed, stdout, stderr) -> throw Error stderr.trim().replace 'Error response from daemon: ', '' if err and /^Error response from daemon/.test stderr