Using the Docker REST API to run a container with parameters

Question

I'm using the Docker Engine API and I would like to be able to mimic a docker run .

I see in this link some notes about this, but no concrete example on how to pass parameters. For instance, how can I reproduce the following

docker run -d -p 27017:27017 -p 28017:28017 tutum/mongodb

using the REST API?

Answer 1

One hacky way to find that out is to run strace on the command itself:

$ sudo strace -e write \
              -o /tmp/docker.strace \
              -s 10000 \
              -f docker run -d -p 27017:27017 -p 28017:28017 tutum/mongodb

In the file /tmp/docker.strace , you will see:

10911 write(3, "POST /v1.25/containers/create HTTP/1.1\r\nHost: docker\r\nUser-Agent: Docker-Client/1.13.0 (linux)\r\nContent-Length: 1551\r\nContent-Type: application/json\r\n\r\n{\"Hostname\":\"\",\"Domainname\":\"\",\"User\":\"\",\"AttachStdin\":false,\"AttachStdout\":false,\"AttachStderr\":false,\"ExposedPorts\":{\"27017/tcp\":{},\"28017/tcp\":{}},\"Tty\":false,\"OpenStdin\":false,\"StdinOnce\":false,\"Env\":[],\"Cmd\":null,\"Image\":\"tutum/mongodb\",\"Volumes\":{},\"WorkingDir\":\"\",\"Entrypoint\":null,\"OnBuild\":null,\"Labels\":{},\"HostConfig\":{\"Binds\":null,\"ContainerIDFile\":\"\",\"LogConfig\":{\"Type\":\"\",\"Config\":{}},\"NetworkMode\":\"default\",\"PortBindings\":{\"27017/tcp\":[{\"HostIp\":\"\",\"HostPort\":\"27017\"}],\"28017/tcp\":[{\"HostIp\":\"\",\"HostPort\":\"28017\"}]},\"RestartPolicy\":{\"Name\":\"no\",\"MaximumRetryCount\":0},\"AutoRemove\":false,\"VolumeDriver\":\"\",\"VolumesFrom\":null,\"CapAdd\":null,\"CapDrop\":null,\"Dns\":[],\"DnsOptions\":[],\"DnsSearch\":[],\"ExtraHosts\":null,\"GroupAdd\":null,\"IpcMode\":\"\",\"Cgroup\":\"\",\"Links\":null,\"OomScoreAdj\":0,\"PidMode\":\"\",\"Privileged\":false,\"PublishAllPorts\":false,\"ReadonlyRootfs\":false,\"SecurityOpt\":null,\"UTSMode\":\"\",\"UsernsMode\":\"\",\"ShmSize\":0,\"ConsoleSize\":[0,0],\"Isolation\":\"\",\"CpuShares\":0,\"Memory\":0,\"NanoCpus\":0,\"CgroupParent\":\"\",\"BlkioWeight\":0,\"BlkioWeightDevice\":null,\"BlkioDeviceReadBps\":null,\"BlkioDeviceWriteBps\":null,\"BlkioDeviceReadIOps\":null,\"BlkioDeviceWriteIOps\":null,\"CpuPeriod\":0,\"CpuQuota\":0,\"CpuRealtimePeriod\":0,\"CpuRealtimeRuntime\":0,\"CpusetCpus\":\"\",\"CpusetMems\":\"\",\"Devices\":[],\"DiskQuota\":0,\"KernelMemory\":0,\"MemoryReservation\":0,\"MemorySwap\":0,\"MemorySwappiness\":-1,\"OomKillDisable\":false,\"PidsLimit\":0,\"Ulimits\":null,\"CpuCount\":0,\"CpuPercent\":0,\"IOMaximumIOps\":0,\"IOMaximumBandwidth\":0},\"NetworkingConfig\":{\"EndpointsConfig\":{}}}\n", 1703) = 1703
...
10914 write(5, "POST /v1.25/containers/42844726d8bd925d9903a0922f380c295dd398475b779d7ae2099ec2b4ab494e/start HTTP/1.1\r\nHost: docker\r\nUser-Agent: Docker-Client/1.13.0 (linux)\r\nContent-Length: 0\r\nContent-Type: text/plain\r\n\r\n", 207) = 207

The first POST request (for container creation), in a pretty form is:

POST /v1.25/containers/create HTTP/1.1
Host: docker
User-Agent: Docker-Client/1.13.0 (linux)
Content-Length: 1551
Content-Type: application/json

{
  "Hostname": "",
  "Domainname": "",
  "User": "",
  "AttachStdin": false,
  "AttachStdout": false,
  "AttachStderr": false,
  "ExposedPorts": {
    "27017/tcp": {},
    "28017/tcp": {}
  },
  "Tty": false,
  "OpenStdin": false,
  "StdinOnce": false,
  "Env": [],
  "Cmd": null,
  "Image": "tutum/mongodb",
  "Volumes": {},
  "WorkingDir": "",
  "Entrypoint": null,
  "OnBuild": null,
  "Labels": {},
  "HostConfig": {
    "Binds": null,
    "ContainerIDFile": "",
    "LogConfig": {
      "Type": "",
      "Config": {}
    },
    "NetworkMode": "default",
    "PortBindings": {
      "27017/tcp": [
        {
          "HostIp": "",
          "HostPort": "27017"
        }
      ],
      "28017/tcp": [
        {
          "HostIp": "",
          "HostPort": "28017"
        }
      ]
    },
    "RestartPolicy": {
      "Name": "no",
      "MaximumRetryCount": 0
    },
    "AutoRemove": false,
    "VolumeDriver": "",
    "VolumesFrom": null,
    "CapAdd": null,
    "CapDrop": null,
    "Dns": [],
    "DnsOptions": [],
    "DnsSearch": [],
    "ExtraHosts": null,
    "GroupAdd": null,
    "IpcMode": "",
    "Cgroup": "",
    "Links": null,
    "OomScoreAdj": 0,
    "PidMode": "",
    "Privileged": false,
    "PublishAllPorts": false,
    "ReadonlyRootfs": false,
    "SecurityOpt": null,
    "UTSMode": "",
    "UsernsMode": "",
    "ShmSize": 0,
    "ConsoleSize": [
      0,
      0
    ],
    "Isolation": "",
    "CpuShares": 0,
    "Memory": 0,
    "NanoCpus": 0,
    "CgroupParent": "",
    "BlkioWeight": 0,
    "BlkioWeightDevice": null,
    "BlkioDeviceReadBps": null,
    "BlkioDeviceWriteBps": null,
    "BlkioDeviceReadIOps": null,
    "BlkioDeviceWriteIOps": null,
    "CpuPeriod": 0,
    "CpuQuota": 0,
    "CpuRealtimePeriod": 0,
    "CpuRealtimeRuntime": 0,
    "CpusetCpus": "",
    "CpusetMems": "",
    "Devices": [],
    "DiskQuota": 0,
    "KernelMemory": 0,
    "MemoryReservation": 0,
    "MemorySwap": 0,
    "MemorySwappiness": -1,
    "OomKillDisable": false,
    "PidsLimit": 0,
    "Ulimits": null,
    "CpuCount": 0,
    "CpuPercent": 0,
    "IOMaximumIOps": 0,
    "IOMaximumBandwidth": 0
  },
  "NetworkingConfig": {
    "EndpointsConfig": {}
  }
}

Now, there are a lot of defaults present. Let's prune them out, and create a minimum set, which, in this case, is:

{
  "ExposedPorts": {
    "27017/tcp": {},
    "28017/tcp": {}
  },
  "Image": "tutum/mongodb",
  "HostConfig": {
    "PortBindings": {
      "27017/tcp": [
        {
          "HostIp": "",
          "HostPort": "27017"
        }
      ],
      "28017/tcp": [
        {
          "HostIp": "",
          "HostPort": "28017"
        }
      ]
    }
  }
}

Now, lets try creating the container and starting it using the REST API ourselves.

$ sudo curl -v -H "Content-Type: application/json" -d '{"ExposedPorts":{"27017/tcp":{},"28017/tcp":{}},"Image":"tutum/mongodb","HostConfig":{"PortBindings":{"27017/tcp":[{"HostIp":"","HostPort":
"27017"}],"28017/tcp":[{"HostIp":"","HostPort":"28017"}]}}}' --unix-socket /var/run/docker.sock http://docker/containers/create                                                                                    
*   Trying /var/run/docker.sock...
* Connected to docker (/var/run/docker.sock) port 80 (#0)
> POST /containers/create HTTP/1.1
> Host: docker
> User-Agent: curl/7.50.3
> Accept: */*
> Content-Type: application/json
> Content-Length: 198
> 
* upload completely sent off: 198 out of 198 bytes
< HTTP/1.1 201 Created
< Api-Version: 1.25
< Content-Type: application/json
< Docker-Experimental: false
< Server: Docker/1.13.0 (linux)
< Date: Tue, 31 Jan 2017 05:03:34 GMT
< Content-Length: 90
< 
{"Id":"be10c2bb8f07e36717a10cdf102a304aaf2ee072661df0265e322bdeb5fc1d78","Warnings":null}
* Curl_http_done: called premature == 0
* Connection #0 to host docker left intact

Verify that the container has been created:

$ sudo docker ps -a                                                                                                                                                                               
CONTAINER ID        IMAGE                   COMMAND                  CREATED              STATUS                    PORTS               NAMES
be10c2bb8f07        tutum/mongodb           "/run.sh"                About a minute ago   Created                                       inspiring_shannon

Now, let's start the container. From the strace output, we now know that the endpoint for that is /containers/UUID/start , the HTTP method is POST and we also know the container UUID from the previous curl command's output:

$ sudo curl -X POST -v --unix-socket /var/run/docker.sock http://docker/containers/be10c2bb8f07e36717a10cdf102a304aaf2ee072661df0265e322bdeb5fc1d78/start                                         
*   Trying /var/run/docker.sock...
* Connected to docker (/var/run/docker.sock) port 80 (#0)
> POST /containers/be10c2bb8f07e36717a10cdf102a304aaf2ee072661df0265e322bdeb5fc1d78/start HTTP/1.1
> Host: docker
> User-Agent: curl/7.50.3
> Accept: */*
> 
< HTTP/1.1 204 No Content
< Api-Version: 1.25
< Docker-Experimental: false
< Server: Docker/1.13.0 (linux)
< Date: Tue, 31 Jan 2017 05:05:46 GMT
< 
* Curl_http_done: called premature == 0
* Connection #0 to host docker left intact

Let's verify that the container is indeed running.

$ sudo docker ps   
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS                                                NAMES
be10c2bb8f07        tutum/mongodb       "/run.sh"           2 minutes ago       Up 8 seconds        0.0.0.0:27017->27017/tcp, 0.0.0.0:28017->28017/tcp   inspiring_shannon

FYI, the API documentation is pretty useful, if you don't want to keep running strace every time you want to find out the parameters. Perhaps they should also include some examples. :-)