docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add develop section, reorganize TOC (WIP) (#4312)

This commit is contained in:
Misty Stanley-Jones 2017-09-26 20:16:59 -07:00 committed by GitHub
parent 410ed46347
commit 99a697824b
9 changed files with 1474 additions and 1311 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

534
_data/toc.yaml
View File

@ -135,6 +135,16 @@ guides:
title: Known issues
- path: /toolbox/faqs/troubleshoot/
title: Troubleshooting
- sectiontitle: Compatibility between Docker versions
section:
- path: /engine/migration/
title: Migrate to Docker 1.10
- path: /engine/breaking_changes/
title: Breaking changes
- path: /engine/deprecated/
title: Deprecated Docker features
- path: /engine/faq/
title: FAQ
- sectiontitle: Release notes
section:
- path: /enterprise/release-notes/
@ -166,147 +176,70 @@ guides:
title: Network containers
- path: /engine/docker-overview/
title: Docker overview
- sectiontitle: User guide
- sectiontitle: Develop with Docker
section:
- path: /engine/userguide/
title: Overview
- sectiontitle: Work with images
section:
- path: /engine/userguide/eng-image/dockerfile_best-practices/
title: Best practices for writing Dockerfiles
- path: /engine/userguide/eng-image/baseimages/
title: Create a base image
- path: /engine/userguide/eng-image/multistage-build/
title: Use multi-stage builds
- path: /engine/userguide/eng-image/image_management/
title: Image management
- sectiontitle: Store data within containers
section:
- path: /engine/userguide/storagedriver/
title: Storage driver overview
- path: /engine/userguide/storagedriver/imagesandcontainers/
title: About images, containers, and storage drivers
- path: /engine/userguide/storagedriver/selectadriver/
title: Select a storage driver
- path: /engine/userguide/storagedriver/aufs-driver/
title: Use the AUFS storage driver
- path: /engine/userguide/storagedriver/btrfs-driver/
title: Use the Btrfs storage driver
- path: /engine/userguide/storagedriver/device-mapper-driver/
title: Use the Device mapper storage driver
- path: /engine/userguide/storagedriver/overlayfs-driver/
title: Use the OverlayFS storage driver
- path: /engine/userguide/storagedriver/zfs-driver/
title: Use the ZFS storage driver
- path: /engine/userguide/storagedriver/vfs-driver/
title: Use the VFS storage driver
- sectiontitle: Network configuration
section:
- path: /engine/userguide/networking/
title: Docker container networking
- path: /engine/userguide/networking/work-with-networks/
title: Work with network commands
- path: /engine/swarm/networking/
title: Manage swarm service networks
- path: /engine/userguide/networking/overlay-standalone-swarm/
title: Multi-host networking with standalone swarms
- path: /engine/userguide/networking/get-started-macvlan/
title: Get started with macvlan network driver
- path: /engine/userguide/networking/overlay-security-model/
title: Swarm mode overlay network security model
- path: /engine/userguide/networking/configure-dns/
title: Configure container DNS in user-defined networks
- sectiontitle: Default bridge network
- sectiontitle: Develop your apps on Docker
section:
- path: /engine/userguide/networking/default_network/dockerlinks/
title: Legacy container links
- path: /engine/userguide/networking/default_network/binding/
title: Bind container ports to the host
- path: /engine/userguide/networking/default_network/build-bridges/
title: Build your own bridge
- path: /engine/userguide/networking/default_network/configure-dns/
title: Configure container DNS
- path: /engine/userguide/networking/default_network/custom-docker0/
title: Customize the docker0 bridge
- path: /engine/userguide/networking/default_network/container-communication/
title: Understand container communication
- path: /engine/userguide/networking/default_network/ipv6/
title: IPv6 with Docker
- path: /engine/userguide/labels-custom-metadata/
title: Apply custom metadata
- path: /engine/migration/
title: Migrate to Engine 1.10
- path: /engine/breaking_changes/
title: Breaking changes
- path: /engine/deprecated/
title: Deprecated Engine features
- path: /engine/faq/
title: FAQ
- sectiontitle: Admin guide
- path: /develop/
title: App development overview
- path: /develop/dev-best-practices/
title: App development best practices
- sectiontitle: Work with images
section:
- path: /engine/userguide/eng-image/dockerfile_best-practices/
title: Best practices for writing Dockerfiles
- path: /engine/userguide/eng-image/baseimages/
title: Create a base image
- path: /engine/userguide/eng-image/multistage-build/
title: Use multi-stage builds
- path: /engine/reference/builder/
title: Dockerfile reference
nosync: true
- path: /engine/userguide/eng-image/image_management/
title: Image management
- path: /samples/
title: Docker app examples
nosync: true
- sectiontitle: Develop using the Docker Engine SDKs and API
section:
- path: /develop/sdk/
title: Overview
- path: /develop/sdk/examples/
title: SDK and API examples
- sectiontitle: Configure networking
section:
- path: /engine/admin/
title: Configuring and running Docker
- path: /engine/admin/prometheus/
title: Collect Docker metrics with Prometheus
- path: /engine/admin/start-containers-automatically/
title: Start containers automatically
- path: /engine/admin/resource_constraints/
title: Limit a container's resources
- path: /engine/admin/pruning/
title: Prune unused Docker objects
- path: /engine/admin/live-restore/
title: Keep containers alive during daemon downtime
- path: /engine/admin/systemd/
title: Control and configure Docker with systemd
- path: /engine/admin/formatting/
title: Format command and log output
- path: /registry/recipes/mirror/
title: Run a local registry mirror
nosync: true
- sectiontitle: Logging
- path: /engine/userguide/networking/
title: Docker container networking
- path: /engine/userguide/networking/work-with-networks/
title: Work with network commands
- path: /engine/swarm/networking/
title: Manage swarm service networks
- path: /engine/userguide/networking/overlay-standalone-swarm/
title: Multi-host networking with standalone swarms
- path: /engine/userguide/networking/get-started-macvlan/
title: Get started with macvlan network driver
- path: /engine/userguide/networking/overlay-security-model/
title: Swarm mode overlay network security model
- path: /engine/userguide/networking/configure-dns/
title: Configure container DNS in user-defined networks
- sectiontitle: Default bridge network
section:
- path: /engine/admin/logging/view_container_logs/
title: View a container's logs
- path: /engine/admin/logging/overview/
title: Configuring logging drivers
- path: /engine/admin/logging/plugins/
title: Use a logging driver plugin
- path: /engine/admin/logging/log_tags/
title: Log tags for logging driver
- path: /engine/admin/logging/logentries/
title: Logentries logging driver
- path: /engine/admin/logging/json-file/
title: JSON File logging driver
- path: /engine/admin/logging/gelf/
title: Graylog Extended Format (GELF) logging driver
- path: /engine/admin/logging/syslog/
title: Syslog logging driver
- path: /engine/admin/logging/awslogs/
title: Amazon CloudWatch logs logging driver
- path: /engine/admin/logging/etwlogs/
title: ETW logging driver
- path: /engine/admin/logging/fluentd/
title: Fluentd logging driver
- path: /engine/admin/logging/gcplogs/
title: Google Cloud logging driver
- path: /engine/admin/logging/journald/
title: Journald logging driver
- path: /engine/admin/logging/splunk/
title: Splunk logging driver
- path: /engine/admin/dsc/
title: PowerShell DSC usage
- path: /engine/admin/ansible/
title: Using Ansible
- path: /engine/admin/chef/
title: Using Chef
- path: /engine/admin/puppet/
title: Using Puppet
- path: /engine/admin/multi-service_container/
title: Run multiple services in a container
- path: /engine/admin/runmetrics/
title: Runtime metrics
- path: /engine/admin/ambassador_pattern_linking/
title: Link via an ambassador container
- path: /engine/userguide/networking/default_network/dockerlinks/
title: Legacy container links
- path: /engine/userguide/networking/default_network/binding/
title: Bind container ports to the host
- path: /engine/userguide/networking/default_network/build-bridges/
title: Build your own bridge
- path: /engine/userguide/networking/default_network/configure-dns/
title: Configure container DNS
- path: /engine/userguide/networking/default_network/custom-docker0/
title: Customize the docker0 bridge
- path: /engine/userguide/networking/default_network/container-communication/
title: Understand container communication
- path: /engine/userguide/networking/default_network/ipv6/
title: IPv6 with Docker
- sectiontitle: Manage application data
section:
- path: /engine/admin/volumes/
@ -317,99 +250,205 @@ guides:
title: Bind mounts
- path: /engine/admin/volumes/tmpfs/
title: tmpfs mounts
- path: /engine/userguide/storagedriver/
title: Container storage drivers
nosync: true
- sectiontitle: Troubleshoot Docker Engine
- path: /engine/admin/troubleshooting_volume_errors/
title: Troubleshoot volume problems
- sectiontitle: Store data within containers
section:
- path: /engine/userguide/storagedriver/
title: Storage driver overview
- path: /engine/userguide/storagedriver/imagesandcontainers/
title: About images, containers, and storage drivers
- path: /engine/userguide/storagedriver/selectadriver/
title: Select a storage driver
- path: /engine/userguide/storagedriver/aufs-driver/
title: Use the AUFS storage driver
- path: /engine/userguide/storagedriver/btrfs-driver/
title: Use the Btrfs storage driver
- path: /engine/userguide/storagedriver/device-mapper-driver/
title: Use the Device mapper storage driver
- path: /engine/userguide/storagedriver/overlayfs-driver/
title: Use the OverlayFS storage driver
- path: /engine/userguide/storagedriver/zfs-driver/
title: Use the ZFS storage driver
- path: /engine/userguide/storagedriver/vfs-driver/
title: Use the VFS storage driver
- sectiontitle: Run your app in production
section:
- path: /engine/admin/troubleshooting_volume_errors/
title: Troubleshoot volume problems
- sectiontitle: Manage a swarm
section:
- path: /engine/swarm/
title: Swarm mode overview
- path: /engine/swarm/key-concepts/
title: Swarm mode key concepts
- sectiontitle: Get started with swarm mode
section:
- path: /engine/swarm/swarm-tutorial/
title: Set up for the tutorial
- path: /engine/swarm/swarm-tutorial/create-swarm/
title: Create a swarm
- path: /engine/swarm/swarm-tutorial/add-nodes/
title: Add nodes to the swarm
- path: /engine/swarm/swarm-tutorial/deploy-service/
title: Deploy a service
- path: /engine/swarm/swarm-tutorial/inspect-service/
title: Inspect the service
- path: /engine/swarm/swarm-tutorial/scale-service/
title: Scale the service
- path: /engine/swarm/swarm-tutorial/delete-service/
title: Delete the service
- path: /engine/swarm/swarm-tutorial/rolling-update/
title: Apply rolling updates
- path: /engine/swarm/swarm-tutorial/drain-node/
title: Drain a node
- path: /engine/swarm/ingress/
title: Use swarm mode routing mesh
- sectiontitle: How swarm mode works
section:
- path: /engine/swarm/how-swarm-mode-works/nodes/
title: How nodes work
- path: /engine/swarm/how-swarm-mode-works/services/
title: How services work
- path: /engine/swarm/how-swarm-mode-works/pki/
title: Manage swarm security with PKI
- path: /engine/swarm/swarm-mode/
title: Run Docker Engine in swarm mode
- path: /engine/swarm/join-nodes/
title: Join nodes to a swarm
- path: /engine/swarm/manage-nodes/
title: Manage nodes in a swarm
- path: /engine/swarm/services/
title: Deploy services to a swarm
- path: /engine/swarm/configs/
title: Store service configuration data
- path: /engine/swarm/secrets/
title: Manage sensitive data with Docker secrets
- path: /engine/swarm/swarm_manager_locking/
title: Lock your swarm
- path: /engine/swarm/networking/
title: Manage swarm service networks
- path: /engine/swarm/admin_guide/
title: Swarm administration guide
- path: /engine/swarm/raft/
title: Raft consensus in swarm mode
- sectiontitle: Secure Engine
section:
- path: /engine/security/security/
title: Docker security
- path: /engine/security/non-events/
title: Docker security non-events
- path: /engine/security/https/
title: Protect the Docker daemon socket
- path: /engine/security/certificates/
title: Using certificates for repository client verification
- sectiontitle: Use trusted images
section:
- path: /engine/security/trust/content_trust/
title: Content trust in Docker
- path: /engine/security/trust/trust_automation/
title: Automation with content trust
- path: /engine/security/trust/trust_delegation/
title: Delegations for content trust
- path: /engine/security/trust/deploying_notary/
title: Deploying Notary
- path: /engine/security/trust/trust_key_mng/
title: Manage keys for content trust
- path: /engine/security/trust/trust_sandbox/
title: Play in a content trust sandbox
- path: /engine/security/apparmor/
title: AppArmor security profiles for Docker
- path: /engine/security/seccomp/
title: Seccomp security profiles for Docker
- path: /engine/security/userns-remap/
title: Isolate containers with a user namespace
- sectiontitle: The basics
section:
- path: /engine/userguide/
title: Overview
- path: /engine/admin/
title: Configuring and running Docker
- path: /engine/admin/prometheus/
title: Collect Docker metrics with Prometheus
- path: /engine/admin/start-containers-automatically/
title: Start containers automatically
- path: /engine/admin/resource_constraints/
title: Limit a container's resources
- path: /engine/userguide/labels-custom-metadata/
title: Apply custom metadata
- path: /engine/admin/pruning/
title: Prune unused Docker objects
- path: /engine/admin/live-restore/
title: Keep containers alive during daemon downtime
- path: /engine/admin/systemd/
title: Control and configure Docker with systemd
- path: /engine/admin/formatting/
title: Format command and log output
- path: /registry/recipes/mirror/
title: Run a local registry mirror
nosync: true
- sectiontitle: Logging
section:
- path: /engine/admin/logging/view_container_logs/
title: View a container's logs
- path: /engine/admin/logging/overview/
title: Configuring logging drivers
- path: /engine/admin/logging/plugins/
title: Use a logging driver plugin
- path: /engine/admin/logging/log_tags/
title: Log tags for logging driver
- path: /engine/admin/logging/logentries/
title: Logentries logging driver
- path: /engine/admin/logging/json-file/
title: JSON File logging driver
- path: /engine/admin/logging/gelf/
title: Graylog Extended Format (GELF) logging driver
- path: /engine/admin/logging/syslog/
title: Syslog logging driver
- path: /engine/admin/logging/awslogs/
title: Amazon CloudWatch logs logging driver
- path: /engine/admin/logging/etwlogs/
title: ETW logging driver
- path: /engine/admin/logging/fluentd/
title: Fluentd logging driver
- path: /engine/admin/logging/gcplogs/
title: Google Cloud logging driver
- path: /engine/admin/logging/journald/
title: Journald logging driver
- path: /engine/admin/logging/splunk/
title: Splunk logging driver
- sectiontitle: Security
section:
- path: /engine/security/security/
title: Docker security
- path: /engine/security/non-events/
title: Docker security non-events
- path: /engine/security/https/
title: Protect the Docker daemon socket
- path: /engine/security/certificates/
title: Using certificates for repository client verification
- sectiontitle: Use trusted images
section:
- path: /engine/security/trust/content_trust/
title: Content trust in Docker
- path: /engine/security/trust/trust_automation/
title: Automation with content trust
- path: /engine/security/trust/trust_delegation/
title: Delegations for content trust
- path: /engine/security/trust/deploying_notary/
title: Deploying Notary
- path: /engine/security/trust/trust_key_mng/
title: Manage keys for content trust
- path: /engine/security/trust/trust_sandbox/
title: Play in a content trust sandbox
- path: /engine/security/apparmor/
title: AppArmor security profiles for Docker
- path: /engine/security/seccomp/
title: Seccomp security profiles for Docker
- path: /engine/security/userns-remap/
title: Isolate containers with a user namespace
- sectiontitle: Scale your app
section:
- path: /engine/swarm/
title: Swarm mode overview
- path: /engine/swarm/key-concepts/
title: Swarm mode key concepts
- sectiontitle: Get started with swarm mode
section:
- path: /engine/swarm/swarm-tutorial/
title: Set up for the tutorial
- path: /engine/swarm/swarm-tutorial/create-swarm/
title: Create a swarm
- path: /engine/swarm/swarm-tutorial/add-nodes/
title: Add nodes to the swarm
- path: /engine/swarm/swarm-tutorial/deploy-service/
title: Deploy a service
- path: /engine/swarm/swarm-tutorial/inspect-service/
title: Inspect the service
- path: /engine/swarm/swarm-tutorial/scale-service/
title: Scale the service
- path: /engine/swarm/swarm-tutorial/delete-service/
title: Delete the service
- path: /engine/swarm/swarm-tutorial/rolling-update/
title: Apply rolling updates
- path: /engine/swarm/swarm-tutorial/drain-node/
title: Drain a node
- path: /engine/swarm/ingress/
title: Use swarm mode routing mesh
- sectiontitle: How swarm mode works
section:
- path: /engine/swarm/how-swarm-mode-works/nodes/
title: How nodes work
- path: /engine/swarm/how-swarm-mode-works/services/
title: How services work
- path: /engine/swarm/how-swarm-mode-works/pki/
title: Manage swarm security with PKI
- path: /engine/swarm/swarm-mode/
title: Run Docker in swarm mode
- path: /engine/swarm/join-nodes/
title: Join nodes to a swarm
- path: /engine/swarm/manage-nodes/
title: Manage nodes in a swarm
- path: /engine/swarm/services/
title: Deploy services to a swarm
- path: /engine/swarm/configs/
title: Store service configuration data
- path: /engine/swarm/secrets/
title: Manage sensitive data with Docker secrets
- path: /engine/swarm/swarm_manager_locking/
title: Lock your swarm
- path: /engine/swarm/networking/
title: Manage swarm service networks
- path: /engine/swarm/admin_guide/
title: Swarm administration guide
- path: /engine/swarm/raft/
title: Raft consensus in swarm mode
- sectiontitle: Work with external tools
section:
- path: /engine/admin/dsc/
title: PowerShell DSC usage
- path: /engine/admin/ansible/
title: Using Ansible
- path: /engine/admin/chef/
title: Using Chef
- path: /engine/admin/puppet/
title: Using Puppet
- path: /engine/admin/multi-service_container/
title: Run multiple services in a container
- path: /engine/admin/runmetrics/
title: Runtime metrics
- path: /engine/admin/ambassador_pattern_linking/
title: Link via an ambassador container
- sectiontitle: Extend Docker
section:
- path: /engine/extend/
title: Managed plugin system
- path: /engine/extend/plugins_authorization/
title: Access authorization plugin
- path: /engine/extend/legacy_plugins/
title: Extending Docker with plugins
- path: /engine/extend/plugins_network/
title: Docker network driver plugins
- path: /engine/extend/plugins_volume/
title: Volume plugins
- title: Plugin configuration
path: /engine/extend/config/
- path: /engine/extend/plugin_api/
title: Plugins API
- sectiontitle: Standards and compliance
section:
- path: /compliance/
@ -420,27 +459,12 @@ guides:
title: FedRAMP
- path: /compliance/cis/
title: CIS
- sectiontitle: Extend Engine
section:
- path: /engine/extend/
title: Managed plugin system
- path: /engine/extend/plugins_authorization/
title: Access authorization plugin
- path: /engine/extend/legacy_plugins/
title: Extending Engine with plugins
- path: /engine/extend/plugins_network/
title: Docker network driver plugins
- path: /engine/extend/plugins_volume/
title: Volume plugins
- title: Plugin configuration
path: /engine/extend/config/
- path: /engine/extend/plugin_api/
title: Plugins API
- sectiontitle: Open source at Docker
section:
- path: /opensource/code/
title: Quickstart contribution
- sectiontitle: Set up for Engine development
- sectiontitle: Set up for Docker development
section:
- path: /opensource/project/who-written-for/
title: README first
@ -574,7 +598,7 @@ reference:
nosync: true
- title: Daemon CLI reference (dockerd)
path: /engine/reference/commandline/dockerd/
- sectiontitle: Engine API
- sectiontitle: Docker Engine API
section:
- path: /engine/api/
title: Overview
@ -614,7 +638,7 @@ reference:
title: v1.19 reference
- path: /engine/api/v1.18/
title: v1.18 reference
- sectiontitle: Engine (docker) CLI
- sectiontitle: Docker CLI
section:
- path: /engine/reference/run/
title: Docker run reference
@ -956,7 +980,7 @@ reference:
title: docker wait
- title: Edge daemon CLI reference (dockerd)
path: /edge/engine/reference/commandline/dockerd/
- sectiontitle: Docker Edge Engine (docker) CLI
- sectiontitle: Docker CLI (Edge)
section:
- path: /edge/engine/reference/run/
title: Docker run reference
@ -1995,7 +2019,7 @@ manuals:
- sectiontitle: Access DTR
section:
- path: /datacenter/dtr/2.3/guides/user/access-dtr/
title: Configure your Docker Engine
title: Configure your Docker daemon
- path: /datacenter/dtr/2.3/guides/user/access-dtr/configure-your-notary-client/
title: Configure your Notary client
- path: /datacenter/dtr/2.3/guides/user/access-dtr/use-a-cache/
@ -2131,7 +2155,7 @@ manuals:
- sectiontitle: Access DTR
section:
- path: /datacenter/dtr/2.2/guides/user/access-dtr/
title: Configure your Docker Engine
title: Configure your Docker daemon
- path: /datacenter/dtr/2.2/guides/user/access-dtr/configure-your-notary-client/
title: Configure your Notary client
- path: /datacenter/dtr/2.2/guides/user/access-dtr/use-a-cache/
@ -2223,7 +2247,7 @@ manuals:
- sectiontitle: Repositories and images
section:
- path: /datacenter/dtr/2.1/guides/repos-and-images/
title: Configure your Docker Engine
title: Configure your Docker daemon
- path: /datacenter/dtr/2.1/guides/repos-and-images/pull-an-image/
title: Pull an image
- path: /datacenter/dtr/2.1/guides/repos-and-images/push-an-image/
@ -2345,7 +2369,7 @@ manuals:
- sectiontitle: Repositories and images
section:
- path: /datacenter/dtr/2.0/repos-and-images/
title: Configure your Docker Engine
title: Configure your Docker daemon
- path: /datacenter/dtr/2.0/repos-and-images/pull-an-image/
title: Pull an image
- path: /datacenter/dtr/2.0/repos-and-images/push-an-image/
@ -2458,7 +2482,7 @@ manuals:
- path: /docker-cloud/infrastructure/ssh-into-a-node/
title: SSH into a Docker Cloud-managed node
- path: /docker-cloud/infrastructure/docker-upgrade/
title: Upgrade Docker Engine on a node
title: Upgrade Docker on a node
- path: /docker-cloud/infrastructure/byoh/
title: Use the Docker Cloud agent
- path: /docker-cloud/infrastructure/cloud-on-packet.net-faq/
@ -2911,7 +2935,7 @@ manuals:
title: CS Docker Engine
nosync: true
- path: /release-notes/docker-engine/
title: Docker Engine
title: Docker (1.13 and earlier)
- path: /docker-for-mac/release-notes/
title: Docker for Mac
nosync: true

125
develop/dev-best-practices.md Normal file
View File

@ -0,0 +1,125 @@
---
title: Docker development best practices
description: Rules of thumb for making your life easier as a Docker application developer
keywords: application, development
---
The following development patterns have proven to be helpful for people
building applications with Docker. If you have discovered something we should
add,
[let us know](https://github.com/docker/docker.github.io/issues/new){: target="_blank" class="_"}.
## How to keep your images small
Small images are faster to pull over the network and faster to load into
memory when starting containers or services. There are a few rules of thumb to
keep image size small:
- Start with an appropriate base image. For instance, if you need a JDK,
consider basing your image on the official `openjdk` image, rather than
starting with a generic `ubuntu` image and installing `openjdk` as part of the
Dockerfile.
- [Use multistage builds](/engine/userguide/eng-image/multistage-build.md). For
instance, you can use the `maven` image to build your Java application, then
reset to the `tomcat` image and copy the Java artifacts into the correct
location to deploy your app, all in the same Dockerfile. This means that your
final image doesn't include all of the libraries and dependencies pulled in by
the build, but only the artifacts and the environment needed to run them.
- If you need to use a version of Docker that does not include multistage
builds, try to reduce the number of layers in your image by minimizing the
number of separate `RUN` commands in your Dockerfile. You can do this by
consolidating multiple commands into a single `RUN` line and using your
shell's mechanisms to combine them together. Consider the following two
fragments. The first will create two layers in the image, while the second
will only create one.
```conf
RUN apt-get -y update
RUN apt-get install -y python
```
```conf
RUN apt-get -y update && apt-get install -y python
```
- If you have multiple images with a lot in common, consider creating your own
[base image](/engine/userguide/eng-image/baseimages.md) with the shared
components, and basing your unique images on that. Docker only needs to load
the common layers once, and they will be cached. This means that your
derivative images use memory on the Docker host more efficiently and load more
quickly.
- To keep your production image lean but allow for debugging, consider using the
production image as the base image for the debug image. Additional testing or
debugging tooling can be added on top of the production image.
- When building images, always tag them with useful tags which codify version
information, intended destination (`prod` or `test`, for instance), stability,
or other information that will be useful when deploying the application in
different environments. Do not rely on the automatically-created `latest` tag.
## Where and how to persist application data
- **Avoid** storing application data in your container's writable layer using
[storage drivers](/engine/userguide/storagedriver.md). This increases the
size of your container and is less efficient from an I/O perspective than
using volumes or bind mounts.
- Instead, store data using [volumes](/engine/admin/volumes/volumes.md).
- One case where it is appropriate to use
[bind mounts](/engine/admin/volumes/bind-mounts.md) is during development,
when you may want to mount your source directory or a binary you just built
into your container. For production, use a volume instead, mounting it into
the same location as you mounted a bind mount during development.
- For production, use [secrets](/engine/swarm/secrets.md) to store sensitive
application data used by services, and use [configs](/engine/swarm/configs.md)
for non-sensitive data such as configuration files. If you currently use
standalone constainers, consider migrating to use single-replica services, so
that you can take advantage of these service-only features.
## Use swarm services when possible
- When possible, design your application to be able to scale using swarm
services.
- Even if you only need to run a single instance of your application, swarm
services provide several advantages over standalone containers. A service's
configuration is declarative, and Docker is always working to keep the
desired and actual state in sync.
- Networks and volumes can be connected and disconnected from swarm services,
and Docker handles redeploying the individual service containers in a
non-disruptive way. Standalone containers need to be manually stopped, removed,
and recreated to accommodate configuration changes.
- Several features, such as the ability to store
[secrets](/engine/swarm/secrets.md) and [configs](/engine/swarm/configs.md),
are only available to services rather than standalone containers. These
features allow you to keep your images as generic as possible and to avoid
storing sensitive data within the Docker images or containers themselves.
There are limitations around sharing data amongst nodes of a swarm service.
If you use [Docker for AWS](/docker-for-aws/persistent-data-volumes.md) or
[Docker for Azure](docker-for-azure/persistent-data-volumes.md), you can use the
Cloudstor plugin to share data amongst your swarm service nodes. You can also
write your application data into a separate database which supports simultaneous
updates.
## Use CI/CD for testing and deployment
- When you check a change into source control or create a pull request, use
[Docker Cloud](/docker-cloud/builds/automated-build.md) or
another CI/CD pipeline to automatically build and tag a Docker image and test
it. Docker Cloud can also deploy tested apps straight into production.
- Take this even further with [Docker EE](/enterprise/index.md) by requiring
your development, testing, and security teams to sign images before they can
be deployed into production. This way, you can be sure that before an image is
deployed into production, it has been tested and signed off by, for instance,
development, quality, and security teams.
## Differences in development and production environments
| Development | Production |
|:--------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Use bind mounts to give your container access to your source code. | Use volumes to store container data. |
| Use Docker for Mac or Docker for Windows. | Use Docker EE if possible, with [userns mapping](/engine/security/userns-remap.md) for greater isolation of Docker processes from host processes. |
| Don't worry about time drift. | Always run an NTP client on the Docker host and within each container process and sync them all to the same NTP server. If you use swarm services, also ensure that each Docker node syncs its clocks to the same time source as the containers. |

34
develop/index.md Normal file
View File

@ -0,0 +1,34 @@
---
title: Develop with Docker
description: Overview of developer resources
keywords: developer, developing, apps, api, sdk
---
This page lists resources for application developers using Docker.
## Develop new apps on Docker
If you're just getting started developing a brand new app on Docker, check out
these resources to understand some of the most common patterns for getting the
most benefits from Docker.
- Learn to [build an image from a Dockerfile](/get-started/part2.md){: target="_blank" class="_"}
- Use [multistage builds](/engine/userguide/eng-image/multistage-build.md){: target="_blank" class="_"} to keep your images lean
- Manage application data using [volumes](/engine/admin/volumes/volumes.md) and [bind mounts](/engine/admin/volumes/bind-mounts.md){: target="_blank" class="_"}
- [Scale your app](/get-started/part3.md){: target="_blank" class="_"} as a swarm service
- [Define your app stack](/get-started/part5.md){: target="_blank" class="_"} using a compose file
- General application development best practices
## Learn about language-specific app development with Docker
- [Docker for Java developers](https://github.com/docker/labs/tree/master/developer-tools/java/){: target="_blank" class="_"} lab
- [Port a node.js app to Docker](https://github.com/docker/labs/tree/master/developer-tools/nodejs/porting){: target="_blank" class="_"}
- [Ruby on Rails app on Docker](https://github.com/docker/labs/tree/master/developer-tools/ruby){: target="_blank" class="_"} lab
- [Dockerize a .Net Core application](/engine/examples/dotnetcore/){: target="_blank" class="_"}
- [Dockerize an ASP.NET Core application with SQL Server on Linux](/compose/aspnet-mssql-compose/){: target="_blank" class="_"} using Docker Compose
## Advanced development with the SDK or API
When you're comfortable developing apps by writing Dockerfiles or compose files
and using the Docker CLI, you can take it to the next level by using the Docker
Engine SDK for Go or Python or using the HTTP API directly.

768
develop/sdk/examples.md Normal file
View File

@ -0,0 +1,768 @@
---
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](/engine/installation.md), you can
[install the Go and Python SDKs](/develop/api/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 (
"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.NewEnvClient()
if err != nil {
panic(err)
}
_, err = cli.ImagePull(ctx, "docker.io/library/alpine", types.ImagePullOptions{})
if err != nil {
panic(err)
}
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)
}
io.Copy(os.Stdout, 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.NewEnvClient()
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() {
cli, err := client.NewEnvClient()
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 will stop, but Docker will create 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.NewEnvClient()
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.NewEnvClient()
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 images`:
<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() {
cli, err := client.NewEnvClient()
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.NewEnvClient()
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 fadee" 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.NewEnvClient()
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 will leave 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.NewEnvClient()
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 -->

261
develop/sdk/index.md Normal file
View File

@ -0,0 +1,261 @@
---
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 won'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
```
[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/).
## Versioned API and SDK
The version of the Docker 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 will be 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 will 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).
### 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, but do specify the
version you are using. This helps prevent surprises.
- If you need a new feature, update your code use at least the oldest version
that supports the feature, and prefer the latest version you are able to 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" markdown="1">
```go
package main
import (
"io"
"os"
"github.com/docker/docker/client"
"github.com/docker/docker/api/types"
"github.com/docker/docker/api/types/container"
"golang.org/x/net/context"
)
func main() {
ctx := context.Background()
cli, err := client.NewEnvClient()
if err != nil {
panic(err)
}
_, err = cli.ImagePull(ctx, "docker.io/library/alpine", types.ImagePullOptions{})
if err != nil {
panic(err)
}
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)
}
io.Copy(os.Stdout, out)
}
```
</div>
<div id="python" class="tab-pane fade in active" 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](getting-started.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) |
| NodeJS | [dockerode](https://github.com/apocas/dockerode) |
| 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) |

803
engine/api/get-started.md
View File

@ -1,803 +0,0 @@
---
title: Get started with the Docker API
keywords: developing, api, sdk, developers, rest, curl, python, go
redirect_from:
- /engine/api/getting-started/
---
After you
[install Docker](/engine/installation.md), you can try out the Docker API.
Optionally, install an SDK for the language you are using. Official SDKs are
available for Python and Go, and a number of community maintained
libraries for other languages.
[Learn more about installing and using Docker SDKs](sdks.md).
These examples show how to perform the same operation using Python, Go, or
by using `curl` directly.
## Versioned API
The Python and Go examples used here do not specify the API version to use,
because they use features that have been part of Docker for a long time. The
Docker API is fully backward compatible.
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 `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/`.
- For the SDKs, or to force the Docker CLI to use a specific version of the API,
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).
## API Examples
### 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-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-run-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-run-curl" data-group="curl">Curl</a></li>
</ul>
<div class="tab-content">
<div id="tab-run-python" class="tab-pane fade in active" markdown="1">
```python
import docker
client = docker.from_env()
print client.containers.run("alpine", ["echo", "hello", "world"])
```
</div>
<div id="tab-run-go" class="tab-pane fade" markdown="1">
```go
package main
import (
"io"
"os"
"github.com/docker/docker/client"
"github.com/docker/docker/api/types"
"github.com/docker/docker/api/types/container"
"golang.org/x/net/context"
)
func main() {
ctx := context.Background()
cli, err := client.NewEnvClient()
if err != nil {
panic(err)
}
_, err = cli.ImagePull(ctx, "docker.io/library/alpine", types.ImagePullOptions{})
if err != nil {
panic(err)
}
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)
}
if _, err = cli.ContainerWait(ctx, resp.ID); err != nil {
panic(err)
}
out, err := cli.ContainerLogs(ctx, resp.ID, types.ContainerLogsOptions{ShowStdout: true})
if err != nil {
panic(err)
}
io.Copy(os.Stdout, out)
}
```
</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-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-rundetach-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-rundetach-curl" data-group="curl">Curl</a></li>
</ul>
<div class="tab-content">
<div id="tab-rundetach-python" class="tab-pane fade in active" 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-go" class="tab-pane fade" 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.NewEnvClient()
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-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-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-listcontainers-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-listcontainers-curl" data-group="curl">Curl</a></li>
</ul>
<div class="tab-content">
<div id="tab-listcontainers-python" class="tab-pane fade in active" markdown="1">
```python
import docker
client = docker.from_env()
for container in client.containers.list():
print container.id
```
</div>
<div id="tab-listcontainers-go" class="tab-pane fade" markdown="1">
```go
package main
import (
"context"
"fmt"
"github.com/docker/docker/api/types"
"github.com/docker/docker/client"
)
func main() {
cli, err := client.NewEnvClient()
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-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. For
example, to stop all running containers:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab-stopcontainers-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-stopcontainers-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-stopcontainers-curl" data-group="curl">Curl</a></li>
</ul>
<div class="tab-content">
<div id="tab-stopcontainers-python" class="tab-pane fade in active" markdown="1">
```python
import docker
client = docker.from_env()
for container in client.containers.list():
container.stop()
```
</div>
<div id="tab-stopcontainers-go" class="tab-pane fade in" markdown="1">
```go
package main
import (
"context"
"github.com/docker/docker/api/types"
"github.com/docker/docker/client"
)
func main() {
ctx := context.Background()
cli, err := client.NewEnvClient()
if err != nil {
panic(err)
}
containers, err := cli.ContainerList(ctx, types.ContainerListOptions{})
if err != nil {
panic(err)
}
for _, container := range containers {
if err := cli.ContainerStop(ctx, container.ID, nil); err != nil {
panic(err)
}
}
}
```
</div>
<div id="tab-stopcontainers-curl" class="tab-pane fade in" 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:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab-containerlogs-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-containerlogs-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-containerlogs-curl" data-group="curl">Curl</a></li>
</ul>
<div class="tab-content">
<div id="tab-containerlogs-python" class="tab-pane fade in active" markdown="1">
```python
import docker
client = docker.from_env()
container = client.containers.get('f1064a8a4c82')
print container.logs()
```
</div>
<div id="tab-containerlogs-go" class="tab-pane fade in" markdown="1">
```go
package main
import (
"context"
"io"
"os"
"github.com/docker/docker/api/types"
"github.com/docker/docker/client"
)
func main() {
ctx := context.Background()
cli, err := client.NewEnvClient()
if err != nil {
panic(err)
}
options := types.ContainerLogsOptions{ShowStdout: true}
out, err := cli.ContainerLogs(ctx, "f1064a8a4c82", options)
if err != nil {
panic(err)
}
io.Copy(os.Stdout, out)
}
```
</div>
<div id="tab-containerlogs-curl" class="tab-pane fade in" 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 images`:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab-listimages-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-listimages-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-listimages-curl" data-group="curl">Curl</a></li>
</ul>
<div class="tab-content">
<div id="tab-listimages-python" class="tab-pane fade in active" markdown="1">
```python
import docker
client = docker.from_env()
for image in client.images.list():
print image.id
```
</div>
<div id="tab-listimages-go" class="tab-pane fade" markdown="1">
```go
package main
import (
"context"
"fmt"
"github.com/docker/docker/api/types"
"github.com/docker/docker/client"
)
func main() {
cli, err := client.NewEnvClient()
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-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 images
Pull images, like `docker pull`:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab-pullimages-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-pullimages-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-pullimages-curl" data-group="curl">Curl</a></li>
</ul>
<div class="tab-content">
<div id="tab-pullimages-python" class="tab-pane fade in active" markdown="1">
```python
import docker
client = docker.from_env()
image = client.images.pull("alpine")
print image.id
```
</div>
<div id="tab-pullimages-go" class="tab-pane fade" 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.NewEnvClient()
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-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 images with authentication
Pull images, 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-python" data-group="python">Python</a></li>
<li><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-curl" data-group="curl">Curl</a></li>
</ul>
<div class="tab-content">
<div id="tab-pullimages-auth-python" class="tab-pane fade in active" 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-auth-go" class="tab-pane fade" markdown="1">
```go
package main
import (
"io"
"os"
"encoding/json"
"encoding/base64"
"github.com/docker/docker/api/types"
"github.com/docker/docker/client"
"golang.org/x/net/context"
)
func main() {
ctx := context.Background()
cli, err := client.NewEnvClient()
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-curl" class="tab-pane fade" markdown="1">
This example will leave 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 containers
Commit containers to create images from their contents:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab-commit-python" data-group="python">Python</a></li>
<li><a data-toggle="tab" data-target="#tab-commit-go" data-group="go">Go</a></li>
<li><a data-toggle="tab" data-target="#tab-commit-curl" data-group="curl">Curl</a></li>
</ul>
<div class="tab-content">
<div id="tab-commit-python" class="tab-pane fade in active" 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-go" class="tab-pane fade" 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.NewEnvClient()
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)
}
if _, err = cli.ContainerWait(ctx, createResp.ID); err != nil {
panic(err)
}
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-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 -->
## Next steps
- [Full documentation for the Python SDK](https://docker-py.readthedocs.io)
- [Full documentation for the Go SDK](https://godoc.org/github.com/moby/moby/client)
- [Full documentation for the HTTP API](/engine/api/v1.27/)

146
engine/api/index.md
View File

@ -1,146 +0,0 @@
---
title: Docker Engine API and SDKs
redirect_from:
- /engine/reference/api/
- /engine/reference/api/docker_remote_api/
- /reference/api/
- /reference/api/docker_remote_api/
---
The Engine API is the API served by Docker Engine. It allows you to control
every aspect of Docker from within your own applications, build tools to manage
and monitor applications running on Docker, and even use it to build apps on
Docker itself.
It is the API the Docker client uses to communicate with the Engine, so
everything the Docker client can do can be done with the API. For example:
* Running and managing containers
* Managing Swarm nodes and services
* Reading logs and metrics
* Creating and managing Swarms
* Pulling and managing images
* Managing networks and volumes
The API can be accessed with any HTTP client, but we also provide
Python and Go [SDKs](sdks.md).
## Versioned API
The version of the API you should use depends upon the version of your Docker
daemon. 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
```
## API example
As an example, the `docker run` command can be easily implemented in various
programming languages and by hitting the API directly with `curl`:
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#python">Python</a></li>
<li><a data-toggle="tab" data-target="#go">Go</a></li>
<li><a data-toggle="tab" data-target="#curl">curl</a></li>
</ul>
<div class="tab-content">
<div id="python" class="tab-pane fade in active">
{% highlight python %}
import docker
client = docker.from_env()
print client.containers.run("alpine", ["echo", "hello", "world"])
{% endhighlight %}
</div>
<div id="go" class="tab-pane fade">
{% highlight go %}
package main
import (
"io"
"os"
"github.com/moby/moby/client"
"github.com/moby/moby/api/types"
"github.com/moby/moby/api/types/container"
"golang.org/x/net/context"
)
func main() {
ctx := context.Background()
cli, err := client.NewEnvClient()
if err != nil {
panic(err)
}
_, err = cli.ImagePull(ctx, "docker.io/library/alpine", types.ImagePullOptions{})
if err != nil {
panic(err)
}
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)
}
if _, err = cli.ContainerWait(ctx, resp.ID); err != nil {
panic(err)
}
out, err := cli.ContainerLogs(ctx, resp.ID, types.ContainerLogsOptions{ShowStdout: true})
if err != nil {
panic(err)
}
io.Copy(os.Stdout, out)
}
{% endhighlight %}
</div>
<div id="curl" class="tab-pane fade">
{% highlight 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
{% endhighlight %}
</div>
</div>
To learn more, take a look at the [getting started guide](getting-started.md).

61
engine/api/sdks.md
View File

@ -1,61 +0,0 @@
---
title: SDKs for Docker Engine API
description: Client libraries for the Docker Engine API.
keywords: API, SDK, library, Docker, index, registry, REST, documentation, clients, C#, Erlang, Go, Groovy, Java, JavaScript, Perl, PHP, Python, Ruby, Rust, Scala
redirect_from:
- /engine/api/client-libraries/
- /engine/reference/api/remote_api_client_libraries/
- /reference/api/remote_api_client_libraries/
---
The Docker SDKs allow you to build applications that can control and manage the Docker Engine. They are interfaces for the [Docker Engine API](index.md), but also contain a number of tools to make it easier to work with the API.
There are official libraries available in Python and Go, and there are a number of community supported libraries for other languages.
## Python
The Docker SDK for Python is available on the Python Package Index (PyPI), and can be installed with PIP:
$ pip install docker
To see how to start using it, [head to the getting started guide](getting-started.md).
For a full reference, see the [Docker SDK for Python documentation](https://docker-py.readthedocs.io).
## Go
The Docker SDK for Go is a package inside the Docker Engine repository. To use it, you import it:
{% highlight go %}
import "github.com/docker/docker/client"
{% endhighlight %}
To see how to start using it, [head to the getting started guide](getting-started.md).
[A full reference is available on GoDoc.](https://godoc.org/github.com/moby/moby/client)
## Other languages
There are a number of community supported libraries available for other languages. They have not been tested by the Docker maintainers for compatibility, 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) |
| NodeJS | [dockerode](https://github.com/apocas/dockerode) |
| 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) |

53
engine/userguide/index.md
View File

@ -1,52 +1,13 @@
---
description: How to use the Docker Engine user guide
keywords: engine, introduction, documentation, about, technology, docker, user, guide, framework, home, intro
title: Docker Engine user guide
keywords: docker, overview
title: Configure and use Docker
redirect_from:
- /engine/userguide/intro/
---
This guide helps users learn how to use Docker Engine.
## Learn by example
- [Network containers](/engine/tutorials/networkingcontainers.md)
- [Manage data in containers](/engine/tutorials/dockervolumes.md)
- [Samples](/samples/)
- [Get started](/get-started/)
## Work with images
- [Best practices for writing Dockerfiles](eng-image/dockerfile_best-practices.md)
- [Create a base image](eng-image/baseimages.md)
- [Image management](eng-image/image_management.md)
## Manage storage drivers
- [Understand images, containers, and storage drivers](storagedriver/imagesandcontainers.md)
- [Select a storage driver](storagedriver/selectadriver.md)
- [AUFS storage in practice](storagedriver/aufs-driver.md)
- [Btrfs storage in practice](storagedriver/btrfs-driver.md)
- [Device Mapper storage in practice](storagedriver/device-mapper-driver.md)
- [OverlayFS storage in practice](storagedriver/overlayfs-driver.md)
- [ZFS storage in practice](storagedriver/zfs-driver.md)
## Configure networks
- [Understand Docker container networks](networking/index.md)
- [Embedded DNS server in user-defined networks](networking/configure-dns.md)
- [Get started with multi-host networking](networking/get-started-overlay.md)
- [Work with network commands](networking/work-with-networks.md)
### Work with the default network
- [Understand container communication](networking/default_network/container-communication.md)
- [Legacy container links](networking/default_network/dockerlinks.md)
- [Binding container ports to the host](networking/default_network/binding.md)
- [Build your own bridge](networking/default_network/build-bridges.md)
- [Configure container DNS](networking/default_network/configure-dns.md)
- [Customize the docker0 bridge](networking/default_network/custom-docker0.md)
- [IPv6 with Docker](networking/default_network/ipv6.md)
## Misc
- [Apply custom metadata](labels-custom-metadata.md)
After you've [installed Docker](/engine/installation/) and completed the
[Getting started guides](/get-started/), you're ready to take it to the next
level. The topics in this section show how to develop and design your app,
store your app's data, and get your app running in a scalable, secure, robust
production environment.