centersl/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-04-12 06:19:22 +07:00
Code Issues Packages Projects Releases Wiki Activity

Moved topics under engine/api/

Browse Source
This commit is contained in:
Usha Mandya
2020-02-21 16:44:41 +00:00
parent 797daef4cc
commit 1566e01673
4 changed files with 300 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

772
develop/sdk/examples.md
View File

@@ -1,772 +0,0 @@
---
title: Examples using the Docker Engine SDKs and Docker API
keywords: developing, api, sdk, developers, rest, curl, python, go
redirect_from:
- /engine/api/getting-started/
- /engine/api/get-started/
- /engine/api/client-libraries/
- /engine/reference/api/remote_api_client_libraries/
- /reference/api/remote_api_client_libraries/
---
After you
[install Docker](/install/index.md), you can
[install the Go and Python SDKs](/develop/sdk/index.md#install-the-sdks) and
also try out the Docker Engine API.
Each of these examples show how to perform a given Docker operation using the Go
and Python SDKs and the HTTP API using `curl`.
## Run a container
This first example shows how to run a container using the Docker API. On the
command line, you would use the `docker run` command, but this is just as easy
to do from your own apps too.
This is the equivalent of typing `docker run alpine echo hello world` at the
command prompt:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab-run-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-run-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-run-curl" data-group="curl">HTTP</a></li>
</ul>
<div class="tab-content">
<div id="tab-run-go" class="tab-pane fade in active" markdown="1">
```go
package main
import (
"os"
"io"
"github.com/docker/docker/api/types"
"github.com/docker/docker/api/types/container"
"github.com/docker/docker/pkg/stdcopy"
"github.com/docker/docker/client"
"golang.org/x/net/context"
)
func main() {
ctx := context.Background()
cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
if err != nil {
panic(err)
}
reader, err := cli.ImagePull(ctx, "docker.io/library/alpine", types.ImagePullOptions{})
if err != nil {
panic(err)
}
io.Copy(os.Stdout, reader)
resp, err := cli.ContainerCreate(ctx, &container.Config{
Image: "alpine",
Cmd: []string{"echo", "hello world"},
Tty: true,
}, nil, nil, "")
if err != nil {
panic(err)
}
if err := cli.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{}); err != nil {
panic(err)
}
statusCh, errCh := cli.ContainerWait(ctx, resp.ID, container.WaitConditionNotRunning)
select {
case err := <-errCh:
if err != nil {
panic(err)
}
case <-statusCh:
}
out, err := cli.ContainerLogs(ctx, resp.ID, types.ContainerLogsOptions{ShowStdout: true})
if err != nil {
panic(err)
}
stdcopy.StdCopy(os.Stdout, os.Stderr, out)
}
```
</div>
<div id="tab-run-python" class="tab-pane fade" markdown="1">
```python
import docker
client = docker.from_env()
print client.containers.run("alpine", ["echo", "hello", "world"])
```
</div>
<div id="tab-run-curl" class="tab-pane fade" markdown="1">
```bash
$ curl --unix-socket /var/run/docker.sock -H "Content-Type: application/json" \
-d '{"Image": "alpine", "Cmd": ["echo", "hello world"]}' \
-X POST http:/v1.24/containers/create
{"Id":"1c6594faf5","Warnings":null}
$ curl --unix-socket /var/run/docker.sock -X POST http:/v1.24/containers/1c6594faf5/start
$ curl --unix-socket /var/run/docker.sock -X POST http:/v1.24/containers/1c6594faf5/wait
{"StatusCode":0}
$ curl --unix-socket /var/run/docker.sock "http:/v1.24/containers/1c6594faf5/logs?stdout=1"
hello world
```
</div>
</div><!-- end tab-content -->
## Run a container in the background
You can also run containers in the background, the equivalent of typing
`docker run -d bfirsh/reticulate-splines`:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab-rundetach-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-rundetach-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-rundetach-curl" data-group="curl">HTTP</a></li>
</ul>
<div class="tab-content">
<div id="tab-rundetach-go" class="tab-pane fade in active" markdown="1">
```go
package main
import (
"fmt"
"io"
"os"
"github.com/docker/docker/api/types"
"github.com/docker/docker/api/types/container"
"github.com/docker/docker/client"
"golang.org/x/net/context"
)
func main() {
ctx := context.Background()
cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
if err != nil {
panic(err)
}
imageName := "bfirsh/reticulate-splines"
out, err := cli.ImagePull(ctx, imageName, types.ImagePullOptions{})
if err != nil {
panic(err)
}
io.Copy(os.Stdout, out)
resp, err := cli.ContainerCreate(ctx, &container.Config{
Image: imageName,
}, nil, nil, "")
if err != nil {
panic(err)
}
if err := cli.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{}); err != nil {
panic(err)
}
fmt.Println(resp.ID)
}
```
</div>
<div id="tab-rundetach-python" class="tab-pane fade" markdown="1">
```python
import docker
client = docker.from_env()
container = client.containers.run("bfirsh/reticulate-splines", detach=True)
print container.id
```
</div>
<div id="tab-rundetach-curl" class="tab-pane fade" markdown="1">
```bash
$ curl --unix-socket /var/run/docker.sock -H "Content-Type: application/json" \
-d '{"Image": "bfirsh/reticulate-splines"}' \
-X POST http:/v1.24/containers/create
{"Id":"1c6594faf5","Warnings":null}
$ curl --unix-socket /var/run/docker.sock -X POST http:/v1.24/containers/1c6594faf5/start
```
</div>
</div><!-- end tab-content -->
## List and manage containers
You can use the API to list containers that are running, just like using
`docker ps`:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab-listcontainers-go" data-group="go">Go</a></li>
<li ><a data-toggle="tab" data-target="#tab-listcontainers-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-listcontainers-curl" data-group="curl">HTTP</a></li>
</ul>
<div class="tab-content">
<div id="tab-listcontainers-go" class="tab-pane fade in active" markdown="1">
```go
package main
import (
"fmt"
"github.com/docker/docker/api/types"
"github.com/docker/docker/client"
"golang.org/x/net/context"
)
func main() {
ctx := context.Background()
cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
if err != nil {
panic(err)
}
containers, err := cli.ContainerList(context.Background(), types.ContainerListOptions{})
if err != nil {
panic(err)
}
for _, container := range containers {
fmt.Println(container.ID)
}
}
```
</div>
<div id="tab-listcontainers-python" class="tab-pane fade" markdown="1">
```python
import docker
client = docker.from_env()
for container in client.containers.list():
print container.id
```
</div>
<div id="tab-listcontainers-curl" class="tab-pane fade" markdown="1">
```bash
$ curl --unix-socket /var/run/docker.sock http:/v1.24/containers/json
[{
"Id":"ae63e8b89a26f01f6b4b2c9a7817c31a1b6196acf560f66586fbc8809ffcd772",
"Names":["/tender_wing"],
"Image":"bfirsh/reticulate-splines",
...
}]
```
</div>
</div><!-- end tab-content -->
## Stop all running containers
Now that you know what containers exist, you can perform operations on them.
This example stops all running containers.
> **Note**: Don't run this on a production server. Also, if you are using swarm
> services, the containers stop, but Docker creates new ones to keep
> the service running in its configured state.
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab-stopcontainers-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-stopcontainers-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-stopcontainers-curl" data-group="curl">HTTP</a></li>
</ul>
<div class="tab-content">
<div id="tab-stopcontainers-go" class="tab-pane fade in active" markdown="1">
```go
package main
import (
"fmt"
"github.com/docker/docker/api/types"
"github.com/docker/docker/client"
"golang.org/x/net/context"
)
func main() {
ctx := context.Background()
cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
if err != nil {
panic(err)
}
containers, err := cli.ContainerList(ctx, types.ContainerListOptions{})
if err != nil {
panic(err)
}
for _, container := range containers {
fmt.Print("Stopping container ", container.ID[:10], "... ")
if err := cli.ContainerStop(ctx, container.ID, nil); err != nil {
panic(err)
}
fmt.Println("Success")
}
}
```
</div>
<div id="tab-stopcontainers-python" class="tab-pane fade" markdown="1">
```python
import docker
client = docker.from_env()
for container in client.containers.list():
container.stop()
```
</div>
<div id="tab-stopcontainers-curl" class="tab-pane fade" markdown="1">
```bash
$ curl --unix-socket /var/run/docker.sock http:/v1.24/containers/json
[{
"Id":"ae63e8b89a26f01f6b4b2c9a7817c31a1b6196acf560f66586fbc8809ffcd772",
"Names":["/tender_wing"],
"Image":"bfirsh/reticulate-splines",
...
}]
$ curl --unix-socket /var/run/docker.sock \
-X POST http:/v1.24/containers/ae63e8b89a26/stop
```
</div>
</div><!-- end tab-content -->
## Print the logs of a specific container
You can also perform actions on individual containers. This example prints the
logs of a container given its ID. You need to modify the code before running it
to change the hard-coded ID of the container to print the logs for.
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab-containerlogs-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-containerlogs-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-containerlogs-curl" data-group="curl">HTTP</a></li>
</ul>
<div class="tab-content">
<div id="tab-containerlogs-go" class="tab-pane fade in active" markdown="1">
```go
package main
import (
"io"
"os"
"github.com/docker/docker/api/types"
"github.com/docker/docker/client"
"golang.org/x/net/context"
)
func main() {
ctx := context.Background()
cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
if err != nil {
panic(err)
}
options := types.ContainerLogsOptions{ShowStdout: true}
// Replace this ID with a container that really exists
out, err := cli.ContainerLogs(ctx, "f1064a8a4c82", options)
if err != nil {
panic(err)
}
io.Copy(os.Stdout, out)
}
```
</div>
<div id="tab-containerlogs-python" class="tab-pane fade" markdown="1">
```python
import docker
client = docker.from_env()
container = client.containers.get('f1064a8a4c82')
print container.logs()
```
</div>
<div id="tab-containerlogs-curl" class="tab-pane fade" markdown="1">
```bash
$ curl --unix-socket /var/run/docker.sock "http:/v1.24/containers/ca5f55cdb/logs?stdout=1"
Reticulating spline 1...
Reticulating spline 2...
Reticulating spline 3...
Reticulating spline 4...
Reticulating spline 5...
```
</div>
</div><!-- end tab-content -->
## List all images
List the images on your Engine, similar to `docker image ls`:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab-listimages-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-listimages-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-listimages-curl" data-group="curl">HTTP</a></li>
</ul>
<div class="tab-content">
<div id="tab-listimages-go" class="tab-pane fade in active" markdown="1">
```go
package main
import (
"fmt"
"github.com/docker/docker/api/types"
"github.com/docker/docker/client"
"golang.org/x/net/context"
)
func main() {
ctx := context.Background()
cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
if err != nil {
panic(err)
}
images, err := cli.ImageList(context.Background(), types.ImageListOptions{})
if err != nil {
panic(err)
}
for _, image := range images {
fmt.Println(image.ID)
}
}
```
</div>
<div id="tab-listimages-python" class="tab-pane fade" markdown="1">
```python
import docker
client = docker.from_env()
for image in client.images.list():
print image.id
```
</div>
<div id="tab-listimages-curl" class="tab-pane fade" markdown="1">
```bash
$ curl --unix-socket /var/run/docker.sock http:/v1.24/images/json
[{
"Id":"sha256:31d9a31e1dd803470c5a151b8919ef1988ac3efd44281ac59d43ad623f275dcd",
"ParentId":"sha256:ee4603260daafe1a8c2f3b78fd760922918ab2441cbb2853ed5c439e59c52f96",
...
}]
```
</div>
</div><!-- end tab-content -->
## Pull an image
Pull an image, like `docker pull`:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab-pullimages-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-pullimages-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-pullimages-curl" data-group="curl">HTTP</a></li>
</ul>
<div class="tab-content">
<div id="tab-pullimages-go" class="tab-pane fade in active" markdown="1">
```go
package main
import (
"io"
"os"
"github.com/docker/docker/api/types"
"github.com/docker/docker/client"
"golang.org/x/net/context"
)
func main() {
ctx := context.Background()
cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
if err != nil {
panic(err)
}
out, err := cli.ImagePull(ctx, "alpine", types.ImagePullOptions{})
if err != nil {
panic(err)
}
defer out.Close()
io.Copy(os.Stdout, out)
}
```
</div>
<div id="tab-pullimages-python" class="tab-pane fade" markdown="1">
```python
import docker
client = docker.from_env()
image = client.images.pull("alpine")
print image.id
```
</div>
<div id="tab-pullimages-curl" class="tab-pane fade" markdown="1">
```bash
$ curl --unix-socket /var/run/docker.sock \
-X POST "http:/v1.24/images/create?fromImage=alpine"
{"status":"Pulling from library/alpine","id":"3.1"}
{"status":"Pulling fs layer","progressDetail":{},"id":"8f13703509f7"}
{"status":"Downloading","progressDetail":{"current":32768,"total":2244027},"progress":"[\u003e ] 32.77 kB/2.244 MB","id":"8f13703509f7"}
...
```
</div>
</div> <!-- end tab-content -->
## Pull an image with authentication
Pull an image, like `docker pull`, with authentication:
> **Note**: Credentials are sent in the clear. Docker's official registries use
> HTTPS. Private registries should also be configured to use HTTPS.
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab-pullimages-auth-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-pullimages-auth-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-pullimages-auth-curl" data-group="curl">HTTP</a></li>
</ul>
<div class="tab-content">
<div id="tab-pullimages-auth-go" class="tab-pane fade in active" markdown="1">
```go
package main
import (
"encoding/base64"
"encoding/json"
"io"
"os"
"github.com/docker/docker/api/types"
"github.com/docker/docker/client"
"golang.org/x/net/context"
)
func main() {
ctx := context.Background()
cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
if err != nil {
panic(err)
}
authConfig := types.AuthConfig{
Username: "username",
Password: "password",
}
encodedJSON, err := json.Marshal(authConfig)
if err != nil {
panic(err)
}
authStr := base64.URLEncoding.EncodeToString(encodedJSON)
out, err := cli.ImagePull(ctx, "alpine", types.ImagePullOptions{RegistryAuth: authStr})
if err != nil {
panic(err)
}
defer out.Close()
io.Copy(os.Stdout, out)
}
```
</div>
<div id="tab-pullimages-auth-python" class="tab-pane fade" markdown="1">
The Python SDK retrieves authentication information from the [credentials
store](/engine/reference/commandline/login/#credentials-store) file and
integrates with [credential
helpers](https://github.com/docker/docker-credential-helpers){: target="_blank"
class="_" }. It is possible to override these credentials, but that is out of
scope for this Getting Started guide. After using `docker login`, the Python SDK
uses these credentials automatically.
```python
import docker
client = docker.from_env()
image = client.images.pull("alpine")
print image.id
```
</div>
<div id="tab-pullimages-curl" class="tab-pane fade" markdown="1">
This example leaves the credentials in your shell's history, so consider
this a naive implementation. The credentials are passed as a Base-64-encoded
JSON structure.
```bash
$ JSON=$(echo '{"username": "string", "password": "string", "serveraddress": "string"}' | base64)
$ curl --unix-socket /var/run/docker.sock \
-H "Content-Type: application/tar"
-X POST "http:/v1.24/images/create?fromImage=alpine"
-H "X-Registry-Auth"
-d "$JSON"
{"status":"Pulling from library/alpine","id":"3.1"}
{"status":"Pulling fs layer","progressDetail":{},"id":"8f13703509f7"}
{"status":"Downloading","progressDetail":{"current":32768,"total":2244027},"progress":"[\u003e ] 32.77 kB/2.244 MB","id":"8f13703509f7"}
...
```
</div>
</div> <!-- end tab-content -->
## Commit a container
Commit a container to create an image from its contents:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab-commit-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-commit-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-commit-curl" data-group="curl">HTTP</a></li>
</ul>
<div class="tab-content">
<div id="tab-commit-go" class="tab-pane fade in active" markdown="1">
```go
package main
import (
"fmt"
"github.com/docker/docker/api/types"
"github.com/docker/docker/api/types/container"
"github.com/docker/docker/client"
"golang.org/x/net/context"
)
func main() {
ctx := context.Background()
cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
if err != nil {
panic(err)
}
createResp, err := cli.ContainerCreate(ctx, &container.Config{
Image: "alpine",
Cmd: []string{"touch", "/helloworld"},
}, nil, nil, "")
if err != nil {
panic(err)
}
if err := cli.ContainerStart(ctx, createResp.ID, types.ContainerStartOptions{}); err != nil {
panic(err)
}
statusCh, errCh := cli.ContainerWait(ctx, createResp.ID, container.WaitConditionNotRunning)
select {
case err := <-errCh:
if err != nil {
panic(err)
}
case <-statusCh:
}
commitResp, err := cli.ContainerCommit(ctx, createResp.ID, types.ContainerCommitOptions{Reference: "helloworld"})
if err != nil {
panic(err)
}
fmt.Println(commitResp.ID)
}
```
</div>
<div id="tab-commit-python" class="tab-pane fade" markdown="1">
```python
import docker
client = docker.from_env()
container = client.containers.run("alpine", ["touch", "/helloworld"], detach=True)
container.wait()
image = container.commit("helloworld")
print image.id
```
</div>
<div id="tab-commit-curl" class="tab-pane fade" markdown="1">
```bash
$ docker run -d alpine touch /helloworld
0888269a9d584f0fa8fc96b3c0d8d57969ceea3a64acf47cd34eebb4744dbc52
$ curl --unix-socket /var/run/docker.sock\
-X POST "http:/v1.24/commit?container=0888269a9d&repo=helloworld"
{"Id":"sha256:6c86a5cd4b87f2771648ce619e319f3e508394b5bfc2cdbd2d60f59d52acda6c"}
```
</div>
</div><!-- end tab-content -->

299
develop/sdk/index.md
View File

@@ -1,299 +0,0 @@
---
title: Develop with Docker Engine SDKs and API
description: Using Docker SDKs and APIs to automate Docker tasks in your language of choice
keywords: developing, api, sdk
redirect_from:
- /engine/api/
- /engine/reference/api/
- /engine/reference/api/docker_remote_api/
- /reference/api/
- /reference/api/docker_remote_api/
- /engine/api/sdks/
---
Docker provides an API for interacting with the Docker daemon (called the Docker
Engine API), as well as SDKs for Go and Python. The SDKs allow you to build and
scale Docker apps and solutions quickly and easily. If Go or Python don't work
for you, you can use the Docker Engine API directly.
The Docker Engine API is a RESTful API accessed by an HTTP client such as `wget` or
`curl`, or the HTTP library which is part of most modern programming languages.
## Install the SDKs
Use the following commands to install the Go or Python SDK. Both SDKs can be
installed and coexist together.
### Go SDK
```bash
go get github.com/docker/docker/client
```
The client requires a recent version of Go. Run `go version` and ensure that you
are running at least version 1.9.4 of Go
[Read the full Docker Engine Go SDK reference](https://godoc.org/github.com/docker/docker/client).
### Python SDK
- **Recommended**: Run `pip install docker`.
- **If you can't use `pip`**:
1. [Download the package directly](https://pypi.python.org/pypi/docker/).
2. Extract it and change to the extracted directory,
3. Run `python setup.py install`.
[Read the full Docker Engine Python SDK reference](https://docker-py.readthedocs.io/).
## View the API reference
You can
[view the reference for the latest version of the API](/engine/api/latest/)
or [choose a specific version](/engine/api/version-history/).
## Versioned API and SDK
The version of the Docker Engine API you should use depends upon the version of
your Docker daemon and Docker client.
A given version of the Docker Engine SDK supports a specific version of the
Docker Engine API, as well as all earlier versions. If breaking changes occur,
they are documented prominently.
> Daemon and client API mismatches
>
> The Docker daemon and client do not necessarily need to be the same version
> at all times. However, keep the following in mind.
>
> - If the daemon is newer than the client, the client does not know about new
> features or deprecated API endpoints in the daemon.
>
> - If the client is newer than the daemon, the client can request API
> endpoints that the daemon does not know about.
A new version of the API is released when new features are added. The Docker API
is backward-compatible, so you do not need to update code that uses the API
unless you need to take advantage of new features.
To see the highest version of the API your Docker daemon and client support, use
`docker version`:
```bash
$ docker version
Client:
Version: 17.04.0-ce
API version: 1.28
Go version: go1.7.5
Git commit: 4845c56
Built: Wed Apr 5 06:06:36 2017
OS/Arch: darwin/amd64
Server:
Version: 17.04.0-ce
API version: 1.28 (minimum version 1.12)
Go version: go1.7.5
Git commit: 4845c56
Built: Tue Apr 4 00:37:25 2017
OS/Arch: linux/amd64
Experimental: true
```
You can specify the API version to use, in one of the following ways:
- When using the SDK, use the latest version you can, but at least the version
that incorporates the API version with the features you need.
- When using `curl` directly, specify the version as the first part of the URL.
For instance, if the endpoint is `/containers/`, you can use
`/v1.27/containers/`.
- To force the Docker CLI or the Docker Engine SDKs to use an old version
version of the API than the version reported by `docker version`, set the
environment variable `DOCKER_API_VERSION` to the correct version. This works
on Linux, Windows, or macOS clients.
```bash
DOCKER_API_VERSION='1.27'
```
While the environment variable is set, that version of the API is used, even
if the Docker daemon supports a newer version.
- For the SDKs, you can also specify the API version programmatically, as a
parameter to the `client` object. See the
[Go constructor](https://github.com/moby/moby/blob/master/client/client.go#L136){: target="_blank" class="_"}
or the
[Python SDK documentation for `client`](https://docker-py.readthedocs.io/en/stable/client.html).
### Docker Engine - Enterprise and Docker Engine - Community API mismatch
If you use Docker Engine - Enterprise in production, we recommend using Docker Engine - Enterprise in development
too. If you can't, such as when your developers use Docker Desktop for Mac or Docker Desktop for
Windows and manually build and push images, then your developers need to configure
their Docker clients to use the same version of the API reported by their Docker
daemon. This prevents the developer from using a feature that is not yet supported
on the daemon where the workload runs in production. You can do this one of two ways:
- Configure the Docker client to connect to an external daemon running Docker EE.
You can use the `-H` flag on the `docker` command or set the `DOCKER_HOST`
environment variable. The client uses the daemon's latest supported API version.
- Configure the Docker client to use a specific API by setting the `DOCKER_API_VERSION`
environment variable to the API version to use, such as `1.30`.
### API version matrix
Docker does not recommend running versions prior to 1.12, which means you
are encouraged to use an API version of 1.24 or higher.
{% include api-version-matrix.md %}
### Choose the SDK or API version to use
Use the following guidelines to choose the SDK or API version to use in your
code:
- If you're starting a new project, use the
[latest version](/engine/api/latest/), but do specify the version you are
using. This helps prevent surprises.
- If you need a new feature, update your code to use at least the minimum version
that supports the feature, and prefer the latest version you can use.
- Otherwise, continue to use the version that your code is already using.
## SDK and API quickstart
As an example, the `docker run` command can be easily implemented using the
Docker API directly, or using the Python or Go SDK.
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#go">Go</a></li>
<li><a data-toggle="tab" data-target="#python">Python</a></li>
<li><a data-toggle="tab" data-target="#curl">HTTP</a></li>
</ul>
<div class="tab-content">
<div id="go" class="tab-pane fade in active" markdown="1">
```go
package main
import (
"context"
"io"
"os"
"github.com/docker/docker/api/types"
"github.com/docker/docker/api/types/container"
"github.com/docker/docker/client"
"github.com/docker/docker/pkg/stdcopy"
)
func main() {
ctx := context.Background()
cli, err := client.NewClientWithOpts(client.FromEnv)
if err != nil {
panic(err)
}
cli.NegotiateAPIVersion(ctx)
reader, err := cli.ImagePull(ctx, "docker.io/library/alpine", types.ImagePullOptions{})
if err != nil {
panic(err)
}
io.Copy(os.Stdout, reader)
resp, err := cli.ContainerCreate(ctx, &container.Config{
Image: "alpine",
Cmd: []string{"echo", "hello world"},
}, nil, nil, "")
if err != nil {
panic(err)
}
if err := cli.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{}); err != nil {
panic(err)
}
statusCh, errCh := cli.ContainerWait(ctx, resp.ID, container.WaitConditionNotRunning)
select {
case err := <-errCh:
if err != nil {
panic(err)
}
case <-statusCh:
}
out, err := cli.ContainerLogs(ctx, resp.ID, types.ContainerLogsOptions{ShowStdout: true})
if err != nil {
panic(err)
}
stdcopy.StdCopy(os.Stdout, os.Stderr, out)
}
```
</div>
<div id="python" class="tab-pane fade" markdown="1">
```python
import docker
client = docker.from_env()
print client.containers.run("alpine", ["echo", "hello", "world"])
```
</div>
<div id="curl" class="tab-pane fade" markdown="1">
```bash
$ curl --unix-socket /var/run/docker.sock -H "Content-Type: application/json" \
-d '{"Image": "alpine", "Cmd": ["echo", "hello world"]}' \
-X POST http:/v1.24/containers/create
{"Id":"1c6594faf5","Warnings":null}
$ curl --unix-socket /var/run/docker.sock -X POST http:/v1.24/containers/1c6594faf5/start
$ curl --unix-socket /var/run/docker.sock -X POST http:/v1.24/containers/1c6594faf5/wait
{"StatusCode":0}
$ curl --unix-socket /var/run/docker.sock "http:/v1.24/containers/1c6594faf5/logs?stdout=1"
hello world
```
</div>
</div>
For more examples, take a look at the
[getting started guide](examples.md).
## Unofficial libraries
There are a number of community supported libraries available for other
languages. They have not been tested by Docker, so if you run into any issues,
file them with the library maintainers.
| Language | Library |
|:----------------------|:----------------------------------------------------------------------------|
| C | [libdocker](https://github.com/danielsuo/libdocker) |
| C# | [Docker.DotNet](https://github.com/ahmetalpbalkan/Docker.DotNet) |
| C++ | [lasote/docker_client](https://github.com/lasote/docker_client) |
| Dart | [bwu_docker](https://github.com/bwu-dart/bwu_docker) |
| Erlang | [erldocker](https://github.com/proger/erldocker) |
| Gradle | [gradle-docker-plugin](https://github.com/gesellix/gradle-docker-plugin) |
| Groovy | [docker-client](https://github.com/gesellix/docker-client) |
| Haskell | [docker-hs](https://github.com/denibertovic/docker-hs) |
| HTML (Web Components) | [docker-elements](https://github.com/kapalhq/docker-elements) |
| Java | [docker-client](https://github.com/spotify/docker-client) |
| Java | [docker-java](https://github.com/docker-java/docker-java) |
| Java | [docker-java-api](https://github.com/amihaiemil/docker-java-api) |
| NodeJS | [dockerode](https://github.com/apocas/dockerode) |
| NodeJS | [harbor-master](https://github.com/arhea/harbor-master) |
| Perl | [Eixo::Docker](https://github.com/alambike/eixo-docker) |
| PHP | [Docker-PHP](https://github.com/docker-php/docker-php) |
| Ruby | [docker-api](https://github.com/swipely/docker-api) |
| Rust | [docker-rust](https://github.com/abh1nav/docker-rust) |
| Rust | [shiplift](https://github.com/softprops/shiplift) |
| Scala | [tugboat](https://github.com/softprops/tugboat) |
| Scala | [reactive-docker](https://github.com/almoehi/reactive-docker) |
| Swift | [docker-client-swift](https://github.com/valeriomazzeo/docker-client-swift) |