-------------------------------------------------------------------------------
Directly using a Docker Socket API

The Unix socket "/var/run/docker.sock"  uses the REST API protocol.
Which is basically web calls with JSON results (pretty print using "jq").

If the socket is mapped into a container...
Then you can use web calls as shown below,
or a copy of the 'docker' command to make the API calls.


For example....
  "docker images"  is equivelent to calling the URI /images
  The output format is then appended and made into URL
    http://foo/images/json
  Which can be called using the command...
    curl --unix-socket /var/run/docker.sock http://foo/images/json | json_pp
  The hostname 'foo' can be any string (non-sensical)

  d_curl() {
     URI="$1"; shift
     curl --silent --unix-socket /var/run/docker.sock \
          "http://docker/v1.37$URI" "$@"
  }

  d_curl /info | jq

You can prefix the URI with a version so things do not break, when the API
upgrades.  And is actually recommended, and may in the future be required!

Most use a '/json' postfix.


-------------------------------------------------------------------------------
General server information

   CLI = info
   URI = /info

   The json arguement is not needed
     d_curl /info | jq

   EG: number of containers (running,paused,stopped), images, etc
-------------------------------------------------------------------------------
Images available...
  CLI = images    # docker command arguments
  URI = /images    # REST API aruments

  get the json
    d_curl /images/json -o images.json

  Extract the zeroth element
    jq '.[0]' images.json
  Extract the image name 'tags' removing it from the array
    jq '.[].RepoTags | .[]' images.json
  Extract Ids
    jq '.[].Id' images.json
  Extract Both
    jq '.[] | { tags: .RepoTags|.[], images: .Id }' images.json

  NOTE: "ID" is normally something like...
    sha256:a55fbf438dfd878424c402e365ef3d80c634f07d0f5832193880ee1b95626e4e
  Which the first 12 chars are used as a 'short id'  EG: a55fbf438dfd


  How to extract 'pairs' using jq?  EG: search for one, to find other values?
    EG: get the Id for the "environ/web-dev" image?


More Image info

  CLI = inspect {id}
  URI = /images/{id}

  Where {id} is either the short or full ID of the image (enough to be unique)

  Example get
    d_curl /images/bfa47f867b44/json -o image.json

  Image tag
    jq '.RepoTags|.[]' image.json

  Extract Environment Array
    jq '.ContainerConfig.Env|.[]' image.json


Add a Tag to an Image
   URL=images/{id}/tag?repo=name&tag=1.0

-------------------------------------------------------------------------------
Running Containers

  CLI = ps
  URI = /containers

  Example
    d_curl /containers/json -o containers.json

  Docker swarm service name
    jq '.[].Labels."com.docker.swarm.service.name"' containers.json

  Specific Conatiner (with environment information)
    d_curl http://a/containers/6d8fd885f60d/json

Processes in a container

  CLI = top
  URI = /containers/{id}/top
          ?ps_args=-ef

  The processes that are running in the container, listing the external PID's
  rather than the PID's seen within the container (if "ps" is available there).

Logs from a container

  CLI logs
  URI = /containers/{id}/logs
        ?follow           # continuious raw output
        ?stdout
        ?stderr
        ?since={time}     # unix timestamp {seconds since epoch)
        ?until={time}
        ?timestamps       # attach timestamps
        ?tail={count}     # last {sount} entries

Start / Stop

  URI = /containers/{id}/start
  URI = /containers/{id}/stop
  URI = /containers/{id}/restart
  URI = /containers/{id}/kill
        ?signal={signal}      # integer or string eg: SIGINT

  URI = /containers/{id}/remove
        ?v                    # remove volumes
        ?force                # kill if running
        ?link                 # remove link assocated

  URI = /containers/{id}/update
        ..lots of options..

  URI = /containers/{id}/rename
  URI = /containers/{id}/pause    # SIGSTOP all processes
  URI = /containers/{id}/unpause

-------------------------------------------------------------------------------
Service

Listing

  URI = /services
        ?filters=...

  d_curl /services | \
     jq '.[] | { ID: .ID,
                 Name: .Spec.Name,
                 Image: .Spec.TaskTemplate.ContainerSpec.Image
               }'

Creating

  URI = /services/create
        ... large POST data ...

-------------------------------------------------------------------------------
Watch events!

  d_curl /events --no-buffer

We get a stream of events that are happening, one json per line

-------------------------------------------------------------------------------
Running a container
This needs multiple API calls.

-------------------------------------------------------------------------------