This module implements an Docker Engine client based on Docker Remotet API. It's asynchronous (non-blocking) that it can be used to write web services for deploying swarm cluster and containers automatically on cloud environment. Of course, it can also be used to write any local deployment tools.

Docker cli vs asyncdocker

The docker cli example:

export DOCKER_HOST=127.0.0.1:2375
docker create --name hello --hostname 192.168.0.1 \
              ubuntu:14.04 /bin/bash -c 'echo hello'
docker start hello

And the equivalent asyncdocker example:

import asyncdocker, asyncdispatch, json

proc main() {.async.} =
  var docker = newAsyncDocker("127.0.0.1", Port(2375))
  var ret = await docker.create(image = "ubuntu:14.04",
                                name = "hello",
                                hostname = "192.168.0.1",
                                cmd = @["/bin/bash", "-c", "echo", "hello"])
  echo "Container Id: ", ret["Id"].getStr()
  await docker.start(name = "hello")
  docker.close()

waitFor main()

Simulate pull image

This example simulates the docker cli docker pull ubuntu:14.10 to download the image and print progress bars:

import asyncdocker, asyncdispatch, json

const
  hostname = "127.0.0.1"
  port = Port(2375)

proc pullCb(state: JsonNode): Future[bool] {.async.} =
  if state.hasKey("progress"):
    let current = state["progressDetail"]["current"].getNum()
    let total = state["progressDetail"]["total"].getNum()
    stdout.write("\r")
    stdout.write(state["id"].getStr())
    stdout.write(": ")
    stdout.write(state["status"].getStr())
    stdout.write(" ")
    stdout.write($current & "/" & $total)
    stdout.write(" ")
    stdout.write(state["progress"].getStr())
    if current == total:
      stdout.write("\n")
    stdout.flushFile()
  else:
    if state.hasKey("id"):
      stdout.write(state["id"].getStr())
      stdout.write(": ")
      stdout.write(state["status"].getStr())
      stdout.write("\n")
    else:
      stdout.write(state["status"].getStr())
      stdout.write("\n")

proc main() {.async.} =
  var docker = newAsyncDocker(hostname, port)
  await docker.pull(fromImage = "ubuntu", tag = "14.04", cb = pullCb)
  docker.close()

waitFor main()

output:

14.04: Pulling from library/ubuntu
b0efe5c05b4c: Pulling fs layer
0a1f1b169319: Pulling fs layer
1ceb0a3c7c48: Pulling fs layer
a3ed95caeb02: Pulling fs layer
a3ed95caeb02: Waiting
1ceb0a3c7c48: Downloading 682/682 [==================================================>]    682 B/682 B
1ceb0a3c7c48: Verifying Checksum
1ceb0a3c7c48: Download complete
a3ed95caeb02: Downloading 32/32 [==================================================>]     32 B/32 BB/77.8 kB
a3ed95caeb02: Verifying Checksum
a3ed95caeb02: Download complete
0a1f1b169319: Downloading 77797/77797 [==================================================>]  77.8 kB/77.8 kB
0a1f1b169319: Verifying Checksum
0a1f1b169319: Download complete
b0efe5c05b4c: Downloading 4848810/68321236 [===>                                               ] 4.849 MB/68.32 MB

Web service

You can write a web service with asynchttpserver:

import asyncdocker, asyncdispatch, asynchttpserver, json

var server = newAsyncHttpServer()

proc cb(req: Request) {.async.} =
  var docker = newAsyncDocker("127.0.0.1", Port(2375))
  var pass = true
  try:
    var ret = await docker.create(image = "ubuntu:14.04",
                                  name = "hello",
                                  hostname = "192.168.0.1",
                                  cmd = @["/bin/bash", "-c", "echo", "hello"])
    echo "Container Id: ", ret["Id"].getStr()
    await docker.start(name = "hello")
    await req.respond(Http201, "OK")
  except:
    pass = false
  if not pass:
    await req.respond(Http500, "Failure")
  docker.close()

waitFor server.serve(Port(8080), cb)

or with jester:

import asyncdocker, asyncdispatch, asynchttpserver, json, jester

routes:
  post "/containers/@name/run"
    var docker = newAsyncDocker("127.0.0.1", Port(2375))
    var pass = true
    try:
      var ret = await docker.create(image = "ubuntu:14.04",
                                    name = @"name",
                                    hostname = "192.168.0.1",
                                    cmd = @["/bin/bash", "-c", "echo", "hello"])
      echo "Container Id: ", ret["Id"].getStr()
      await docker.start(name = "hello")
      await req.respond(Http201, "OK")
    except:
      pass = false
    if not pass:
      await req.respond(Http500, "Failure")
    docker.close()

Stream support

Supports to stream responses from the docker daemon with attach, logs, execStart, etc. For example:

docker logs --follow hello

proc logsCb(): VndCallback =
  var i = 0
  proc cb(vnd: VndKind, data: string): Future[bool] {.async.} =
    if vnd == vndStdout:
      stdout.write("stdout: " & data)
    if vnd == vndStderr:
      stderr.write("stderr: " & data)
    echo i
    if i == 5:
     result = true ##   Close socket to stop receiving logs.
    inc(i)
  result = cb

await docker.logs("hello", follow = true, cb = logsCb())

Tls verify

Supports --tls and --tlsverify to protect docker daemon socket.

This requires the OpenSSL library, fortunately it's widely used and installed on many operating systems. Client will use SSL automatically if you give any of the functions a url with the https schema, for example: https://github.com/, you also have to compile with ssl defined like so: nim c -d:ssl ....

For --tls verification:

docker --host 127.0.0.1:2376 --tls --tlskey /home/docker/.docker/key.pem --tlscert /home/docker/.docker/cert.pem ps

equivalent to:

import asyncdocker, asyncdispatch, json, openssl

const: key = "/home/docker/.docker/key.pem" cert = "/home/docker/.docker/cert.pem"
proc main() {.async.}: var docker = newAsyncDocker("127.0.0.1", Port(2376), nil, key, cert, CVerifyNone) var containers = await docker.ps()

waitFor main()

For --tlsverify verification:

docker --host 127.0.0.1:2376 --tlsverify --tlscacert /home/docker/.docker/ca.pem --tlskey /home/docker/.docker/key.pem --tlscert /home/docker/.docker/cert.pem ps

equivalent to:

import asyncdocker, asyncdispatch, json, openssl

const: cacert = "/home/docker/.docker/ca.pem" key = "/home/docker/.docker/key.pem" cert = "/home/docker/.docker/cert.pem"
proc main() {.async.}: var docker = newAsyncDocker("127.0.0.1", Port(2376), cacert, key, cert, CVerifyPeer) var containers = await docker.ps()

waitFor main()

Swarm cluster support

The Docker Swarm API is mostly compatible with the Docker Remote API. see Docker Swarm Reference

Imports

asyncdispatch, asynchttpclient, strutils, json, strtabs, uri, net, math, nre, base64

Types

AsyncDocker = ref object scheme: string hostname: string port: string httpclient: AsyncHttpClient: Asynchronous docker client. Source
ContainerStatus = enum statCreated, statRestarting, statRunning, statPaused, statExited: Enumeration of all container status. Source
RestartPolicy = enum rpNo = "no", rpOnFailure = "on-failure", rpAlways = "always", rpUnlessStopped = "unless-stopped": Enumeration of all restart policy for container. Source
LogType = enum logNone = "none", logJsonFile = "json-file", logJournald = "journald", logGelf = "gelf", logAwslogs = "awslogs", logSplunk = "splunk": Enumeration of all available log driver. Source
DockerError = object of IOError: Requesting to docker daemon has an error. Source
NotModifiedError = object of DockerError: Not modified from docker daemon, response status code is 304. Source
BadParameterError = object of DockerError: Bad parameter from docker daemon, response status code is 400. Source
ForbiddenError = object of DockerError: Forbidden from docker daemon, response status code is 403. Source
NotFoundError = object of DockerError: Not found from docker daemon, response status code is 404. Source
NotAcceptableError = object of DockerError: Not acceptable from docker daemon, response status code is 406. Source
ConflictError = object of DockerError: Conflict from docker daemon, response status code is 409. Source
ServerError = object of DockerError: Server error from docker daemon, response status code is 500. Source
VndKind = enum vndStdin, vndStdout, vndStderr: Source
VndCallback = proc (vnd: VndKind; data: string): Future[bool]: Source
JsonCallback = proc (data: JsonNode): Future[bool]: Source

Consts

dockerVersion = "1.23": Source
userAgent = "Nim Docker client/0.0.1 (1.23)": Source

Procs

proc newAsyncDocker(hostname: string; port: Port): AsyncDocker {.raises: [], tags: [].}

Creates a new AsyncDocker instance. Source

proc close(c: AsyncDocker) {.raises: [SslError, OSError], tags: [].}

Closes the socket resource used by c. Source

proc ps(c: AsyncDocker; all = false; size = false; limit = - 1; since = ""; before = ""; exitedFilters: seq[int] = nil; statusFilters: seq[ContainerStatus] = nil; labelFilters: seq[string] = nil): Future[JsonNode] {.raises: [FutureError], tags: [RootEffect, ReadIOEffect].}

List containers. see Docker Reference

FutureError represents an exception, it may be BadParameterError, ServerError or DockerError.

Request parameters:

all - Show all containers. Only running containers are shown by default (i.e., this defaults to false).
size - Show the containers sizes.
limit - Show limit last created containers, include non-running ones.
since - Show only containers created since Id, include non-running ones.
before - Show only containers created before Id, include non-running ones.
exitedFilters - Filter containers with exit code.
statusFilters - Filter containers with status. Available status: created | restarting | running | paused | exited.
labelFilters - Filter containers with label.

Result is a JSON object, the internal members of which depends on the version of your docker engine. For example:

[
  {
    "Id": "8dfafdbc3a40",
    "Names":["/boring_feynman"],
    "Image": "ubuntu:latest",
    "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
    "Command": "echo 1",
    "Created": 1367854155,
    "Status": "Exit 0",
    "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}],
    "Labels": {
      "com.example.vendor": "Acme",
      "com.example.license": "GPL",
      "com.example.version": "1.0"
    },
    "SizeRw": 12288,
    "SizeRootFs": 0
  },
  {
    "Id": "9cd87474be90",
    "Names":["/coolName"],
    "Image": "ubuntu:latest",
    "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
    "Command": "echo 222222",
    "Created": 1367854155,
    "Status": "Exit 0",
    "Ports": [],
    "Labels": {},
    "SizeRw": 12288,
    "SizeRootFs": 0
  },
  {
    "Id": "3176a2479c92",
    "Names":["/sleepy_dog"],
    "Image": "ubuntu:latest",
    "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
    "Command": "echo 3333333333333333",
    "Created": 1367854154,
    "Status": "Exit 0",
    "Ports":[],
    "Labels": {},
    "SizeRw":12288,
    "SizeRootFs":0
  },
  {
    "Id": "4cb07b47f9fb",
    "Names":["/running_cat"],
    "Image": "ubuntu:latest",
    "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
    "Command": "echo 444444444444444444444444444444444",
    "Created": 1367854152,
    "Status": "Exit 0",
    "Ports": [],
    "Labels": {},
    "SizeRw": 12288,
    "SizeRootFs": 0
  }
]

If you access the docker swarm api, the result will has new field Node added:

"Node": {
  "Id": "ODAI:IC6Q:MSBL:TPB5:HIEE:6IKC:VCAM:QRNH:PRGX:ERZT:OK46:PMFX",
  "Ip": "0.0.0.0",
  "Addr": "http://0.0.0.0:4243",
  "Name": "vagrant-ubuntu-saucy-64",
},

see Docker Reference of Swarm API

Source

proc create(c: AsyncDocker; image: string; cmd, entrypoint: seq[string] = nil; name, hostname, domainname, user = ""; attachStdin, attachStdout, attachStderr = true; tty, openStdin, stdinOnce = false; labels: seq[tuple[key, value: string]] = nil; workingDir, macAddress = ""; stopSignal = "SIGTERM"; networkDisabled = false; env, exposedPorts, volumes, binds, links: seq[string] = nil; memory, memorySwap, memoryReservation, kernelMemory = 0; memorySwappiness = - 1; cpuShares, cpuPeriod, cpuQuota = 0; cpusetCpus, cpusetMems = ""; blkioWeight = 0; blkioWeightDevice: seq[tuple[path: string, weight: int]] = nil; blkioDeviceReadBps: seq[tuple[path: string, rate: int]] = nil; blkioDeviceWriteBps: seq[tuple[path: string, rate: int]] = nil; blkioDeviceReadIOps: seq[tuple[path: string, rate: int]] = nil; blkioDeviceWriteIOps: seq[tuple[path: string, rate: int]] = nil; oomKillDisable = false; oomScoreAdj = 0; networkMode = "bridge"; portBindings: seq[tuple[port: string, hostPort: seq[string]]] = nil; publishAllPorts, privileged, readonlyRootfs = false; dns, dnsOptions, dnsSearch: seq[string] = nil; extraHosts, volumesFrom, capAdd, capDrop: seq[string] = nil; restartPolicy: tuple[ name: RestartPolicy, maximumRetryCount: int] = (rpNo, 0); securityOpt: seq[string] = nil; cgroupParent, volumeDriver = ""; shmSize = 0; ulimits: seq[tuple[name: string, soft: int, hard: int]] = nil; devices: seq[ tuple[pathOnHost, pathInContainer, cgroupPermissions: string]] = nil; logConfig: tuple[ typ: LogType, config: seq[tuple[key, value: string]]] = (logJsonFile, nil)): Future[ JsonNode] {.raises: [FutureError], tags: [RootEffect, ReadIOEffect].}

Create a container. see Docker Reference

FutureError represents an exception, it may be NotFoundError, NotAcceptableError, ServerError or DockerError.

Request parameters:

image - A string specifying the image name to use for the container.
cmd - Command to run specified as a string or an array of strings.
name - Assign the specified name or id to the container. Must match /?[a-zA-Z0-9_-]+.
hostname - A string value containing the hostname to use for the container.
domainname - A string value containing the domain name to use for the container.
user - A string value specifying the user inside the container.
attachStdin - Boolean value, attaches to stdin.
attachStdout - Boolean value, attaches to stdout.
attachStderr - Boolean value, attaches to stderr.
tty - Boolean value, Attach standard streams to a tty, including stdin if it is not closed.
openStdin - Boolean value, opens stdin.
stdinOnce - Boolean value, close stdin after the 1 attached client disconnects.
env - A list of environment variables in the form of @["VAR=value","VAR2=value2"].
entrypoint - Set the entry point for the container.
labels - Adds a map of labels to a container. To specify a map: {"key":"value", "key2":"value2"}.
workingDir - A string specifying the working directory for commands to run in.
stopSignal - Signal to stop a container as a string or unsigned integer. SIGTERM by default.
networkDisabled - Boolean value, when true disables networking for the container.
exposedPorts - Mapping ports in the form of: "@["<port>/<tcp|udp>"].
volumes - A list of volume that you want mount for this container.
binds - A list of volume bindings for this container. Each volume binding is a string in one of these forms:
- container_path to create a new volume for the container.
- host_path:container_path to bind-mount a host path into the container.
- host_path:container_path:ro to make the bind-mount read-only inside the container.
links - A list of links for the container. Each link entry should be in the form of container_name:alias.
memory - Memory limit in bytes.
memorySwap - Total memory limit (memory + swap); set -1 to disable swap. You must use this with Memory and make the swap value larger than Memory.
memoryReservation - Memory soft limit in bytes.
kernelMemory - Kernel memory limit in bytes.
cpuShares - An integer value containing the container’s CPU Shares (ie. the relative weight vs other containers).
cpuPeriod - The length of a CPU period in microseconds.
cpuQuota - Microseconds of CPU time that the container can get in a CPU period.
cpuset - Deprecated please don’t use. Use CpusetCpus instead.
cpusetCpus - String value containing the cgroups CpusetCpus to use.
cpusetMems - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.
blkioWeight - Block IO weight (relative weight) accepts a weight value between 10 and 1000.
memorySwappiness - Tune a container’s memory swappiness behavior. Accepts an integer between 0 and 100.
blkioWeightDevice - Block IO weight (relative device weight) in the form of: @[("Path": "device_path", "Weight": weight)].
blkioDeviceReadBps - Limit read rate (bytes per second) from a device in the form of: @[("Path": "device_path", "Rate": rate)].
blkioDeviceWriteBps - Limit write rate (bytes per second) to a device in the form of: @[("Path": "device_path", "Rate": rate)].
blkioDeviceReadIOps - Limit read rate (IO per second) from a device in the form of: @[("Path": "device_path", "Rate": rate)].
blkioDeviceWriteIOps - Limit write rate (IO per second) to a device in the form of: @[("Path": "device_path", "Rate": rate)].
oomKillDisable - Boolean value, whether to disable OOM Killer for the container or not.
OomScoreAdj - An integer value containing the score given to the container in order to tune OOM killer preferences.
networkMode - Sets the networking mode for the container. Supported values are: bridge, host, and container:<name|id>.
portBindings - A map of exposed container ports.
publishAllPorts - Allocates a random host port for all of a container’s exposed ports.Specified as a boolean value.
privileged - Gives the container full access to the host. Specified as a boolean value.
readonlyRootfs - Mount the container’s root filesystem as read only. Specified as a boolean value.
dns - A list of DNS servers for the container to use.
dnsOptions - A list of DNS options.
dnsSearch - A list of DNS search domains
extraHosts - A list of hostnames/IP mappings to add to the container’s /etc/hosts file. Specified in the form ["hostname:IP"].
volumesFrom - A list of volumes to inherit from another container. Specified in the form <container name>[:<ro|rw>].
capAdd - A list of kernel capabilities to add to the container.
capdrop - A list of kernel capabilities to drop from the container.
restartPolicy - The behavior to apply when the container exits. The value is an object with a Name property of either "always" to always restart, "unless-stopped" to restart always except when user has manually stopped the container or "on-failure" to restart only when the container exit code is non-zero. If on-failure is used, MaximumRetryCount controls the number of times to retry before giving up. The default is not to restart. (optional) An ever increasingdelay (double the previous delay, starting at 100mS) is added before each restart to prevent flooding the server.
securityOpt - A list of string values to customize labels for MLS systems, such as SELinux.
cgroupParent - Path to cgroups under which the container’s cgroup is created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups are created if they do not already exist.
volumeDriver - Driver that this container users to mount volumes.
ShmSize - Size of /dev/shm in bytes. The size must be greater than 0. If omitted the system uses 64MB.
ulimits - A list of ulimits to set in the container, specified as ( "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> ).
devices - A list of devices to add to the container specified in the form ( "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw").
logConfig - Log configuration for the container, specified in the form ( "Type": "<driver_name>", "Config": {"key1": "val1"}). Available types: json-file, syslog, journald, gelf, awslogs, none. json-file logging driver.

Result is a JSON object, the internal members of which depends on the version of your docker engine. For example:

{
  "Id":"e90e34656806",
  "Warnings":[]
}

Note: the official documentation of Mounts is invalid. Use Volumes or Binds to mount for your container. For example:

var ret = await docker.create(image = "ubuntu:14.10",
                              cmd = @["/bin/bash", "-c", "echo", "hello"],
                              exposedPorts = @["22/tcp"],
                              volumes = @["/tmp", "/data"],
                              portBindings = @[("5000", @["5000"])])
echo "Container Id: ", ret["Id"].getStr()

equivalent to:

docker create --expose 22/tcp \
              --volumes /tmp --volumes /store \
              --publish 5000:5000 \
              ubuntu:14.10 /bin/bash -c 'echo hello'

In the above example, docker engine will copy files from /tmp and /data to container volumes.

But following example does not copy (just mounting):

var ret = await docker.create(image = "ubuntu:14.10",
                              cmd = @["/bin/bash", "-c", "echo", "hello"],
                              exposedPorts = @["22/tcp"],
                              binds = @["/tmp:/tmp:ro", "/store:/data:rw"],
                              portBindings = @[("5000", @["5000"])])
echo "Container Id: ", ret["Id"].getStr()

equivalent to:

docker create --expose 22/tcp \
              --volumes /tmp:/tmp:ro --volumes /store:/data:rw \
              --publish 5000:5000 \
              ubuntu:14.10 /bin/bash -c 'echo hello'

Module asyncdocker