python/lib/docker/README.md

   1 docker-py
   2 =========
   3
   4 [![Build Status](https://travis-ci.org/dotcloud/docker-py.png)](https://travis-ci.org/dotcloud/docker-py)
   5
   6 An API client for docker written in Python
   7
   8 API
   9 ===
  10
  11 To instantiate a `Client` class that will allow you to communicate with
  12 a Docker daemon, simply do:
  13
  14 ```python
  15 c = docker.Client(base_url='unix://var/run/docker.sock',
  16                   version='1.6',
  17                   timeout=10)
  18 ```
  19
  20 `base_url` refers to the protocol+hostname+port where the docker server
  21 is hosted. `version` is the version of the API the client will use and
  22 `timeout` specifies the HTTP request timeout, in seconds.
  23
  24 ```python
  25 c.build(path=None, tag=None, quiet=False, fileobj=None, nocache=False,
  26         rm=False, stream=False)
  27 ```
  28
  29 Similar to the `docker build` command. Either `path` or `fileobj` needs
  30 to be set. `path` can be a local path (to a directory containing a
  31 Dockerfile) or a remote URL. `fileobj` must be a readable file-like
  32 object to a Dockerfile.
  33
  34 ```python
  35 c.commit(container, repository=None, tag=None, message=None, author=None,
  36          conf=None)
  37 ```
  38
  39 Identical to the `docker commit` command.
  40
  41 ```python
  42 c.containers(quiet=False, all=False, trunc=True, latest=False, since=None,
  43              before=None, limit=-1)
  44 ```
  45
  46 Identical to the `docker ps` command.
  47
  48 ```python
  49 c.copy(container, resource)
  50 ```
  51
  52 Identical to the `docker cp` command.
  53
  54 ```python
  55 c.create_container(image, command=None, hostname=None, user=None,
  56                    detach=False, stdin_open=False, tty=False, mem_limit=0,
  57                    ports=None, environment=None, dns=None, volumes=None,
  58                    volumes_from=None, network_disabled=False, name=None,
  59                    entrypoint=None, cpu_shares=None, working_dir=None)
  60 ```
  61
  62 Creates a container that can then be `start`ed. Parameters are similar
  63 to those for the `docker run` command except it doesn't support the
  64 attach options (`-a`). See "Port bindings" and "Using volumes" below for
  65 more information on how to create port bindings and volume mappings.
  66
  67 ```python
  68 c.diff(container)
  69 ```
  70
  71 Identical to the `docker diff` command.
  72
  73 ```python
  74 c.export(container)
  75 ```
  76
  77 Identical to the `docker export` command.
  78
  79 ```python
  80 c.history(image)
  81 ```
  82
  83 Identical to the `docker history` command.
  84
  85 ```python
  86 c.images(name=None, quiet=False, all=False, viz=False)
  87 ```
  88
  89 Identical to the `docker images` command.
  90
  91 ```python
  92 c.import_image(src, data=None, repository=None, tag=None)
  93 ```
  94
  95 Identical to the `docker import` command. If `src` is a string or
  96 unicode string, it will be treated as a URL to fetch the image from. To
  97 import an image from the local machine, `src` needs to be a file-like
  98 object or bytes collection.  To import from a tarball use your absolute
  99 path to your tarball.  To load arbitrary data as tarball use whatever
 100 you want as src and your tarball content in data.
 101
 102 ```python
 103 c.info()
 104 ```
 105
 106 Identical to the `docker info` command.
 107
 108 ```python
 109 c.insert(image, url, path)
 110 ```
 111
 112 Identical to the `docker insert` command.
 113
 114 ```python
 115 c.inspect_container(container)
 116 ```
 117
 118 Identical to the `docker inspect` command, but only for containers.
 119
 120 ```python
 121 c.inspect_image(image_id)
 122 ```
 123
 124 Identical to the `docker inspect` command, but only for images.
 125
 126 ```python
 127 c.kill(container, signal=None)
 128 ```
 129
 130 Kill a container. Similar to the `docker kill` command.
 131
 132 ```python
 133 c.login(username, password=None, email=None, registry=None)
 134 ```
 135
 136 Identical to the `docker login` command (but non-interactive, obviously).
 137
 138 ```python
 139 c.logs(container, stdout=True, stderr=True, stream=False)
 140 ```
 141
 142 Identical to the `docker logs` command. The `stream` parameter makes the
 143 `logs` function return a blocking generator you can iterate over to
 144 retrieve log output as it happens.
 145
 146 ```python
 147 c.attach(container, stdout=True, stderr=True, stream=False, logs=False)
 148 ```
 149
 150 The `logs` function is a wrapper around this one, which you can use
 151 instead if you want to fetch/stream container output without first
 152 retrieving the entire backlog.
 153
 154 ```python
 155 c.port(container, private_port)
 156 ```
 157
 158 Identical to the `docker port` command.
 159
 160 ```python
 161 c.pull(repository, tag=None, stream=False)
 162 ```
 163
 164 Identical to the `docker pull` command.
 165
 166 ```python
 167 c.push(repository, stream=False)
 168 ```
 169
 170 Identical to the `docker push` command.
 171
 172 ````python
 173 c.remove_container(container, v=False, link=False)
 174 ```
 175
 176 Remove a container. Similar to the `docker rm` command.
 177
 178 ```python
 179 c.remove_image(image)
 180 ```
 181
 182 Remove an image. Similar to the `docker rmi` command.
 183
 184 ```python
 185 c.restart(container, timeout=10)
 186 ```
 187 Restart a container. Similar to the `docker restart` command.
 188
 189 ```python
 190 c.search(term)
 191 ```
 192
 193 Identical to the `docker search` command.
 194
 195 ```python
 196 c.start(container, binds=None, port_bindings=None, lxc_conf=None,
 197         publish_all_ports=False, links=None, privileged=False)
 198 ```
 199
 200 Similar to the `docker start` command, but doesn't support attach
 201 options.  Use `docker logs` to recover `stdout`/`stderr`.
 202
 203 `binds` allows to bind a directory in the host to the container. See
 204 "Using volumes" below for more information. `port_bindings` exposes
 205 container ports to the host. See "Port bindings" below for more
 206 information. `lxc_conf` allows to pass LXC configuration options using a
 207 dictionary. `privileged` starts the container in privileged mode.
 208
 209 [Links](http://docs.docker.io/en/latest/use/working_with_links_names/)
 210 can be specified with the `links` argument. They can either be
 211 specified as a dictionary mapping name to alias or as a list of
 212 `(name, alias)` tuples.
 213
 214 ```python
 215 c.stop(container, timeout=10)
 216 ```
 217
 218 Stops a container. Similar to the `docker stop` command.
 219
 220 ```python
 221 c.tag(image, repository, tag=None, force=False)
 222 ```
 223
 224 Identical to the `docker tag` command.
 225
 226 ```python
 227 c.top(container)
 228 ```
 229
 230 Identical to the `docker top` command.
 231
 232 ```python
 233 c.version()
 234 ```
 235
 236 Identical to the `docker version` command.
 237
 238 ```python
 239 c.wait(container)
 240 ```
 241
 242 Wait for a container and return its exit code. Similar to the `docker
 243 wait` command.
 244
 245
 246 Port bindings
 247 =============
 248
 249 Port bindings is done in two parts. Firstly, by providing a list of ports to
 250 open inside the container in the `Client.create_container` method.
 251
 252 ```python
 253 c.create_container('busybox', 'ls', ports=[1111, 2222])
 254 ```
 255
 256 If you wish to use UDP instead of TCP (default), you can declare it like such:
 257
 258 ```python
 259 c.create_container('busybox', 'ls', ports=[(1111, 'udp'), 2222])
 260 ```
 261
 262 Bindings are then declared in the `Client.start` method.
 263
 264 ```python
 265 c.start(container_id, port_bindings={1111: 4567, 2222: None})
 266 ```
 267
 268 You can limit the host address on which the port will be exposed like such:
 269
 270 ```python
 271 c.start(container_id, port_bindings={1111: ('127.0.0.1', 4567)})
 272 ```
 273
 274 Or without host port assignment:
 275
 276 ```python
 277 c.start(container_id, port_bindings={1111: ('127.0.0.1',)})
 278 ```
 279
 280
 281 Using volumes
 282 =============
 283
 284 Similarly, volume declaration is done in two parts. First, you have to provide
 285 a list of mountpoints to the `Client.create_container` method.
 286
 287 ```python
 288 c.create_container('busybox', 'ls', volumes=['/mnt/vol1', '/mnt/vol2'])
 289 ```
 290
 291 Volume mappings are then declared inside the `Client.start` method like this:
 292
 293 ```python
 294 c.start(container_id, binds={
 295     '/home/user1/': '/mnt/vol2',
 296     '/var/www': '/mnt/vol1'
 297 })
 298 ```