clearlinux/docker
2
0
Fork 0
mirror of https://github.com/clearlinux/docker.git synced 2026-10-04 07:48:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs auto-conversion fixes and MD marking and structure improvements.

Browse Source 
- Remove redundant chars and all errors caused by RST->MD conversion.
   e.g. [/#, /\, \<, />, etc.]
 - Fix broken inter-document links
 - Fix outbound links no-longer active or changed
 - Fix lists
 - Fix code blocks
 - Correct apostrophes
 - Replace redundant inline note marks for code with code marks
 - Fix broken image links
 - Remove non-functional title links
 - Correct broken cross-docs links
 - Improve readability

Note: This PR does not try to fix/amend:

 - Grammatical errors
 - Lexical errors
 - Linguistic-logic errors etc.

It just aims to fix main structural or conversion errors to serve as
a base for further amendments that will cover others including but
not limited to those mentioned above.

Docker-DCO-1.1-Signed-off-by: O.S. Tezer <ostezer@gmail.com> (github: ostezer)

Update:

 - Fix backtick issues

Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au> (github: SvenDowideit)
This commit is contained in:
O.S.Tezer
2014-04-24 22:19:32 +10:00
committed by Sven Dowideit
parent 83b388c979
commit c932667cd2
87 changed files with 4408 additions and 4191 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/reference/api/README.md
+7 -4
View File
@@ -1,6 +1,9 @@
This directory holds the authoritative specifications of APIs defined and implemented by Docker. Currently this includes:
* The remote API by which a docker node can be queried over HTTP
* The registry API by which a docker node can download and upload container images for storage and sharing
* The index search API by which a docker node can search the public index for images to download
* The docker.io OAuth and accounts API which 3rd party services can use to access account information
* The remote API by which a docker node can be queried over HTTP
* The registry API by which a docker node can download and upload
container images for storage and sharing
* The index search API by which a docker node can search the public
index for images to download
* The docker.io OAuth and accounts API which 3rd party services can
use to access account information
docs/sources/reference/api/archive/docker_remote_api_v1.0.md
+130 -107
View File
@@ -2,9 +2,9 @@ page_title: Remote API v1.0
page_description: API Documentation for Docker
page_keywords: API, Docker, rcli, REST, documentation
# [Docker Remote API v1.0](#id1)
# Docker Remote API v1.0
## [1. Brief introduction](#id2)
# 1. Brief introduction
- The Remote API is replacing rcli
- Default port in the docker daemon is 4243
@@ -12,14 +12,15 @@ page_keywords: API, Docker, rcli, REST, documentation
or pull, the HTTP connection is hijacked to transport stdout stdin
and stderr
## [2. Endpoints](#id3)
# 2. Endpoints
### [2.1 Containers](#id4)
## 2.1 Containers
#### [List containers](#id5)
### List containers
`GET /containers/json`
: List containers
`GET /containers/json`
List containers
**Example request**:
@@ -80,10 +81,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create a container](#id6)
### Create a container
`POST /containers/create`
: Create a container
`POST /containers/create`
Create a container
**Example request**:
@@ -126,7 +128,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **config** – the container’s configuration
- **config** – the container's configuration
Status Codes:
@@ -135,10 +137,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **406** – impossible to attach (container not running)
- **500** – server error
#### [Inspect a container](#id7)
### Inspect a container
`GET /containers/`(*id*)`/json`
: Return low-level information on the container `id`
`GET /containers/(id)/json`
Return low-level information on the container `id`
**Example request**:
@@ -202,10 +205,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Inspect changes on a container’s filesystem](#id8)
### Inspect changes on a container's filesystem
`GET /containers/`(*id*)`/changes`
: Inspect changes on container `id` ‘s filesystem
`GET /containers/(id)/changes`
Inspect changes on container `id`'s filesystem
**Example request**:
@@ -237,10 +241,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Export a container](#id9)
### Export a container
`GET /containers/`(*id*)`/export`
: Export the contents of container `id`
`GET /containers/(id)/export`
Export the contents of container `id`
**Example request**:
@@ -259,10 +264,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Start a container](#id10)
### Start a container
`POST /containers/`(*id*)`/start`
: Start the container `id`
`POST /containers/(id)/start`
Start the container `id`
**Example request**:
@@ -278,10 +284,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Stop a container](#id11)
### Stop a container
`POST /containers/`(*id*)`/stop`
: Stop the container `id`
`POST /containers/(id)/stop`
Stop the container `id`
**Example request**:
@@ -303,10 +310,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Restart a container](#id12)
### Restart a container
`POST /containers/`(*id*)`/restart`
: Restart the container `id`
`POST /containers/(id)/restart`
Restart the container `id`
**Example request**:
@@ -328,10 +336,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Kill a container](#id13)
### Kill a container
`POST /containers/`(*id*)`/kill`
: Kill the container `id`
`POST /containers/(id)/kill`
Kill the container `id`
**Example request**:
@@ -347,10 +356,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Attach to a container](#id14)
### Attach to a container
`POST /containers/`(*id*)`/attach`
: Attach to the container `id`
`POST /containers/(id)/attach`
Attach to the container `id`
**Example request**:
@@ -385,11 +395,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Wait a container](#id15)
### Wait a container
`POST /containers/`(*id*)`/wait`
: Block until container `id` stops, then returns
the exit code
`POST /containers/(id)/wait`
Block until container `id` stops, then returns the exit code
**Example request**:
@@ -408,10 +418,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Remove a container](#id16)
### Remove a container
`DELETE /containers/`(*id*)
: Remove the container `id` from the filesystem
`DELETE /containers/(id)`
Remove the container `id` from the filesystem
**Example request**:
@@ -435,13 +446,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
### [2.2 Images](#id17)
## 2.2 Images
#### [List Images](#id18)
### List Images
`GET /images/`(*format*)
: List images `format` could be json or viz (json
default)
`GET /images/(format)`
List images `format` could be json or viz (json default)
**Example request**:
@@ -507,11 +518,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create an image](#id19)
### Create an image
`POST /images/create`
: Create an image, either by pull it from the registry or by importing
it
`POST /images/create`
Create an image, either by pull it from the registry or by importing it
**Example request**:
@@ -539,11 +550,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Insert a file in an image](#id20)
### Insert a file in an image
`POST /images/`(*name*)`/insert`
: Insert a file from `url` in the image
`name` at `path`
`POST /images/(name)/insert`
Insert a file from `url` in the image `name` at `path`
**Example request**:
@@ -560,10 +571,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Inspect an image](#id21)
### Inspect an image
`GET /images/`(*name*)`/json`
: Return low-level information on the image `name`
`GET /images/(name)/json`
Return low-level information on the image `name`
**Example request**:
@@ -607,10 +619,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Get the history of an image](#id22)
### Get the history of an image
`GET /images/`(*name*)`/history`
: Return the history of the image `name`
`GET /images/(name)/history`
Return the history of the image `name`
**Example request**:
@@ -640,10 +653,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Push an image on the registry](#id23)
### Push an image on the registry
`POST /images/`(*name*)`/push`
: Push the image `name` on the registry
`POST /images/(name)/push`
Push the image `name` on the registry
> **Example request**:
>
@@ -668,10 +682,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Tag an image into a repository](#id24)
### Tag an image into a repository
`POST /images/`(*name*)`/tag`
: Tag the image `name` into a repository
`POST /images/(name)/tag`
Tag the image `name` into a repository
**Example request**:
@@ -695,10 +710,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Remove an image](#id25)
### Remove an image
`DELETE /images/`(*name*)
: Remove the image `name` from the filesystem
`DELETE /images/(name)`
Remove the image `name` from the filesystem
**Example request**:
@@ -714,10 +730,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Search images](#id26)
### Search images
`GET /images/search`
: Search for an image in the docker index
`GET /images/search`
Search for an image in the docker index
**Example request**:
@@ -747,12 +764,13 @@ page_keywords: API, Docker, rcli, REST, documentation
:statuscode 200: no error
:statuscode 500: server error
### [2.3 Misc](#id27)
## 2.3 Misc
#### [Build an image from Dockerfile via stdin](#id28)
### Build an image from Dockerfile via stdin
`POST /build`
: Build an image from Dockerfile via stdin
`POST /build`
Build an image from Dockerfile via stdin
**Example request**:
@@ -778,10 +796,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Get default username and email](#id29)
### Get default username and email
`GET /auth`
: Get the default username and email
`GET /auth`
Get the default username and email
**Example request**:
@@ -802,10 +821,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Check auth configuration and store it](#id30)
### Check auth configuration and store it
`POST /auth`
: Get the default username and email
`POST /auth`
Get the default username and email
**Example request**:
@@ -828,10 +848,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **204** – no error
- **500** – server error
#### [Display system-wide information](#id31)
### Display system-wide information
`GET /info`
: Display system-wide information
`GET /info`
Display system-wide information
**Example request**:
@@ -857,10 +878,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Show the docker version information](#id32)
### Show the docker version information
`GET /version`
: Show the docker version information
`GET /version`
Show the docker version information
**Example request**:
@@ -882,10 +904,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Create a new image from a container’s changes](#id33)
### Create a new image from a container's changes
`POST /commit`
: Create a new image from a container’s changes
`POST /commit`
Create a new image from a container's changes
>
> **Example request**:
@@ -913,7 +936,7 @@ page_keywords: API, Docker, rcli, REST, documentation
- **tag** – tag
- **m** – commit message
- **author** – author (eg. "John Hannibal Smith
\<[hannibal@a-team.com](mailto:hannibal%40a-team.com)\>")
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
Status Codes:
@@ -921,28 +944,28 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
## [3. Going further](#id34)
# 3. Going further
### [3.1 Inside ‘docker run’](#id35)
## 3.1 Inside `docker run`
Here are the steps of ‘docker run’ :
Here are the steps of `docker run` :
- Create the container
- Create the container
- If the status code is 404, it means the image doesn’t exists:
: - Try to pull it
- Then retry to create the container
- If the status code is 404, it means the image doesn't exists:
- Try to pull it
- Then retry to create the container
- Start the container
- Start the container
- If you are not in detached mode:
: - Attach to the container, using logs=1 (to have stdout and
stderr from the container’s start) and stream=1
- If you are not in detached mode:
- Attach to the container, using logs=1 (to have stdout and
stderr from the container's start) and stream=1
- If in detached mode or only stdin is attached:
: - Display the container’s id
- If in detached mode or only stdin is attached:
- Display the container's
### [3.2 Hijacking](#id36)
## 3.2 Hijacking
In this first version of the API, some of the endpoints, like /attach,
/pull or /push uses hijacking to transport stdin, stdout and stderr on
docs/sources/reference/api/archive/docker_remote_api_v1.1.md
+130 -107
View File
@@ -2,9 +2,9 @@ page_title: Remote API v1.1
page_description: API Documentation for Docker
page_keywords: API, Docker, rcli, REST, documentation
# [Docker Remote API v1.1](#id1)
# Docker Remote API v1.1
## [1. Brief introduction](#id2)
# 1. Brief introduction
- The Remote API is replacing rcli
- Default port in the docker daemon is 4243
@@ -12,14 +12,15 @@ page_keywords: API, Docker, rcli, REST, documentation
or pull, the HTTP connection is hijacked to transport stdout stdin
and stderr
## [2. Endpoints](#id3)
# 2. Endpoints
### [2.1 Containers](#id4)
## 2.1 Containers
#### [List containers](#id5)
### List containers
`GET /containers/json`
: List containers
`GET /containers/json`
List containers
**Example request**:
@@ -80,10 +81,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create a container](#id6)
### Create a container
`POST /containers/create`
: Create a container
`POST /containers/create`
Create a container
**Example request**:
@@ -126,7 +128,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **config** – the container’s configuration
- **config** – the container's configuration
Status Codes:
@@ -135,10 +137,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **406** – impossible to attach (container not running)
- **500** – server error
#### [Inspect a container](#id7)
### Inspect a container
`GET /containers/`(*id*)`/json`
: Return low-level information on the container `id`
`GET /containers/(id)/json`
Return low-level information on the container `id`
**Example request**:
@@ -202,10 +205,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Inspect changes on a container’s filesystem](#id8)
### Inspect changes on a container's filesystem
`GET /containers/`(*id*)`/changes`
: Inspect changes on container `id` ‘s filesystem
`GET /containers/(id)/changes`
Inspect changes on container `id`'s filesystem
**Example request**:
@@ -237,10 +241,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Export a container](#id9)
### Export a container
`GET /containers/`(*id*)`/export`
: Export the contents of container `id`
`GET /containers/(id)/export`
Export the contents of container `id`
**Example request**:
@@ -259,10 +264,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Start a container](#id10)
### Start a container
`POST /containers/`(*id*)`/start`
: Start the container `id`
`POST /containers/(id)/start`
Start the container `id`
**Example request**:
@@ -278,10 +284,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Stop a container](#id11)
### Stop a container
`POST /containers/`(*id*)`/stop`
: Stop the container `id`
`POST /containers/(id)/stop`
Stop the container `id`
**Example request**:
@@ -303,10 +310,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Restart a container](#id12)
### Restart a container
`POST /containers/`(*id*)`/restart`
: Restart the container `id`
`POST /containers/(id)/restart`
Restart the container `id`
**Example request**:
@@ -328,10 +336,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Kill a container](#id13)
### Kill a container
`POST /containers/`(*id*)`/kill`
: Kill the container `id`
`POST /containers/(id)/kill`
Kill the container `id`
**Example request**:
@@ -347,10 +356,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Attach to a container](#id14)
### Attach to a container
`POST /containers/`(*id*)`/attach`
: Attach to the container `id`
`POST /containers/(id)/attach`
Attach to the container `id`
**Example request**:
@@ -385,11 +395,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Wait a container](#id15)
### Wait a container
`POST /containers/`(*id*)`/wait`
: Block until container `id` stops, then returns
the exit code
`POST /containers/(id)/wait`
Block until container `id` stops, then returns the exit code
**Example request**:
@@ -408,10 +418,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Remove a container](#id16)
### Remove a container
`DELETE /containers/`(*id*)
: Remove the container `id` from the filesystem
`DELETE /containers/(id)`
Remove the container `id` from the filesystem
**Example request**:
@@ -435,13 +446,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
### [2.2 Images](#id17)
## 2.2 Images
#### [List Images](#id18)
### List Images
`GET /images/`(*format*)
: List images `format` could be json or viz (json
default)
`GET /images/(format)`
List images `format` could be json or viz (json default)
**Example request**:
@@ -507,11 +518,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create an image](#id19)
### Create an image
`POST /images/create`
: Create an image, either by pull it from the registry or by importing
it
`POST /images/create`
Create an image, either by pull it from the registry or by importing it
**Example request**:
@@ -542,11 +553,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Insert a file in an image](#id20)
### Insert a file in an image
`POST /images/`(*name*)`/insert`
: Insert a file from `url` in the image
`name` at `path`
`POST /images/(name)/insert`
Insert a file from `url` in the image `name` at `path`
**Example request**:
@@ -567,10 +578,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Inspect an image](#id21)
### Inspect an image
`GET /images/`(*name*)`/json`
: Return low-level information on the image `name`
`GET /images/(name)/json`
Return low-level information on the image `name`
**Example request**:
@@ -614,10 +626,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Get the history of an image](#id22)
### Get the history of an image
`GET /images/`(*name*)`/history`
: Return the history of the image `name`
`GET /images/(name)/history`
Return the history of the image `name`
**Example request**:
@@ -647,10 +660,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Push an image on the registry](#id23)
### Push an image on the registry
`POST /images/`(*name*)`/push`
: Push the image `name` on the registry
`POST /images/(name)/push`
Push the image `name` on the registry
> **Example request**:
>
@@ -678,10 +692,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Tag an image into a repository](#id24)
### Tag an image into a repository
`POST /images/`(*name*)`/tag`
: Tag the image `name` into a repository
`POST /images/(name)/tag`
Tag the image `name` into a repository
**Example request**:
@@ -706,10 +721,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### [Remove an image](#id25)
### Remove an image
`DELETE /images/`(*name*)
: Remove the image `name` from the filesystem
`DELETE /images/(name)`
Remove the image `name` from the filesystem
**Example request**:
@@ -725,10 +741,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Search images](#id26)
### Search images
`GET /images/search`
: Search for an image in the docker index
`GET /images/search`
Search for an image in the docker index
**Example request**:
@@ -758,12 +775,13 @@ page_keywords: API, Docker, rcli, REST, documentation
:statuscode 200: no error
:statuscode 500: server error
### [2.3 Misc](#id27)
## 2.3 Misc
#### [Build an image from Dockerfile via stdin](#id28)
### Build an image from Dockerfile via stdin
`POST /build`
: Build an image from Dockerfile via stdin
`POST /build`
Build an image from Dockerfile via stdin
**Example request**:
@@ -789,10 +807,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Get default username and email](#id29)
### Get default username and email
`GET /auth`
: Get the default username and email
`GET /auth`
Get the default username and email
**Example request**:
@@ -813,10 +832,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Check auth configuration and store it](#id30)
### Check auth configuration and store it
`POST /auth`
: Get the default username and email
`POST /auth`
Get the default username and email
**Example request**:
@@ -839,10 +859,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **204** – no error
- **500** – server error
#### [Display system-wide information](#id31)
### Display system-wide information
`GET /info`
: Display system-wide information
`GET /info`
Display system-wide information
**Example request**:
@@ -868,10 +889,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Show the docker version information](#id32)
### Show the docker version information
`GET /version`
: Show the docker version information
`GET /version`
Show the docker version information
**Example request**:
@@ -893,10 +915,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Create a new image from a container’s changes](#id33)
### Create a new image from a container's changes
`POST /commit`
: Create a new image from a container’s changes
`POST /commit`
Create a new image from a container's changes
**Example request**:
@@ -924,7 +947,7 @@ page_keywords: API, Docker, rcli, REST, documentation
- **tag** – tag
- **m** – commit message
- **author** – author (eg. "John Hannibal Smith
\<[hannibal@a-team.com](mailto:hannibal%40a-team.com)\>")
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
Status Codes:
@@ -932,28 +955,28 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
## [3. Going further](#id34)
# 3. Going further
### [3.1 Inside ‘docker run’](#id35)
## 3.1 Inside `docker run`
Here are the steps of ‘docker run’ :
Here are the steps of `docker run` :
- Create the container
- Create the container
- If the status code is 404, it means the image doesn’t exists:
: - Try to pull it
- Then retry to create the container
- If the status code is 404, it means the image doesn't exists:
- Try to pull it
- Then retry to create the container
- Start the container
- Start the container
- If you are not in detached mode:
: - Attach to the container, using logs=1 (to have stdout and
stderr from the container’s start) and stream=1
- If you are not in detached mode:
- Attach to the container, using logs=1 (to have stdout and
stderr from the container's start) and stream=1
- If in detached mode or only stdin is attached:
: - Display the container’s id
- If in detached mode or only stdin is attached:
- Display the container's
### [3.2 Hijacking](#id36)
## 3.2 Hijacking
In this version of the API, /attach uses hijacking to transport stdin,
stdout and stderr on the same socket. This might change in the future.
docs/sources/reference/api/archive/docker_remote_api_v1.2.md
+132 -110
View File
@@ -2,24 +2,25 @@ page_title: Remote API v1.2
page_description: API Documentation for Docker
page_keywords: API, Docker, rcli, REST, documentation
# [Docker Remote API v1.2](#id1)
# Docker Remote API v1.2
## [1. Brief introduction](#id2)
# 1. Brief introduction
- The Remote API is replacing rcli
- Default port in the docker daemon is 4243
- The API tends to be REST, but for some complex commands, like attach
or pull, the HTTP connection is hijacked to transport stdout stdin
and stderr
- The Remote API is replacing rcli
- Default port in the docker daemon is 4243
- The API tends to be REST, but for some complex commands, like attach
or pull, the HTTP connection is hijacked to transport stdout stdin
and stderr
## [2. Endpoints](#id3)
# 2. Endpoints
### [2.1 Containers](#id4)
## 2.1 Containers
#### [List containers](#id5)
### List containers
`GET /containers/json`
: List containers
`GET /containers/json`
List containers
**Example request**:
@@ -92,10 +93,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create a container](#id6)
### Create a container
`POST /containers/create`
: Create a container
`POST /containers/create`
Create a container
**Example request**:
@@ -138,7 +140,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **config** – the container’s configuration
- **config** – the container's configuration
Status Codes:
@@ -147,10 +149,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **406** – impossible to attach (container not running)
- **500** – server error
#### [Inspect a container](#id7)
### Inspect a container
`GET /containers/`(*id*)`/json`
: Return low-level information on the container `id`
`GET /containers/(id)/json`
Return low-level information on the container `id`
**Example request**:
@@ -214,10 +217,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Inspect changes on a container’s filesystem](#id8)
### Inspect changes on a container's filesystem
`GET /containers/`(*id*)`/changes`
: Inspect changes on container `id` ‘s filesystem
`GET /containers/(id)/changes`
Inspect changes on container `id`'s filesystem
**Example request**:
@@ -249,10 +253,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Export a container](#id9)
### Export a container
`GET /containers/`(*id*)`/export`
: Export the contents of container `id`
`GET /containers/(id)/export`
Export the contents of container `id`
**Example request**:
@@ -271,10 +276,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Start a container](#id10)
### Start a container
`POST /containers/`(*id*)`/start`
: Start the container `id`
`POST /containers/(id)/start`
Start the container `id`
**Example request**:
@@ -290,10 +296,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Stop a container](#id11)
### Stop a container
`POST /containers/`(*id*)`/stop`
: Stop the container `id`
`POST /containers/(id)/stop`
Stop the container `id`
**Example request**:
@@ -315,10 +322,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Restart a container](#id12)
### Restart a container
`POST /containers/`(*id*)`/restart`
: Restart the container `id`
`POST /containers/(id)/restart`
Restart the container `id`
**Example request**:
@@ -340,10 +348,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Kill a container](#id13)
### Kill a container
`POST /containers/`(*id*)`/kill`
: Kill the container `id`
`POST /containers/(id)/kill`
Kill the container `id`
**Example request**:
@@ -359,10 +368,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Attach to a container](#id14)
### Attach to a container
`POST /containers/`(*id*)`/attach`
: Attach to the container `id`
`POST /containers/(id)/attach`
Attach to the container `id`
**Example request**:
@@ -397,11 +407,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Wait a container](#id15)
### Wait a container
`POST /containers/`(*id*)`/wait`
: Block until container `id` stops, then returns
the exit code
`POST /containers/(id)/wait`
Block until container `id` stops, then returns the exit code
**Example request**:
@@ -420,10 +430,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Remove a container](#id16)
### Remove a container
`DELETE /containers/`(*id*)
: Remove the container `id` from the filesystem
`DELETE /containers/(id)`
Remove the container `id` from the filesystem
**Example request**:
@@ -447,13 +458,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
### [2.2 Images](#id17)
## 2.2 Images
#### [List Images](#id18)
### List Images
`GET /images/`(*format*)
: List images `format` could be json or viz (json
default)
`GET /images/(format)`
List images `format` could be json or viz (json default)
**Example request**:
@@ -523,11 +534,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create an image](#id19)
### Create an image
`POST /images/create`
: Create an image, either by pull it from the registry or by importing
it
`POST /images/create`
Create an image, either by pull it from the registry or by importing it
**Example request**:
@@ -558,11 +569,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Insert a file in an image](#id20)
### Insert a file in an image
`POST /images/`(*name*)`/insert`
: Insert a file from `url` in the image
`name` at `path`
`POST /images/(name)/insert`
Insert a file from `url` in the image `name` at `path`
**Example request**:
@@ -583,10 +594,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Inspect an image](#id21)
### Inspect an image
`GET /images/`(*name*)`/json`
: Return low-level information on the image `name`
`GET /images/(name)/json`
Return low-level information on the image `name`
**Example request**:
@@ -631,10 +643,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Get the history of an image](#id22)
### Get the history of an image
`GET /images/`(*name*)`/history`
: Return the history of the image `name`
`GET /images/(name)/history`
Return the history of the image `name`
**Example request**:
@@ -665,10 +678,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Push an image on the registry](#id23)
### Push an image on the registry
`POST /images/`(*name*)`/push`
: Push the image `name` on the registry
`POST /images/(name)/push`
Push the image `name` on the registry
> **Example request**:
>
@@ -697,10 +711,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Tag an image into a repository](#id24)
### Tag an image into a repository
`POST /images/`(*name*)`/tag`
: Tag the image `name` into a repository
`POST /images/(name)/tag`
Tag the image `name` into a repository
**Example request**:
@@ -725,10 +740,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### [Remove an image](#id25)
### Remove an image
`DELETE /images/`(*name*)
: Remove the image `name` from the filesystem
`DELETE /images/(name)`
Remove the image `name` from the filesystem
**Example request**:
@@ -752,10 +768,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### [Search images](#id26)
### Search images
`GET /images/search`
: Search for an image in the docker index
`GET /images/search`
Search for an image in the docker index
**Example request**:
@@ -785,12 +802,13 @@ page_keywords: API, Docker, rcli, REST, documentation
:statuscode 200: no error
:statuscode 500: server error
### [2.3 Misc](#id27)
## 2.3 Misc
#### [Build an image from Dockerfile via stdin](#id28)
### Build an image from Dockerfile via stdin
`POST /build`
: Build an image from Dockerfile
`POST /build`
Build an image from Dockerfile
**Example request**:
@@ -820,10 +838,11 @@ page_keywords: API, Docker, rcli, REST, documentation
{{ STREAM }} is the raw text output of the build command. It uses the
HTTP Hijack method in order to stream.
#### [Check auth configuration](#id29)
### Check auth configuration
`POST /auth`
: Get the default username and email
`POST /auth`
Get the default username and email
**Example request**:
@@ -853,10 +872,11 @@ HTTP Hijack method in order to stream.
- **403** – forbidden
- **500** – server error
#### [Display system-wide information](#id30)
### Display system-wide information
`GET /info`
: Display system-wide information
`GET /info`
Display system-wide information
**Example request**:
@@ -882,10 +902,11 @@ HTTP Hijack method in order to stream.
- **200** – no error
- **500** – server error
#### [Show the docker version information](#id31)
### Show the docker version information
`GET /version`
: Show the docker version information
`GET /version`
Show the docker version information
**Example request**:
@@ -907,10 +928,11 @@ HTTP Hijack method in order to stream.
- **200** – no error
- **500** – server error
#### [Create a new image from a container’s changes](#id32)
### Create a new image from a container's changes
`POST /commit`
: Create a new image from a container’s changes
`POST /commit`
Create a new image from a container's changes
**Example request**:
@@ -938,7 +960,7 @@ HTTP Hijack method in order to stream.
- **tag** – tag
- **m** – commit message
- **author** – author (eg. "John Hannibal Smith
\<[hannibal@a-team.com](mailto:hannibal%40a-team.com)\>")
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
Status Codes:
@@ -946,33 +968,33 @@ HTTP Hijack method in order to stream.
- **404** – no such container
- **500** – server error
## [3. Going further](#id33)
# 3. Going further
### [3.1 Inside ‘docker run’](#id34)
## 3.1 Inside `docker run`
Here are the steps of ‘docker run’ :
Here are the steps of `docker run` :
- Create the container
- Create the container
- If the status code is 404, it means the image doesn’t exists:
: - Try to pull it
- Then retry to create the container
- If the status code is 404, it means the image doesn't exists:
- Try to pull it
- Then retry to create the container
- Start the container
- Start the container
- If you are not in detached mode:
: - Attach to the container, using logs=1 (to have stdout and
stderr from the container’s start) and stream=1
- If you are not in detached mode:
- Attach to the container, using logs=1 (to have stdout and
stderr from the container's start) and stream=1
- If in detached mode or only stdin is attached:
: - Display the container’s id
- If in detached mode or only stdin is attached:
- Display the container's
### [3.2 Hijacking](#id35)
## 3.2 Hijacking
In this version of the API, /attach, uses hijacking to transport stdin,
stdout and stderr on the same socket. This might change in the future.
### [3.3 CORS Requests](#id36)
## 3.3 CORS Requests
To enable cross origin requests to the remote api add the flag
"–api-enable-cors" when running docker in daemon mode.
docs/sources/reference/api/archive/docker_remote_api_v1.3.md
+142 -118
View File
@@ -2,24 +2,25 @@ page_title: Remote API v1.3
page_description: API Documentation for Docker
page_keywords: API, Docker, rcli, REST, documentation
# [Docker Remote API v1.3](#id1)
# Docker Remote API v1.3
## [1. Brief introduction](#id2)
# 1. Brief introduction
- The Remote API is replacing rcli
- Default port in the docker daemon is 4243
- The API tends to be REST, but for some complex commands, like attach
or pull, the HTTP connection is hijacked to transport stdout stdin
and stderr
- The Remote API is replacing rcli
- Default port in the docker daemon is 4243
- The API tends to be REST, but for some complex commands, like attach
or pull, the HTTP connection is hijacked to transport stdout stdin
and stderr
## [2. Endpoints](#id3)
# 2. Endpoints
### [2.1 Containers](#id4)
## 2.1 Containers
#### [List containers](#id5)
### List containers
`GET /containers/json`
: List containers
`GET /containers/json`
List containers
**Example request**:
@@ -94,10 +95,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create a container](#id6)
### Create a container
`POST /containers/create`
: Create a container
`POST /containers/create`
Create a container
**Example request**:
@@ -140,7 +142,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **config** – the container’s configuration
- **config** – the container's configuration
Status Codes:
@@ -149,10 +151,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **406** – impossible to attach (container not running)
- **500** – server error
#### [Inspect a container](#id7)
### Inspect a container
`GET /containers/`(*id*)`/json`
: Return low-level information on the container `id`
`GET /containers/(id)/json`
Return low-level information on the container `id`
**Example request**:
@@ -216,10 +219,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [List processes running inside a container](#id8)
### List processes running inside a container
`GET /containers/`(*id*)`/top`
: List processes running inside the container `id`
`GET /containers/(id)/top`
List processes running inside the container `id`
**Example request**:
@@ -251,10 +255,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Inspect changes on a container’s filesystem](#id9)
### Inspect changes on a container's filesystem
`GET /containers/`(*id*)`/changes`
: Inspect changes on container `id` ‘s filesystem
`GET /containers/(id)/changes`
Inspect changes on container `id`'s filesystem
**Example request**:
@@ -286,10 +291,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Export a container](#id10)
### Export a container
`GET /containers/`(*id*)`/export`
: Export the contents of container `id`
`GET /containers/(id)/export`
Export the contents of container `id`
**Example request**:
@@ -308,10 +314,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Start a container](#id11)
### Start a container
`POST /containers/`(*id*)`/start`
: Start the container `id`
`POST /containers/(id)/start`
Start the container `id`
**Example request**:
@@ -331,7 +338,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **hostConfig** – the container’s host configuration (optional)
- **hostConfig** – the container's host configuration (optional)
Status Codes:
@@ -339,10 +346,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Stop a container](#id12)
### Stop a container
`POST /containers/`(*id*)`/stop`
: Stop the container `id`
`POST /containers/(id)/stop`
Stop the container `id`
**Example request**:
@@ -364,10 +372,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Restart a container](#id13)
### Restart a container
`POST /containers/`(*id*)`/restart`
: Restart the container `id`
`POST /containers/(id)/restart`
Restart the container `id`
**Example request**:
@@ -389,10 +398,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Kill a container](#id14)
### Kill a container
`POST /containers/`(*id*)`/kill`
: Kill the container `id`
`POST /containers/(id)/kill`
Kill the container `id`
**Example request**:
@@ -408,10 +418,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Attach to a container](#id15)
### Attach to a container
`POST /containers/`(*id*)`/attach`
: Attach to the container `id`
`POST /containers/(id)/attach`
Attach to the container `id`
**Example request**:
@@ -446,11 +457,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Wait a container](#id16)
### Wait a container
`POST /containers/`(*id*)`/wait`
: Block until container `id` stops, then returns
the exit code
`POST /containers/(id)/wait`
Block until container `id` stops, then returns the exit code
**Example request**:
@@ -469,10 +480,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Remove a container](#id17)
### Remove a container
`DELETE /containers/`(*id*)
: Remove the container `id` from the filesystem
`DELETE /containers/(id)`
Remove the container `id` from the filesystem
**Example request**:
@@ -496,13 +508,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
### [2.2 Images](#id18)
## 2.2 Images
#### [List Images](#id19)
### List Images
`GET /images/`(*format*)
: List images `format` could be json or viz (json
default)
`GET /images/(format)`
List images `format` could be json or viz (json default)
**Example request**:
@@ -572,11 +584,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create an image](#id20)
### Create an image
`POST /images/create`
: Create an image, either by pull it from the registry or by importing
it
`POST /images/create`
Create an image, either by pull it from the registry or by importing it
**Example request**:
@@ -607,11 +619,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Insert a file in an image](#id21)
### Insert a file in an image
`POST /images/`(*name*)`/insert`
: Insert a file from `url` in the image
`name` at `path`
`POST /images/(name)/insert`
Insert a file from `url` in the image `name` at `path`
**Example request**:
@@ -632,10 +644,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Inspect an image](#id22)
### Inspect an image
`GET /images/`(*name*)`/json`
: Return low-level information on the image `name`
`GET /images/(name)/json`
Return low-level information on the image `name`
**Example request**:
@@ -680,10 +693,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Get the history of an image](#id23)
### Get the history of an image
`GET /images/`(*name*)`/history`
: Return the history of the image `name`
`GET /images/(name)/history`
Return the history of the image `name`
**Example request**:
@@ -713,10 +727,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Push an image on the registry](#id24)
### Push an image on the registry
`POST /images/`(*name*)`/push`
: Push the image `name` on the registry
`POST /images/(name)/push`
Push the image `name` on the registry
> **Example request**:
>
@@ -745,10 +760,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Tag an image into a repository](#id25)
### Tag an image into a repository
`POST /images/`(*name*)`/tag`
: Tag the image `name` into a repository
`POST /images/(name)/tag`
Tag the image `name` into a repository
**Example request**:
@@ -773,10 +789,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### [Remove an image](#id26)
### Remove an image
`DELETE /images/`(*name*)
: Remove the image `name` from the filesystem
`DELETE /images/(name)`
Remove the image `name` from the filesystem
**Example request**:
@@ -800,10 +817,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### [Search images](#id27)
### Search images
`GET /images/search`
: Search for an image in the docker index
`GET /images/search`
Search for an image in the docker index
**Example request**:
@@ -833,12 +851,13 @@ page_keywords: API, Docker, rcli, REST, documentation
:statuscode 200: no error
:statuscode 500: server error
### [2.3 Misc](#id28)
## 2.3 Misc
#### [Build an image from Dockerfile via stdin](#id29)
### Build an image from Dockerfile via stdin
`POST /build`
: Build an image from Dockerfile via stdin
`POST /build`
Build an image from Dockerfile via stdin
**Example request**:
@@ -873,10 +892,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Check auth configuration](#id30)
### Check auth configuration
`POST /auth`
: Get the default username and email
`POST /auth`
Get the default username and email
**Example request**:
@@ -899,10 +919,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **204** – no error
- **500** – server error
#### [Display system-wide information](#id31)
### Display system-wide information
`GET /info`
: Display system-wide information
`GET /info`
Display system-wide information
**Example request**:
@@ -931,10 +952,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Show the docker version information](#id32)
### Show the docker version information
`GET /version`
: Show the docker version information
`GET /version`
Show the docker version information
**Example request**:
@@ -956,10 +978,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Create a new image from a container’s changes](#id33)
### Create a new image from a container's changes
`POST /commit`
: Create a new image from a container’s changes
`POST /commit`
Create a new image from a container's changes
**Example request**:
@@ -987,7 +1010,7 @@ page_keywords: API, Docker, rcli, REST, documentation
- **tag** – tag
- **m** – commit message
- **author** – author (eg. "John Hannibal Smith
\<[hannibal@a-team.com](mailto:hannibal%40a-team.com)\>")
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
Status Codes:
@@ -995,11 +1018,12 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Monitor Docker’s events](#id34)
### Monitor Docker's events
`GET /events`
: Get events from docker, either in real time via streaming, or via
polling (using since)
`GET /events`
Get events from docker, either in real time via streaming, or via
polling (using since)
**Example request**:
@@ -1026,33 +1050,33 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
## [3. Going further](#id35)
# 3. Going further
### [3.1 Inside ‘docker run’](#id36)
## 3.1 Inside `docker run`
Here are the steps of ‘docker run’ :
Here are the steps of `docker run` :
- Create the container
- Create the container
- If the status code is 404, it means the image doesn’t exists:
: - Try to pull it
- Then retry to create the container
- If the status code is 404, it means the image doesn't exists:
- Try to pull it
- Then retry to create the container
- Start the container
- Start the container
- If you are not in detached mode:
: - Attach to the container, using logs=1 (to have stdout and
stderr from the container’s start) and stream=1
- If you are not in detached mode:
- Attach to the container, using logs=1 (to have stdout and
stderr from the container's start) and stream=1
- If in detached mode or only stdin is attached:
: - Display the container’s id
- If in detached mode or only stdin is attached:
- Display the container's id
### [3.2 Hijacking](#id37)
## 3.2 Hijacking
In this version of the API, /attach, uses hijacking to transport stdin,
stdout and stderr on the same socket. This might change in the future.
### [3.3 CORS Requests](#id38)
## 3.3 CORS Requests
To enable cross origin requests to the remote api add the flag
"–api-enable-cors" when running docker in daemon mode.
docs/sources/reference/api/archive/docker_remote_api_v1.4.md
+163 -137
View File
@@ -2,24 +2,25 @@ page_title: Remote API v1.4
page_description: API Documentation for Docker
page_keywords: API, Docker, rcli, REST, documentation
# [Docker Remote API v1.4](#id1)
# Docker Remote API v1.4
## [1. Brief introduction](#id2)
# 1. Brief introduction
- The Remote API is replacing rcli
- Default port in the docker daemon is 4243
- The API tends to be REST, but for some complex commands, like attach
or pull, the HTTP connection is hijacked to transport stdout stdin
and stderr
- The Remote API is replacing rcli
- Default port in the docker daemon is 4243
- The API tends to be REST, but for some complex commands, like attach
or pull, the HTTP connection is hijacked to transport stdout stdin
and stderr
## [2. Endpoints](#id3)
# 2. Endpoints
### [2.1 Containers](#id4)
## 2.1 Containers
#### [List containers](#id5)
### List containers
`GET /containers/json`
: List containers
`GET /containers/json`
List containers
**Example request**:
@@ -94,10 +95,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create a container](#id6)
### Create a container
`POST /containers/create`
: Create a container
`POST /containers/create`
Create a container
**Example request**:
@@ -143,7 +145,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **config** – the container’s configuration
- **config** – the container's configuration
Status Codes:
@@ -152,10 +154,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **406** – impossible to attach (container not running)
- **500** – server error
#### [Inspect a container](#id7)
### Inspect a container
`GET /containers/`(*id*)`/json`
: Return low-level information on the container `id`
`GET /containers/(id)/json`
Return low-level information on the container `id`
**Example request**:
@@ -222,10 +225,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict between containers and images
- **500** – server error
#### [List processes running inside a container](#id8)
### List processes running inside a container
`GET /containers/`(*id*)`/top`
: List processes running inside the container `id`
`GET /containers/(id)/top`
List processes running inside the container `id`
**Example request**:
@@ -260,7 +264,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **ps\_args** – ps arguments to use (eg. aux)
- **ps_args** – ps arguments to use (eg. aux)
Status Codes:
@@ -268,10 +272,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Inspect changes on a container’s filesystem](#id9)
### Inspect changes on a container's filesystem
`GET /containers/`(*id*)`/changes`
: Inspect changes on container `id` ‘s filesystem
`GET /containers/(id)/changes`
Inspect changes on container `id`'s filesystem
**Example request**:
@@ -303,10 +308,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Export a container](#id10)
### Export a container
`GET /containers/`(*id*)`/export`
: Export the contents of container `id`
`GET /containers/(id)/export`
Export the contents of container `id`
**Example request**:
@@ -325,10 +331,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Start a container](#id11)
### Start a container
`POST /containers/`(*id*)`/start`
: Start the container `id`
`POST /containers/(id)/start`
Start the container `id`
**Example request**:
@@ -349,7 +356,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **hostConfig** – the container’s host configuration (optional)
- **hostConfig** – the container's host configuration (optional)
Status Codes:
@@ -357,10 +364,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Stop a container](#id12)
### Stop a container
`POST /containers/`(*id*)`/stop`
: Stop the container `id`
`POST /containers/(id)/stop`
Stop the container `id`
**Example request**:
@@ -382,10 +390,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Restart a container](#id13)
### Restart a container
`POST /containers/`(*id*)`/restart`
: Restart the container `id`
`POST /containers/(id)/restart`
Restart the container `id`
**Example request**:
@@ -407,10 +416,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Kill a container](#id14)
### Kill a container
`POST /containers/`(*id*)`/kill`
: Kill the container `id`
`POST /containers/(id)/kill`
Kill the container `id`
**Example request**:
@@ -426,10 +436,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Attach to a container](#id15)
### Attach to a container
`POST /containers/`(*id*)`/attach`
: Attach to the container `id`
`POST /containers/(id)/attach`
Attach to the container `id`
**Example request**:
@@ -464,11 +475,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Wait a container](#id16)
### Wait a container
`POST /containers/`(*id*)`/wait`
: Block until container `id` stops, then returns
the exit code
`POST /containers/(id)/wait`
Block until container `id` stops, then returns the exit code
**Example request**:
@@ -487,10 +498,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Remove a container](#id17)
### Remove a container
`DELETE /containers/`(*id*)
: Remove the container `id` from the filesystem
`DELETE /containers/(id)`
Remove the container `id` from the filesystem
**Example request**:
@@ -514,10 +526,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Copy files or folders from a container](#id18)
### Copy files or folders from a container
`POST /containers/`(*id*)`/copy`
: Copy files or folders of container `id`
`POST /containers/(id)/copy`
Copy files or folders of container `id`
**Example request**:
@@ -541,13 +554,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
### [2.2 Images](#id19)
## 2.2 Images
#### [List Images](#id20)
### List Images
`GET /images/`(*format*)
: List images `format` could be json or viz (json
default)
`GET /images/(format)`
List images `format` could be json or viz (json default)
**Example request**:
@@ -617,11 +630,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create an image](#id21)
### Create an image
`POST /images/create`
: Create an image, either by pull it from the registry or by importing
it
`POST /images/create`
Create an image, either by pull it from the registry or by importing it
**Example request**:
@@ -652,11 +665,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Insert a file in an image](#id22)
### Insert a file in an image
`POST /images/`(*name*)`/insert`
: Insert a file from `url` in the image
`name` at `path`
`POST /images/(name)/insert`
Insert a file from `url` in the image `name` at `path`
**Example request**:
@@ -677,10 +690,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Inspect an image](#id23)
### Inspect an image
`GET /images/`(*name*)`/json`
: Return low-level information on the image `name`
`GET /images/(name)/json`
Return low-level information on the image `name`
**Example request**:
@@ -727,10 +741,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict between containers and images
- **500** – server error
#### [Get the history of an image](#id24)
### Get the history of an image
`GET /images/`(*name*)`/history`
: Return the history of the image `name`
`GET /images/(name)/history`
Return the history of the image `name`
**Example request**:
@@ -760,10 +775,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Push an image on the registry](#id25)
### Push an image on the registry
`POST /images/`(*name*)`/push`
: Push the image `name` on the registry
`POST /images/(name)/push`
Push the image `name` on the registry
**Example request**:
@@ -789,10 +805,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error :statuscode 404: no such image :statuscode
500: server error
#### [Tag an image into a repository](#id26)
### Tag an image into a repository
`POST /images/`(*name*)`/tag`
: Tag the image `name` into a repository
`POST /images/(name)/tag`
Tag the image `name` into a repository
**Example request**:
@@ -817,10 +834,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### [Remove an image](#id27)
### Remove an image
`DELETE /images/`(*name*)
: Remove the image `name` from the filesystem
`DELETE /images/(name)`
Remove the image `name` from the filesystem
**Example request**:
@@ -844,10 +862,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### [Search images](#id28)
### Search images
`GET /images/search`
: Search for an image in the docker index
`GET /images/search`
Search for an image in the docker index
**Example request**:
@@ -877,12 +896,13 @@ page_keywords: API, Docker, rcli, REST, documentation
:statuscode 200: no error
:statuscode 500: server error
### [2.3 Misc](#id29)
## 2.3 Misc
#### [Build an image from Dockerfile via stdin](#id30)
### Build an image from Dockerfile via stdin
`POST /build`
: Build an image from Dockerfile via stdin
`POST /build`
Build an image from Dockerfile via stdin
**Example request**:
@@ -918,10 +938,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Check auth configuration](#id31)
### Check auth configuration
`POST /auth`
: Get the default username and email
`POST /auth`
Get the default username and email
**Example request**:
@@ -945,10 +966,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **204** – no error
- **500** – server error
#### [Display system-wide information](#id32)
### Display system-wide information
`GET /info`
: Display system-wide information
`GET /info`
Display system-wide information
**Example request**:
@@ -975,35 +997,38 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Show the docker version information](#id33)
### Show the docker version information
`GET /version`
: Show the docker version information
>
> **Example request**:
>
> GET /version HTTP/1.1
>
> **Example response**:
>
> HTTP/1.1 200 OK
> Content-Type: application/json
>
> {
> "Version":"0.2.2",
> "GitCommit":"5a2a5cc+CHANGES",
> "GoVersion":"go1.0.3"
> }
`GET /version`
Show the docker version information
**Example request**:
GET /version HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{
"Version":"0.2.2",
"GitCommit":"5a2a5cc+CHANGES",
"GoVersion":"go1.0.3"
}
Status Codes:
- **200** – no error
- **500** – server error
#### [Create a new image from a container’s changes](#id34)
### Create a new image from a container's changes
`POST /commit`
: Create a new image from a container’s changes
`POST /commit`
Create a new image from a container's changes
**Example request**:
@@ -1031,7 +1056,7 @@ page_keywords: API, Docker, rcli, REST, documentation
- **tag** – tag
- **m** – commit message
- **author** – author (eg. "John Hannibal Smith
\<[hannibal@a-team.com](mailto:hannibal%40a-team.com)\>")
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
Status Codes:
@@ -1039,11 +1064,12 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Monitor Docker’s events](#id35)
### Monitor Docker's events
`GET /events`
: Get events from docker, either in real time via streaming, or via
polling (using since)
`GET /events`
Get events from docker, either in real time via streaming, or via
polling (using since)
**Example request**:
@@ -1070,33 +1096,33 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
## [3. Going further](#id36)
# 3. Going further
### [3.1 Inside ‘docker run’](#id37)
## 3.1 Inside `docker run`
Here are the steps of ‘docker run’ :
Here are the steps of `docker run` :
- Create the container
- Create the container
- If the status code is 404, it means the image doesn’t exists:
: - Try to pull it
- Then retry to create the container
- If the status code is 404, it means the image doesn't exists:
- Try to pull it
- Then retry to create the container
- Start the container
- Start the container
- If you are not in detached mode:
: - Attach to the container, using logs=1 (to have stdout and
stderr from the container’s start) and stream=1
- If you are not in detached mode:
- Attach to the container, using logs=1 (to have stdout and
stderr from the container's start) and stream=1
- If in detached mode or only stdin is attached:
: - Display the container’s id
- If in detached mode or only stdin is attached:
- Display the container's id
### [3.2 Hijacking](#id38)
## 3.2 Hijacking
In this version of the API, /attach, uses hijacking to transport stdin,
stdout and stderr on the same socket. This might change in the future.
### [3.3 CORS Requests](#id39)
## 3.3 CORS Requests
To enable cross origin requests to the remote api add the flag
"–api-enable-cors" when running docker in daemon mode.
docs/sources/reference/api/archive/docker_remote_api_v1.5.md
+146 -121
View File
@@ -2,24 +2,25 @@ page_title: Remote API v1.5
page_description: API Documentation for Docker
page_keywords: API, Docker, rcli, REST, documentation
# [Docker Remote API v1.5](#id1)
# Docker Remote API v1.5
## [1. Brief introduction](#id2)
# 1. Brief introduction
- The Remote API is replacing rcli
- Default port in the docker daemon is 4243
- The API tends to be REST, but for some complex commands, like attach
or pull, the HTTP connection is hijacked to transport stdout stdin
and stderr
- The Remote API is replacing rcli
- Default port in the docker daemon is 4243
- The API tends to be REST, but for some complex commands, like attach
or pull, the HTTP connection is hijacked to transport stdout stdin
and stderr
## [2. Endpoints](#id3)
# 2. Endpoints
### [2.1 Containers](#id4)
## 2.1 Containers
#### [List containers](#id5)
### List containers
`GET /containers/json`
: List containers
`GET /containers/json`
List containers
**Example request**:
@@ -94,10 +95,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create a container](#id6)
### Create a container
`POST /containers/create`
: Create a container
`POST /containers/create`
Create a container
**Example request**:
@@ -142,7 +144,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **config** – the container’s configuration
- **config** – the container's configuration
Status Codes:
@@ -151,10 +153,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **406** – impossible to attach (container not running)
- **500** – server error
#### [Inspect a container](#id7)
### Inspect a container
`GET /containers/`(*id*)`/json`
: Return low-level information on the container `id`
`GET /containers/(id)/json`
Return low-level information on the container `id`
**Example request**:
@@ -219,10 +222,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [List processes running inside a container](#id8)
### List processes running inside a container
`GET /containers/`(*id*)`/top`
: List processes running inside the container `id`
`GET /containers/(id)/top`
List processes running inside the container `id`
**Example request**:
@@ -257,7 +261,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **ps\_args** – ps arguments to use (eg. aux)
- **ps_args** – ps arguments to use (eg. aux)
Status Codes:
@@ -265,10 +269,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Inspect changes on a container’s filesystem](#id9)
### Inspect changes on a container's filesystem
`GET /containers/`(*id*)`/changes`
: Inspect changes on container `id` ‘s filesystem
`GET /containers/(id)/changes`
Inspect changes on container `id`'s filesystem
**Example request**:
@@ -300,10 +305,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Export a container](#id10)
### Export a container
`GET /containers/`(*id*)`/export`
: Export the contents of container `id`
`GET /containers/(id)/export`
Export the contents of container `id`
**Example request**:
@@ -322,10 +328,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Start a container](#id11)
### Start a container
`POST /containers/`(*id*)`/start`
: Start the container `id`
`POST /containers/(id)/start`
Start the container `id`
**Example request**:
@@ -346,7 +353,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **hostConfig** – the container’s host configuration (optional)
- **hostConfig** – the container's host configuration (optional)
Status Codes:
@@ -354,10 +361,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Stop a container](#id12)
### Stop a container
`POST /containers/`(*id*)`/stop`
: Stop the container `id`
`POST /containers/(id)/stop`
Stop the container `id`
**Example request**:
@@ -379,10 +387,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Restart a container](#id13)
### Restart a container
`POST /containers/`(*id*)`/restart`
: Restart the container `id`
`POST /containers/(id)/restart`
Restart the container `id`
**Example request**:
@@ -404,10 +413,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Kill a container](#id14)
### Kill a container
`POST /containers/`(*id*)`/kill`
: Kill the container `id`
`POST /containers/(id)/kill`
Kill the container `id`
**Example request**:
@@ -423,10 +433,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Attach to a container](#id15)
### Attach to a container
`POST /containers/`(*id*)`/attach`
: Attach to the container `id`
`POST /containers/(id)/attach`
Attach to the container `id`
**Example request**:
@@ -461,11 +472,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Wait a container](#id16)
### Wait a container
`POST /containers/`(*id*)`/wait`
: Block until container `id` stops, then returns
the exit code
`POST /containers/(id)/wait`
Block until container `id` stops, then returns the exit code
**Example request**:
@@ -484,10 +495,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Remove a container](#id17)
### Remove a container
`DELETE /containers/`(*id*)
: Remove the container `id` from the filesystem
`DELETE /containers/(id)`
Remove the container `id` from the filesystem
**Example request**:
@@ -511,10 +523,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Copy files or folders from a container](#id18)
### Copy files or folders from a container
`POST /containers/`(*id*)`/copy`
: Copy files or folders of container `id`
`POST /containers/(id)/copy`
Copy files or folders of container `id`
**Example request**:
@@ -538,13 +551,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
### [2.2 Images](#id19)
## 2.2 Images
#### [List Images](#id20)
### List Images
`GET /images/`(*format*)
: List images `format` could be json or viz (json
default)
`GET /images/(format)`
List images `format` could be json or viz (json default)
**Example request**:
@@ -614,11 +627,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create an image](#id21)
### Create an image
`POST /images/create`
: Create an image, either by pull it from the registry or by importing
it
`POST /images/create`
Create an image, either by pull it from the registry or by importing it
**Example request**:
@@ -653,11 +666,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Insert a file in an image](#id22)
### Insert a file in an image
`POST /images/`(*name*)`/insert`
: Insert a file from `url` in the image
`name` at `path`
`POST /images/(name)/insert`
Insert a file from `url` in the image `name` at `path`
**Example request**:
@@ -678,10 +691,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Inspect an image](#id23)
### Inspect an image
`GET /images/`(*name*)`/json`
: Return low-level information on the image `name`
`GET /images/(name)/json`
Return low-level information on the image `name`
**Example request**:
@@ -727,10 +741,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Get the history of an image](#id24)
### Get the history of an image
`GET /images/`(*name*)`/history`
: Return the history of the image `name`
`GET /images/(name)/history`
Return the history of the image `name`
**Example request**:
@@ -760,10 +775,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Push an image on the registry](#id25)
### Push an image on the registry
`POST /images/`(*name*)`/push`
: Push the image `name` on the registry
`POST /images/(name)/push`
Push the image `name` on the registry
**Example request**:
@@ -794,10 +810,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Tag an image into a repository](#id26)
### Tag an image into a repository
`POST /images/`(*name*)`/tag`
: Tag the image `name` into a repository
`POST /images/(name)/tag`
Tag the image `name` into a repository
**Example request**:
@@ -822,10 +839,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### [Remove an image](#id27)
### Remove an image
`DELETE /images/`(*name*)
: Remove the image `name` from the filesystem
`DELETE /images/(name)`
Remove the image `name` from the filesystem
**Example request**:
@@ -849,10 +867,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### [Search images](#id28)
### Search images
`GET /images/search`
: Search for an image in the docker index
`GET /images/search`
Search for an image in the docker index
**Example request**:
@@ -889,12 +908,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
### [2.3 Misc](#id29)
## 2.3 Misc
#### [Build an image from Dockerfile via stdin](#id30)
### Build an image from Dockerfile via stdin
`POST /build`
: Build an image from Dockerfile via stdin
`POST /build`
Build an image from Dockerfile via stdin
**Example request**:
@@ -931,10 +951,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Check auth configuration](#id31)
### Check auth configuration
`POST /auth`
: Get the default username and email
`POST /auth`
Get the default username and email
**Example request**:
@@ -958,10 +979,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **204** – no error
- **500** – server error
#### [Display system-wide information](#id32)
### Display system-wide information
`GET /info`
: Display system-wide information
`GET /info`
Display system-wide information
**Example request**:
@@ -988,10 +1010,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Show the docker version information](#id33)
### Show the docker version information
`GET /version`
: Show the docker version information
`GET /version`
Show the docker version information
**Example request**:
@@ -1013,10 +1036,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Create a new image from a container’s changes](#id34)
### Create a new image from a container's changes
`POST /commit`
: Create a new image from a container’s changes
`POST /commit`
Create a new image from a container's changes
**Example request**:
@@ -1044,7 +1068,7 @@ page_keywords: API, Docker, rcli, REST, documentation
- **tag** – tag
- **m** – commit message
- **author** – author (eg. "John Hannibal Smith
\<[hannibal@a-team.com](mailto:hannibal%40a-team.com)\>")
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
Status Codes:
@@ -1052,11 +1076,12 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Monitor Docker’s events](#id35)
### Monitor Docker's events
`GET /events`
: Get events from docker, either in real time via streaming, or via
polling (using since)
`GET /events`
Get events from docker, either in real time via streaming, or via
polling (using since)
**Example request**:
@@ -1083,28 +1108,28 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
## [3. Going further](#id36)
# 3. Going further
### [3.1 Inside ‘docker run’](#id37)
## 3.1 Inside `docker run`
Here are the steps of ‘docker run’ :
Here are the steps of `docker run`:
- Create the container
- If the status code is 404, it means the image doesn’t exists: \* Try
to pull it \* Then retry to create the container
- Start the container
- If you are not in detached mode: \* Attach to the container, using
logs=1 (to have stdout and stderr from the container’s start) and
stream=1
- If in detached mode or only stdin is attached: \* Display the
container’s id
- Create the container
- If the status code is 404, it means the image doesn't exists:
Try to pull it - Then retry to create the container
- Start the container
- If you are not in detached mode:
Attach to the container, using logs=1 (to have stdout and stderr
from the container's start) and stream=1
- If in detached mode or only stdin is attached:
Display the container's id
### [3.2 Hijacking](#id38)
## 3.2 Hijacking
In this version of the API, /attach, uses hijacking to transport stdin,
stdout and stderr on the same socket. This might change in the future.
### [3.3 CORS Requests](#id39)
## 3.3 CORS Requests
To enable cross origin requests to the remote api add the flag
"–api-enable-cors" when running docker in daemon mode.
docs/sources/reference/api/archive/docker_remote_api_v1.6.md
+146 -122
View File
@@ -2,27 +2,27 @@ page_title: Remote API v1.6
page_description: API Documentation for Docker
page_keywords: API, Docker, rcli, REST, documentation
# [Docker Remote API v1.6](#id1)
# Docker Remote API v1.6
## [1. Brief introduction](#id2)
# 1. Brief introduction
- The Remote API has replaced rcli
- The daemon listens on `unix:///var/run/docker.sock`
, but you can [*Bind Docker to another host/port or a Unix
socket*](../../../../use/basics/#bind-docker).
- The API tends to be REST, but for some complex commands, like
`attach` or `pull`, the HTTP
connection is hijacked to transport `stdout, stdin`
and `stderr`
- The Remote API has replaced rcli
- The daemon listens on `unix:///var/run/docker.sock` but you can
[*Bind Docker to another host/port or a Unix socket*](
../../../use/basics/#bind-docker).
- The API tends to be REST, but for some complex commands, like `attach`
or `pull`, the HTTP connection is hijacked to transport `stdout, stdin`
and `stderr`
## [2. Endpoints](#id3)
# 2. Endpoints
### [2.1 Containers](#id4)
## 2.1 Containers
#### [List containers](#id5)
### List containers
`GET /containers/json`
: List containers
`GET /containers/json`
List containers
**Example request**:
@@ -97,10 +97,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create a container](#id6)
### Create a container
`POST /containers/create`
: Create a container
`POST /containers/create`
Create a container
**Example request**:
@@ -144,7 +145,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **config** – the container’s configuration
- **config** – the container's configuration
Query Parameters:
@@ -202,10 +203,11 @@ page_keywords: API, Docker, rcli, REST, documentation
**Now you can ssh into your new container on port 11022.**
#### [Inspect a container](#id7)
### Inspect a container
`GET /containers/`(*id*)`/json`
: Return low-level information on the container `id`
`GET /containers/(id)/json`
Return low-level information on the container `id`
**Example request**:
@@ -271,10 +273,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [List processes running inside a container](#id8)
### List processes running inside a container
`GET /containers/`(*id*)`/top`
: List processes running inside the container `id`
`GET /containers/(id)/top`
List processes running inside the container `id`
**Example request**:
@@ -309,7 +312,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **ps\_args** – ps arguments to use (eg. aux)
- **ps_args** – ps arguments to use (eg. aux)
Status Codes:
@@ -317,10 +320,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Inspect changes on a container’s filesystem](#id9)
### Inspect changes on a container's filesystem
`GET /containers/`(*id*)`/changes`
: Inspect changes on container `id` ‘s filesystem
`GET /containers/(id)/changes`
Inspect changes on container `id`'s filesystem
**Example request**:
@@ -352,10 +356,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Export a container](#id10)
### Export a container
`GET /containers/`(*id*)`/export`
: Export the contents of container `id`
`GET /containers/(id)/export`
Export the contents of container `id`
**Example request**:
@@ -374,10 +379,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Start a container](#id11)
### Start a container
`POST /containers/`(*id*)`/start`
: Start the container `id`
`POST /containers/(id)/start`
Start the container `id`
**Example request**:
@@ -403,7 +409,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **hostConfig** – the container’s host configuration (optional)
- **hostConfig** – the container's host configuration (optional)
Status Codes:
@@ -411,10 +417,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Stop a container](#id12)
### Stop a container
`POST /containers/`(*id*)`/stop`
: Stop the container `id`
`POST /containers/(id)/stop`
Stop the container `id`
**Example request**:
@@ -436,10 +443,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Restart a container](#id13)
### Restart a container
`POST /containers/`(*id*)`/restart`
: Restart the container `id`
`POST /containers/(id)/restart`
Restart the container `id`
**Example request**:
@@ -461,10 +469,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Kill a container](#id14)
### Kill a container
`POST /containers/`(*id*)`/kill`
: Kill the container `id`
`POST /containers/(id)/kill`
Kill the container `id`
**Example request**:
@@ -488,10 +497,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Attach to a container](#id15)
### Attach to a container
`POST /containers/`(*id*)`/attach`
: Attach to the container `id`
`POST /containers/(id)/attach`
Attach to the container `id`
**Example request**:
@@ -530,8 +540,8 @@ page_keywords: API, Docker, rcli, REST, documentation
When using the TTY setting is enabled in
[`POST /containers/create`
](../../docker_remote_api_v1.9/#post--containers-create "POST /containers/create"),
the stream is the raw data from the process PTY and client’s stdin.
](../../docker_remote_api_v1.9/#post--containers-create "POST /containers/create"),
the stream is the raw data from the process PTY and client's stdin.
When the TTY is disabled, then the stream is multiplexed to separate
stdout and stderr.
@@ -570,11 +580,11 @@ page_keywords: API, Docker, rcli, REST, documentation
4. Read the extracted size and output it on the correct output
5. Goto 1)
#### [Wait a container](#id16)
### Wait a container
`POST /containers/`(*id*)`/wait`
: Block until container `id` stops, then returns
the exit code
`POST /containers/(id)/wait`
Block until container `id` stops, then returns the exit code
**Example request**:
@@ -593,10 +603,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Remove a container](#id17)
### Remove a container
`DELETE /containers/`(*id*)
: Remove the container `id` from the filesystem
`DELETE /containers/(id)`
Remove the container `id` from the filesystem
**Example request**:
@@ -620,10 +631,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Copy files or folders from a container](#id18)
### Copy files or folders from a container
`POST /containers/`(*id*)`/copy`
: Copy files or folders of container `id`
`POST /containers/(id)/copy`
Copy files or folders of container `id`
**Example request**:
@@ -647,13 +659,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
### [2.2 Images](#id19)
## 2.2 Images
#### [List Images](#id20)
### List Images
`GET /images/`(*format*)
: List images `format` could be json or viz (json
default)
`GET /images/(format)`
List images `format` could be json or viz (json default)
**Example request**:
@@ -723,11 +735,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create an image](#id21)
### Create an image
`POST /images/create`
: Create an image, either by pull it from the registry or by importing
it
`POST /images/create`
Create an image, either by pull it from the registry or by importing it
**Example request**:
@@ -762,11 +774,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Insert a file in an image](#id22)
### Insert a file in an image
`POST /images/`(*name*)`/insert`
: Insert a file from `url` in the image
`name` at `path`
`POST /images/(name)/insert`
Insert a file from `url` in the image `name` at `path`
**Example request**:
@@ -787,10 +799,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Inspect an image](#id23)
### Inspect an image
`GET /images/`(*name*)`/json`
: Return low-level information on the image `name`
`GET /images/(name)/json`
Return low-level information on the image `name`
**Example request**:
@@ -836,10 +849,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Get the history of an image](#id24)
### Get the history of an image
`GET /images/`(*name*)`/history`
: Return the history of the image `name`
`GET /images/(name)/history`
Return the history of the image `name`
**Example request**:
@@ -869,10 +883,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Push an image on the registry](#id25)
### Push an image on the registry
`POST /images/`(*name*)`/push`
: Push the image `name` on the registry
`POST /images/(name)/push`
Push the image `name` on the registry
**Example request**:
@@ -900,10 +915,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error :statuscode 404: no such image :statuscode
500: server error
#### [Tag an image into a repository](#id26)
### Tag an image into a repository
`POST /images/`(*name*)`/tag`
: Tag the image `name` into a repository
`POST /images/(name)/tag`
Tag the image `name` into a repository
**Example request**:
@@ -928,10 +944,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### [Remove an image](#id27)
### Remove an image
`DELETE /images/`(*name*)
: Remove the image `name` from the filesystem
`DELETE /images/(name)`
Remove the image `name` from the filesystem
**Example request**:
@@ -955,10 +972,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### [Search images](#id28)
### Search images
`GET /images/search`
: Search for an image in the docker index
`GET /images/search`
Search for an image in the docker index
**Example request**:
@@ -988,12 +1006,13 @@ page_keywords: API, Docker, rcli, REST, documentation
:statuscode 200: no error
:statuscode 500: server error
### [2.3 Misc](#id29)
## 2.3 Misc
#### [Build an image from Dockerfile via stdin](#id30)
### Build an image from Dockerfile via stdin
`POST /build`
: Build an image from Dockerfile via stdin
`POST /build`
Build an image from Dockerfile via stdin
**Example request**:
@@ -1029,10 +1048,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Check auth configuration](#id31)
### Check auth configuration
`POST /auth`
: Get the default username and email
`POST /auth`
Get the default username and email
**Example request**:
@@ -1056,10 +1076,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **204** – no error
- **500** – server error
#### [Display system-wide information](#id32)
### Display system-wide information
`GET /info`
: Display system-wide information
`GET /info`
Display system-wide information
**Example request**:
@@ -1086,10 +1107,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Show the docker version information](#id33)
### Show the docker version information
`GET /version`
: Show the docker version information
`GET /version`
Show the docker version information
**Example request**:
@@ -1111,10 +1133,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Create a new image from a container’s changes](#id34)
### Create a new image from a container's changes
`POST /commit`
: Create a new image from a container’s changes
`POST /commit`
Create a new image from a container's changes
**Example request**:
@@ -1142,7 +1165,7 @@ page_keywords: API, Docker, rcli, REST, documentation
- **tag** – tag
- **m** – commit message
- **author** – author (eg. "John Hannibal Smith
\<[hannibal@a-team.com](mailto:hannibal%40a-team.com)\>")
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
Status Codes:
@@ -1150,11 +1173,12 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Monitor Docker’s events](#id35)
### Monitor Docker's events
`GET /events`
: Get events from docker, either in real time via streaming, or via
polling (using since)
`GET /events`
Get events from docker, either in real time via streaming, or via
polling (using since)
**Example request**:
@@ -1181,33 +1205,33 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
## [3. Going further](#id36)
# 3. Going further
### [3.1 Inside ‘docker run’](#id37)
## 3.1 Inside `docker run`
Here are the steps of ‘docker run’ :
Here are the steps of `docker run` :
- Create the container
- If the status code is 404, it means the image doesn’t exists:
: - Try to pull it
- If the status code is 404, it means the image doesn't exists:
- Try to pull it
- Then retry to create the container
- Start the container
- If you are not in detached mode:
: - Attach to the container, using logs=1 (to have stdout and
stderr from the container’s start) and stream=1
- Attach to the container, using logs=1 (to have stdout and
stderr from the container's start) and stream=1
- If in detached mode or only stdin is attached:
: - Display the container’s id
- Display the container's id
### [3.2 Hijacking](#id38)
## 3.2 Hijacking
In this version of the API, /attach, uses hijacking to transport stdin,
stdout and stderr on the same socket. This might change in the future.
### [3.3 CORS Requests](#id39)
## 3.3 CORS Requests
To enable cross origin requests to the remote api add the flag
"–api-enable-cors" when running docker in daemon mode.
docs/sources/reference/api/archive/docker_remote_api_v1.7.md
+157 -130
View File
@@ -2,27 +2,27 @@ page_title: Remote API v1.7
page_description: API Documentation for Docker
page_keywords: API, Docker, rcli, REST, documentation
# [Docker Remote API v1.7](#id1)
# Docker Remote API v1.7
## [1. Brief introduction](#id2)
# 1. Brief introduction
- The Remote API has replaced rcli
- The daemon listens on `unix:///var/run/docker.sock`
, but you can [*Bind Docker to another host/port or a Unix
socket*](../../../../use/basics/#bind-docker).
- The API tends to be REST, but for some complex commands, like
`attach` or `pull`, the HTTP
connection is hijacked to transport `stdout, stdin`
and `stderr`
- The Remote API has replaced rcli
- The daemon listens on `unix:///var/run/docker.sock` but you can
[*Bind Docker to another host/port or a Unix socket*](
../../../use/basics/#bind-docker).
- The API tends to be REST, but for some complex commands, like `attach`
or `pull`, the HTTP connection is hijacked to transport `stdout, stdin`
and `stderr`
## [2. Endpoints](#id3)
# 2. Endpoints
### [2.1 Containers](#id4)
## 2.1 Containers
#### [List containers](#id5)
### List containers
`GET /containers/json`
: List containers
`GET /containers/json`
List containers
**Example request**:
@@ -97,10 +97,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create a container](#id6)
### Create a container
`POST /containers/create`
: Create a container
`POST /containers/create`
Create a container
**Example request**:
@@ -149,7 +150,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **config** – the container’s configuration
- **config** – the container's configuration
Status Codes:
@@ -158,10 +159,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **406** – impossible to attach (container not running)
- **500** – server error
#### [Inspect a container](#id7)
### Inspect a container
`GET /containers/`(*id*)`/json`
: Return low-level information on the container `id`
`GET /containers/(id)/json`
Return low-level information on the container `id`
**Example request**:
@@ -227,10 +229,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [List processes running inside a container](#id8)
### List processes running inside a container
`GET /containers/`(*id*)`/top`
: List processes running inside the container `id`
`GET /containers/(id)/top`
List processes running inside the container `id`
**Example request**:
@@ -265,7 +268,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **ps\_args** – ps arguments to use (eg. aux)
- **ps_args** – ps arguments to use (eg. aux)
Status Codes:
@@ -273,10 +276,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Inspect changes on a container’s filesystem](#id9)
### Inspect changes on a container's filesystem
`GET /containers/`(*id*)`/changes`
: Inspect changes on container `id` ‘s filesystem
`GET /containers/(id)/changes`
Inspect changes on container `id`'s filesystem
**Example request**:
@@ -308,10 +312,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Export a container](#id10)
### Export a container
`GET /containers/`(*id*)`/export`
: Export the contents of container `id`
`GET /containers/(id)/export`
Export the contents of container `id`
**Example request**:
@@ -330,10 +335,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Start a container](#id11)
### Start a container
`POST /containers/`(*id*)`/start`
: Start the container `id`
`POST /containers/(id)/start`
Start the container `id`
**Example request**:
@@ -360,7 +366,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **hostConfig** – the container’s host configuration (optional)
- **hostConfig** – the container's host configuration (optional)
Status Codes:
@@ -368,10 +374,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Stop a container](#id12)
### Stop a container
`POST /containers/`(*id*)`/stop`
: Stop the container `id`
`POST /containers/(id)/stop`
Stop the container `id`
**Example request**:
@@ -393,10 +400,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Restart a container](#id13)
### Restart a container
`POST /containers/`(*id*)`/restart`
: Restart the container `id`
`POST /containers/(id)/restart`
Restart the container `id`
**Example request**:
@@ -418,10 +426,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Kill a container](#id14)
### Kill a container
`POST /containers/`(*id*)`/kill`
: Kill the container `id`
`POST /containers/(id)/kill`
Kill the container `id`
**Example request**:
@@ -437,10 +446,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Attach to a container](#id15)
### Attach to a container
`POST /containers/`(*id*)`/attach`
: Attach to the container `id`
`POST /containers/(id)/attach`
Attach to the container `id`
**Example request**:
@@ -479,8 +489,8 @@ page_keywords: API, Docker, rcli, REST, documentation
When using the TTY setting is enabled in
[`POST /containers/create`
](../../docker_remote_api_v1.9/#post--containers-create "POST /containers/create"),
the stream is the raw data from the process PTY and client’s stdin.
](../../docker_remote_api_v1.9/#post--containers-create "POST /containers/create"),
the stream is the raw data from the process PTY and client's stdin.
When the TTY is disabled, then the stream is multiplexed to separate
stdout and stderr.
@@ -519,11 +529,11 @@ page_keywords: API, Docker, rcli, REST, documentation
4. Read the extracted size and output it on the correct output
5. Goto 1)
#### [Wait a container](#id16)
### Wait a container
`POST /containers/`(*id*)`/wait`
: Block until container `id` stops, then returns
the exit code
`POST /containers/(id)/wait`
Block until container `id` stops, then returns the exit code
**Example request**:
@@ -542,10 +552,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Remove a container](#id17)
### Remove a container
`DELETE /containers/`(*id*)
: Remove the container `id` from the filesystem
`DELETE /containers/(id)`
Remove the container `id` from the filesystem
**Example request**:
@@ -569,10 +580,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Copy files or folders from a container](#id18)
### Copy files or folders from a container
`POST /containers/`(*id*)`/copy`
: Copy files or folders of container `id`
`POST /containers/(id)/copy`
Copy files or folders of container `id`
**Example request**:
@@ -596,12 +608,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
### [2.2 Images](#id19)
## 2.2 Images
#### [List Images](#id20)
### List Images
`GET /images/json`
: **Example request**:
`GET /images/json`
**Example request**:
GET /images/json?all=0 HTTP/1.1
@@ -635,11 +648,11 @@ page_keywords: API, Docker, rcli, REST, documentation
}
]
#### [Create an image](#id21)
### Create an image
`POST /images/create`
: Create an image, either by pull it from the registry or by importing
it
`POST /images/create`
Create an image, either by pull it from the registry or by importing it
**Example request**:
@@ -680,11 +693,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Insert a file in an image](#id22)
### Insert a file in an image
`POST /images/`(*name*)`/insert`
: Insert a file from `url` in the image
`name` at `path`
`POST /images/(name)/insert`
Insert a file from `url` in the image `name` at `path`
**Example request**:
@@ -705,10 +718,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Inspect an image](#id23)
### Inspect an image
`GET /images/`(*name*)`/json`
: Return low-level information on the image `name`
`GET /images/(name)/json`
Return low-level information on the image `name`
**Example request**:
@@ -754,10 +768,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Get the history of an image](#id24)
### Get the history of an image
`GET /images/`(*name*)`/history`
: Return the history of the image `name`
`GET /images/(name)/history`
Return the history of the image `name`
**Example request**:
@@ -787,10 +802,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Push an image on the registry](#id25)
### Push an image on the registry
`POST /images/`(*name*)`/push`
: Push the image `name` on the registry
`POST /images/(name)/push`
Push the image `name` on the registry
**Example request**:
@@ -825,10 +841,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Tag an image into a repository](#id26)
### Tag an image into a repository
`POST /images/`(*name*)`/tag`
: Tag the image `name` into a repository
`POST /images/(name)/tag`
Tag the image `name` into a repository
**Example request**:
@@ -853,10 +870,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### [Remove an image](#id27)
### Remove an image
`DELETE /images/`(*name*)
: Remove the image `name` from the filesystem
`DELETE /images/(name)`
Remove the image `name` from the filesystem
**Example request**:
@@ -880,14 +898,15 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### [Search images](#id28)
### Search images
`GET /images/search`
: Search for an image in the docker index.
`GET /images/search`
Search for an image in the docker index.
> **Note**:
> The response keys have changed from API v1.6 to reflect the JSON
> sent by the registry server to the docker daemon’s request.
> sent by the registry server to the docker daemon's request.
**Example request**:
@@ -934,12 +953,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
### [2.3 Misc](#id29)
## 2.3 Misc
#### [Build an image from Dockerfile via stdin](#id30)
### Build an image from Dockerfile via stdin
`POST /build`
: Build an image from Dockerfile via stdin
`POST /build`
Build an image from Dockerfile via stdin
**Example request**:
@@ -958,7 +978,7 @@ page_keywords: API, Docker, rcli, REST, documentation
following algorithms: identity (no compression), gzip, bzip2, xz.
The archive must include a file called `Dockerfile`
at its root. It may include any number of other files,
at its root. It may include any number of other files,
which will be accessible in the build context (See the [*ADD build
command*](../../../builder/#dockerbuilder)).
@@ -983,10 +1003,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Check auth configuration](#id31)
### Check auth configuration
`POST /auth`
: Get the default username and email
`POST /auth`
Get the default username and email
**Example request**:
@@ -1010,10 +1031,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **204** – no error
- **500** – server error
#### [Display system-wide information](#id32)
### Display system-wide information
`GET /info`
: Display system-wide information
`GET /info`
Display system-wide information
**Example request**:
@@ -1040,10 +1062,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Show the docker version information](#id33)
### Show the docker version information
`GET /version`
: Show the docker version information
`GET /version`
Show the docker version information
**Example request**:
@@ -1065,10 +1088,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Create a new image from a container’s changes](#id34)
### Create a new image from a container's changes
`POST /commit`
: Create a new image from a container’s changes
`POST /commit`
Create a new image from a container's changes
**Example request**:
@@ -1090,7 +1114,7 @@ page_keywords: API, Docker, rcli, REST, documentation
- **tag** – tag
- **m** – commit message
- **author** – author (eg. "John Hannibal Smith
\<[hannibal@a-team.com](mailto:hannibal%40a-team.com)\>")
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
- **run** – config automatically applied when the image is run.
(ex: {"Cmd": ["cat", "/world"], "PortSpecs":["22"]})
@@ -1100,11 +1124,12 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Monitor Docker’s events](#id35)
### Monitor Docker's events
`GET /events`
: Get events from docker, either in real time via streaming, or via
polling (using since)
`GET /events`
Get events from docker, either in real time via streaming, or via
polling (using since)
**Example request**:
@@ -1131,11 +1156,12 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Get a tarball containing all images and tags in a repository](#id36)
### Get a tarball containing all images and tags in a repository
`GET /images/`(*name*)`/get`
: Get a tarball containing all images and metadata for the repository
specified by `name`.
`GET /images/(name)/get`
Get a tarball containing all images and metadata for the repository
specified by `name`.
**Example request**
@@ -1152,10 +1178,11 @@ page_keywords: API, Docker, rcli, REST, documentation
:statuscode 200: no error
:statuscode 500: server error
#### [Load a tarball with a set of images and tags into docker](#id37)
### Load a tarball with a set of images and tags into docker
`POST /images/load`
: Load a set of images and tags into the docker repository.
`POST /images/load`
Load a set of images and tags into the docker repository.
**Example request**
@@ -1172,33 +1199,33 @@ page_keywords: API, Docker, rcli, REST, documentation
:statuscode 200: no error
:statuscode 500: server error
## [3. Going further](#id38)
# 3. Going further
### [3.1 Inside ‘docker run’](#id39)
## 3.1 Inside `docker run`
Here are the steps of ‘docker run’ :
Here are the steps of `docker run` :
- Create the container
- If the status code is 404, it means the image doesn’t exists:
: - Try to pull it
- If the status code is 404, it means the image doesn't exists:
- Try to pull it
- Then retry to create the container
- Start the container
- If you are not in detached mode:
: - Attach to the container, using logs=1 (to have stdout and
stderr from the container’s start) and stream=1
- Attach to the container, using logs=1 (to have stdout and
stderr from the container's start) and stream=1
- If in detached mode or only stdin is attached:
: - Display the container’s id
- Display the container's id
### [3.2 Hijacking](#id40)
## 3.2 Hijacking
In this version of the API, /attach, uses hijacking to transport stdin,
stdout and stderr on the same socket. This might change in the future.
### [3.3 CORS Requests](#id41)
## 3.3 CORS Requests
To enable cross origin requests to the remote api add the flag
"–api-enable-cors" when running docker in daemon mode.
docs/sources/reference/api/archive/docker_remote_api_v1.8.md
+159 -133
View File
@@ -2,27 +2,27 @@ page_title: Remote API v1.8
page_description: API Documentation for Docker
page_keywords: API, Docker, rcli, REST, documentation
# [Docker Remote API v1.8](#id1)
# Docker Remote API v1.8
## [1. Brief introduction](#id2)
# 1. Brief introduction
- The Remote API has replaced rcli
- The daemon listens on `unix:///var/run/docker.sock`
, but you can [*Bind Docker to another host/port or a Unix
socket*](../../../../use/basics/#bind-docker).
- The API tends to be REST, but for some complex commands, like
`attach` or `pull`, the HTTP
connection is hijacked to transport `stdout, stdin`
and `stderr`
- The Remote API has replaced rcli
- The daemon listens on `unix:///var/run/docker.sock` but you can
[*Bind Docker to another host/port or a Unix socket*](
../../../use/basics/#bind-docker).
- The API tends to be REST, but for some complex commands, like `attach`
or `pull`, the HTTP connection is hijacked to transport `stdout, stdin`
and `stderr`
## [2. Endpoints](#id3)
# 2. Endpoints
### [2.1 Containers](#id4)
## 2.1 Containers
#### [List containers](#id5)
### List containers
`GET /containers/json`
: List containers
`GET /containers/json`
List containers
**Example request**:
@@ -97,10 +97,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### [Create a container](#id6)
### Create a container
`POST /containers/create`
: Create a container
`POST /containers/create`
Create a container
**Example request**:
@@ -179,11 +180,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **406** – impossible to attach (container not running)
- **500** – server error
#### [Inspect a container](#id7)
### Inspect a container
`GET /containers/`(*id*)`/json`
: Return low-level information on the container `id`
`GET /containers/(id)/json`
Return low-level information on the container `id`
**Example request**:
@@ -264,10 +265,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [List processes running inside a container](#id8)
### List processes running inside a container
`GET /containers/`(*id*)`/top`
: List processes running inside the container `id`
`GET /containers/(id)/top`
List processes running inside the container `id`
**Example request**:
@@ -302,7 +304,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **ps\_args** – ps arguments to use (eg. aux)
- **ps_args** – ps arguments to use (eg. aux)
Status Codes:
@@ -310,10 +312,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Inspect changes on a container’s filesystem](#id9)
### Inspect changes on a container's filesystem
`GET /containers/`(*id*)`/changes`
: Inspect changes on container `id` ‘s filesystem
`GET /containers/(id)/changes`
Inspect changes on container `id`'s filesystem
**Example request**:
@@ -345,10 +348,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Export a container](#id10)
### Export a container
`GET /containers/`(*id*)`/export`
: Export the contents of container `id`
`GET /containers/(id)/export`
Export the contents of container `id`
**Example request**:
@@ -367,10 +371,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Start a container](#id11)
### Start a container
`POST /containers/`(*id*)`/start`
: Start the container `id`
`POST /containers/(id)/start`
Start the container `id`
**Example request**:
@@ -411,10 +416,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Stop a container](#id12)
### Stop a container
`POST /containers/`(*id*)`/stop`
: Stop the container `id`
`POST /containers/(id)/stop`
Stop the container `id`
**Example request**:
@@ -436,10 +442,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Restart a container](#id13)
### Restart a container
`POST /containers/`(*id*)`/restart`
: Restart the container `id`
`POST /containers/(id)/restart`
Restart the container `id`
**Example request**:
@@ -461,10 +468,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Kill a container](#id14)
### Kill a container
`POST /containers/`(*id*)`/kill`
: Kill the container `id`
`POST /containers/(id)/kill`
Kill the container `id`
**Example request**:
@@ -480,10 +488,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Attach to a container](#id15)
### Attach to a container
`POST /containers/`(*id*)`/attach`
: Attach to the container `id`
`POST /containers/(id)/attach`
Attach to the container `id`
**Example request**:
@@ -522,8 +531,8 @@ page_keywords: API, Docker, rcli, REST, documentation
When using the TTY setting is enabled in
[`POST /containers/create`
](../../docker_remote_api_v1.9/#post--containers-create "POST /containers/create"),
the stream is the raw data from the process PTY and client’s stdin.
](../../docker_remote_api_v1.9/#post--containers-create "POST /containers/create"),
the stream is the raw data from the process PTY and client's stdin.
When the TTY is disabled, then the stream is multiplexed to separate
stdout and stderr.
@@ -562,11 +571,11 @@ page_keywords: API, Docker, rcli, REST, documentation
4. Read the extracted size and output it on the correct output
5. Goto 1)
#### [Wait a container](#id16)
### Wait a container
`POST /containers/`(*id*)`/wait`
: Block until container `id` stops, then returns
the exit code
`POST /containers/(id)/wait`
Block until container `id` stops, then returns the exit code
**Example request**:
@@ -585,10 +594,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Remove a container](#id17)
### Remove a container
`DELETE /containers/`(*id*)
: Remove the container `id` from the filesystem
`DELETE /containers/(id)`
Remove the container `id` from the filesystem
**Example request**:
@@ -612,10 +622,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Copy files or folders from a container](#id18)
### Copy files or folders from a container
`POST /containers/`(*id*)`/copy`
: Copy files or folders of container `id`
`POST /containers/(id)/copy`
Copy files or folders of container `id`
**Example request**:
@@ -639,12 +650,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
### [2.2 Images](#id19)
## 2.2 Images
#### [List Images](#id20)
### List Images
`GET /images/json`
: **Example request**:
`GET /images/json`
**Example request**:
GET /images/json?all=0 HTTP/1.1
@@ -678,11 +690,11 @@ page_keywords: API, Docker, rcli, REST, documentation
}
]
#### [Create an image](#id21)
### Create an image
`POST /images/create`
: Create an image, either by pull it from the registry or by importing
it
`POST /images/create`
Create an image, either by pull it from the registry or by importing it
**Example request**:
@@ -723,11 +735,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Insert a file in an image](#id22)
### Insert a file in an image
`POST /images/`(*name*)`/insert`
: Insert a file from `url` in the image
`name` at `path`
`POST /images/(name)/insert`
Insert a file from `url` in the image `name` at `path`
**Example request**:
@@ -748,10 +760,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Inspect an image](#id23)
### Inspect an image
`GET /images/`(*name*)`/json`
: Return low-level information on the image `name`
`GET /images/(name)/json`
Return low-level information on the image `name`
**Example request**:
@@ -797,10 +810,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Get the history of an image](#id24)
### Get the history of an image
`GET /images/`(*name*)`/history`
: Return the history of the image `name`
`GET /images/(name)/history`
Return the history of the image `name`
**Example request**:
@@ -830,10 +844,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Push an image on the registry](#id25)
### Push an image on the registry
`POST /images/`(*name*)`/push`
: Push the image `name` on the registry
`POST /images/(name)/push`
Push the image `name` on the registry
**Example request**:
@@ -868,10 +883,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### [Tag an image into a repository](#id26)
### Tag an image into a repository
`POST /images/`(*name*)`/tag`
: Tag the image `name` into a repository
`POST /images/(name)/tag`
Tag the image `name` into a repository
**Example request**:
@@ -896,10 +912,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### [Remove an image](#id27)
### Remove an image
`DELETE /images/`(*name*)
: Remove the image `name` from the filesystem
`DELETE /images/(name)`
Remove the image `name` from the filesystem
**Example request**:
@@ -923,14 +940,15 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### [Search images](#id28)
### Search images
`GET /images/search`
: Search for an image in the docker index.
`GET /images/search`
Search for an image in the docker index.
> **Note**:
> The response keys have changed from API v1.6 to reflect the JSON
> sent by the registry server to the docker daemon’s request.
> sent by the registry server to the docker daemon's request.
**Example request**:
@@ -977,12 +995,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
### [2.3 Misc](#id29)
## 2.3 Misc
#### [Build an image from Dockerfile via stdin](#id30)
### Build an image from Dockerfile via stdin
`POST /build`
: Build an image from Dockerfile via stdin
`POST /build`
Build an image from Dockerfile via stdin
**Example request**:
@@ -1003,7 +1022,7 @@ page_keywords: API, Docker, rcli, REST, documentation
following algorithms: identity (no compression), gzip, bzip2, xz.
The archive must include a file called `Dockerfile`
at its root. It may include any number of other files,
at its root. It may include any number of other files,
which will be accessible in the build context (See the [*ADD build
command*](../../../builder/#dockerbuilder)).
@@ -1029,10 +1048,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Check auth configuration](#id31)
### Check auth configuration
`POST /auth`
: Get the default username and email
`POST /auth`
Get the default username and email
**Example request**:
@@ -1056,10 +1076,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **204** – no error
- **500** – server error
#### [Display system-wide information](#id32)
### Display system-wide information
`GET /info`
: Display system-wide information
`GET /info`
Display system-wide information
**Example request**:
@@ -1086,10 +1107,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Show the docker version information](#id33)
### Show the docker version information
`GET /version`
: Show the docker version information
`GET /version`
Show the docker version information
**Example request**:
@@ -1111,10 +1133,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Create a new image from a container’s changes](#id34)
### Create a new image from a container's changes
`POST /commit`
: Create a new image from a container’s changes
`POST /commit`
Create a new image from a container's changes
**Example request**:
@@ -1136,7 +1159,7 @@ page_keywords: API, Docker, rcli, REST, documentation
- **tag** – tag
- **m** – commit message
- **author** – author (eg. "John Hannibal Smith
\<[hannibal@a-team.com](mailto:hannibal%40a-team.com)\>")
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
- **run** – config automatically applied when the image is run.
(ex: {"Cmd": ["cat", "/world"], "PortSpecs":["22"]})
@@ -1146,11 +1169,12 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### [Monitor Docker’s events](#id35)
### Monitor Docker's events
`GET /events`
: Get events from docker, either in real time via streaming, or via
polling (using since)
`GET /events`
Get events from docker, either in real time via streaming,
or via polling (using since)
**Example request**:
@@ -1177,11 +1201,12 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Get a tarball containing all images and tags in a repository](#id36)
### Get a tarball containing all images and tags in a repository
`GET /images/`(*name*)`/get`
: Get a tarball containing all images and metadata for the repository
specified by `name`.
`GET /images/(name)/get`
Get a tarball containing all images and metadata for the repository
specified by `name`.
**Example request**
@@ -1199,10 +1224,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### [Load a tarball with a set of images and tags into docker](#id37)
### Load a tarball with a set of images and tags into docker
`POST /images/load`
: Load a set of images and tags into the docker repository.
`POST /images/load`
Load a set of images and tags into the docker repository.
**Example request**
@@ -1219,33 +1245,33 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
## [3. Going further](#id38)
# 3. Going further
### [3.1 Inside ‘docker run’](#id39)
## 3.1 Inside `docker run`
Here are the steps of ‘docker run’ :
Here are the steps of `docker run`:
- Create the container
- Create the container
- If the status code is 404, it means the image doesn’t exists:
: - Try to pull it
- Then retry to create the container
- If the status code is 404, it means the image doesn't exists:
- Try to pull it
- Then retry to create the container
- Start the container
- Start the container
- If you are not in detached mode:
: - Attach to the container, using logs=1 (to have stdout and
stderr from the container’s start) and stream=1
- If you are not in detached mode:
- Attach to the container, using logs=1 (to have stdout and
stderr from the container's start) and stream=1
- If in detached mode or only stdin is attached:
: - Display the container’s id
- If in detached mode or only stdin is attached:
- Display the container's id
### [3.2 Hijacking](#id40)
## 3.2 Hijacking
In this version of the API, /attach, uses hijacking to transport stdin,
stdout and stderr on the same socket. This might change in the future.
### [3.3 CORS Requests](#id41)
## 3.3 CORS Requests
To enable cross origin requests to the remote api add the flag
"–api-enable-cors" when running docker in daemon mode.
docs/sources/reference/api/docker_io_accounts_api.md
+29 -25
View File
@@ -8,8 +8,9 @@ page_keywords: API, Docker, accounts, REST, documentation
### 1.1 Get a single user
`GET /api/v1.1/users/:username/`
: Get profile info for the specified user.
`GET /api/v1.1/users/:username/`
Get profile info for the specified user.
Parameters:
@@ -61,8 +62,9 @@ page_keywords: API, Docker, accounts, REST, documentation
### 1.2 Update a single user
`PATCH /api/v1.1/users/:username/`
: Update profile info for the specified user.
`PATCH /api/v1.1/users/:username/`
Update profile info for the specified user.
Parameters:
@@ -73,11 +75,11 @@ page_keywords: API, Docker, accounts, REST, documentation
 
- **full\_name** (*string*) – (optional) the new name of the user.
- **full_name** (*string*) – (optional) the new name of the user.
- **location** (*string*) – (optional) the new location.
- **company** (*string*) – (optional) the new company of the user.
- **profile\_url** (*string*) – (optional) the new profile url.
- **gravatar\_email** (*string*) – (optional) the new Gravatar
- **profile_url** (*string*) – (optional) the new profile url.
- **gravatar_email** (*string*) – (optional) the new Gravatar
email address.
Request Headers:
@@ -134,8 +136,9 @@ page_keywords: API, Docker, accounts, REST, documentation
### 1.3 List email addresses for a user
`GET /api/v1.1/users/:username/emails/`
: List email info for the specified user.
`GET /api/v1.1/users/:username/emails/`
List email info for the specified user.
Parameters:
@@ -180,10 +183,11 @@ page_keywords: API, Docker, accounts, REST, documentation
### 1.4 Add email address for a user
`POST /api/v1.1/users/:username/emails/`
: Add a new email address to the specified user’s account. The email
address must be verified separately, a confirmation email is not
automatically sent.
`POST /api/v1.1/users/:username/emails/`
Add a new email address to the specified user's account. The email
address must be verified separately, a confirmation email is not
automatically sent.
Json Parameters:
@@ -235,12 +239,13 @@ page_keywords: API, Docker, accounts, REST, documentation
### 1.5 Update an email address for a user
`PATCH /api/v1.1/users/:username/emails/`
: Update an email address for the specified user to either verify an
email address or set it as the primary email for the user. You
cannot use this endpoint to un-verify an email address. You cannot
use this endpoint to unset the primary email, only set another as
the primary.
`PATCH /api/v1.1/users/:username/emails/`
Update an email address for the specified user to either verify an
email address or set it as the primary email for the user. You
cannot use this endpoint to un-verify an email address. You cannot
use this endpoint to unset the primary email, only set another as
the primary.
Parameters:
@@ -269,7 +274,7 @@ page_keywords: API, Docker, accounts, REST, documentation
Status Codes:
- **200** – success, user’s email updated.
- **200** – success, user's email updated.
- **400** – data validation error.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
@@ -305,9 +310,10 @@ page_keywords: API, Docker, accounts, REST, documentation
### 1.6 Delete email address for a user
`DELETE /api/v1.1/users/:username/emails/`
: Delete an email address from the specified user’s account. You
cannot delete a user’s primary email address.
`DELETE /api/v1.1/users/:username/emails/`
Delete an email address from the specified user's account. You
cannot delete a user's primary email address.
Json Parameters:
@@ -351,5 +357,3 @@ page_keywords: API, Docker, accounts, REST, documentation
HTTP/1.1 204 NO CONTENT
Content-Length: 0
docs/sources/reference/api/docker_io_oauth_api.md
+44 -42
View File
@@ -27,46 +27,47 @@ request registration of your application send an email to
[support-accounts@docker.com](mailto:support-accounts%40docker.com) with
the following information:
- The name of your application
- A description of your application and the service it will provide to
docker.io users.
- A callback URI that we will use for redirecting authorization
requests to your application. These are used in the step of getting
an Authorization Code. The domain name of the callback URI will be
visible to the user when they are requested to authorize your
application.
- The name of your application
- A description of your application and the service it will provide to
docker.io users.
- A callback URI that we will use for redirecting authorization
requests to your application. These are used in the step of getting
an Authorization Code. The domain name of the callback URI will be
visible to the user when they are requested to authorize your
application.
When your application is approved you will receive a response from the
docker.io team with your `client_id` and
`client_secret` which your application will use in
the steps of getting an Authorization Code and getting an Access Token.
## 3. Endpoints
# 3. Endpoints
### 3.1 Get an Authorization Code
## 3.1 Get an Authorization Code
Once You have registered you are ready to start integrating docker.io
accounts into your application! The process is usually started by a user
following a link in your application to an OAuth Authorization endpoint.
`GET /api/v1.1/o/authorize/`
: Request that a docker.io user authorize your application. If the
user is not already logged in, they will be prompted to login. The
user is then presented with a form to authorize your application for
the requested access scope. On submission, the user will be
redirected to the specified `redirect_uri` with
an Authorization Code.
`GET /api/v1.1/o/authorize/`
Request that a docker.io user authorize your application. If the
user is not already logged in, they will be prompted to login. The
user is then presented with a form to authorize your application for
the requested access scope. On submission, the user will be
redirected to the specified `redirect_uri` with
an Authorization Code.
Query Parameters:
 
- **client\_id** – The `client_id` given to
- **client_id** – The `client_id` given to
your application at registration.
- **response\_type** – MUST be set to `code`.
- **response_type** – MUST be set to `code`.
This specifies that you would like an Authorization Code
returned.
- **redirect\_uri** – The URI to redirect back to after the user
- **redirect_uri** – The URI to redirect back to after the user
has authorized your application. If omitted, the first of your
registered `response_uris` is used. If
included, it must be one of the URIs which were submitted when
@@ -95,7 +96,7 @@ following a link in your application to an OAuth Authorization endpoint.
prompt which asks the user to authorize your application with a
description of the requested scopes.
![](../../../_images/io_oauth_authorization_page.png)
![](../../../static_files/io_oauth_authorization_page.png)
Once the user allows or denies your Authorization Request the user
will be redirected back to your application. Included in that
@@ -113,34 +114,35 @@ following a link in your application to an OAuth Authorization endpoint.
: An error message in the event of the user denying the
authorization or some other kind of error with the request.
### 3.2 Get an Access Token
## 3.2 Get an Access Token
Once the user has authorized your application, a request will be made to
your application’s specified `redirect_uri` which
your application'sspecified `redirect_uri` which
includes a `code` parameter that you must then use
to get an Access Token.
`POST /api/v1.1/o/token/`
: Submit your newly granted Authorization Code and your application’s
credentials to receive an Access Token and Refresh Token. The code
is valid for 60 seconds and cannot be used more than once.
`POST /api/v1.1/o/token/`
Submit your newly granted Authorization Code and your application's
credentials to receive an Access Token and Refresh Token. The code
is valid for 60 seconds and cannot be used more than once.
Request Headers:
 
- **Authorization** – HTTP basic authentication using your
application’s `client_id` and
application's `client_id` and
`client_secret`
Form Parameters:
 
- **grant\_type** – MUST be set to `authorization_code`
- **code** – The authorization code received from the user’s
- **grant_type** – MUST be set to `authorization_code`
- **code** – The authorization code received from the user's
redirect request.
- **redirect\_uri** – The same `redirect_uri`
- **redirect_uri** – The same `redirect_uri`
used in the authentication request.
**Example Request**
@@ -177,31 +179,32 @@ to get an Access Token.
In the case of an error, there will be a non-200 HTTP Status and and
data detailing the error.
### 3.3 Refresh a Token
## 3.3 Refresh a Token
Once the Access Token expires you can use your `refresh_token`
to have docker.io issue your application a new Access Token,
if the user has not revoked access from your application.
`POST /api/v1.1/o/token/`
: Submit your `refresh_token` and application’s
credentials to receive a new Access Token and Refresh Token. The
`refresh_token` can be used only once.
`POST /api/v1.1/o/token/`
Submit your `refresh_token` and application's
credentials to receive a new Access Token and Refresh Token. The
`refresh_token` can be used only once.
Request Headers:
 
- **Authorization** – HTTP basic authentication using your
application’s `client_id` and
application's `client_id` and
`client_secret`
Form Parameters:
 
- **grant\_type** – MUST be set to `refresh_token`
- **refresh\_token** – The `refresh_token`
- **grant_type** – MUST be set to `refresh_token`
- **refresh_token** – The `refresh_token`
which was issued to your application.
- **scope** – (optional) The scope of the access token to be
returned. Must not include any scope not originally granted by
@@ -241,11 +244,10 @@ if the user has not revoked access from your application.
In the case of an error, there will be a non-200 HTTP Status and and
data detailing the error.
## 4. Use an Access Token with the API
# 4. Use an Access Token with the API
Many of the docker.io API requests will require a Authorization request
header field. Simply ensure you add this header with "Bearer
\<`access_token`\>":
header field. Simply ensure you add this header with "Bearer <`access_token`>":
GET /api/v1.1/resource HTTP/1.1
Host: docker.io
docs/sources/reference/api/docker_remote_api.md
+155 -123
View File
@@ -6,31 +6,30 @@ page_keywords: API, Docker, rcli, REST, documentation
## 1. Brief introduction
- The Remote API is replacing rcli
- By default the Docker daemon listens on unix:///var/run/docker.sock
and the client must have root access to interact with the daemon
- If a group named *docker* exists on your system, docker will apply
ownership of the socket to the group
- The API tends to be REST, but for some complex commands, like attach
or pull, the HTTP connection is hijacked to transport stdout stdin
and stderr
- Since API version 1.2, the auth configuration is now handled client
side, so the client has to send the authConfig as POST in
/images/(name)/push
- authConfig, set as the `X-Registry-Auth` header,
is currently a Base64 encoded (json) string with credentials:
`{'username': string, 'password': string, 'email': string, 'serveraddress' : string}`
- The Remote API is replacing rcli
- By default the Docker daemon listens on unix:///var/run/docker.sock
and the client must have root access to interact with the daemon
- If a group named *docker* exists on your system, docker will apply
ownership of the socket to the group
- The API tends to be REST, but for some complex commands, like attach
or pull, the HTTP connection is hijacked to transport stdout stdin
and stderr
- Since API version 1.2, the auth configuration is now handled client
side, so the client has to send the authConfig as POST in /images/(name)/push
- authConfig, set as the `X-Registry-Auth` header, is currently a Base64
encoded (json) string with credentials:
`{'username': string, 'password': string, 'email': string, 'serveraddress' : string}`
## 2. Versions
The current version of the API is 1.11
Calling /images/\<name\>/insert is the same as calling
/v1.11/images/\<name\>/insert
Calling /images/<name>/insert is the same as calling
/v1.11/images/<name>/insert
You can still call an old version of the api using
/v1.11/images/\<name\>/insert
/v1.11/images/<name>/insert
### v1.11
@@ -38,11 +37,13 @@ You can still call an old version of the api using
[*Docker Remote API v1.11*](../docker_remote_api_v1.11/)
#### What’s new
#### What's new
`GET /events`
: **New!** You can now use the `-until` parameter
to close connection after timestamp.
`GET /events`
**New!**
You can now use the `-until` parameter to close connection
after timestamp.
### v1.10
@@ -50,16 +51,21 @@ You can still call an old version of the api using
[*Docker Remote API v1.10*](../docker_remote_api_v1.10/)
#### What’s new
#### What's new
`DELETE /images/`(*name*)
: **New!** You can now use the force parameter to force delete of an
image, even if it’s tagged in multiple repositories. **New!** You
`DELETE /images/(name)`
**New!**
You can now use the force parameter to force delete of an
image, even if it's tagged in multiple repositories. **New!**
You
can now use the noprune parameter to prevent the deletion of parent
images
`DELETE /containers/`(*id*)
: **New!** You can now use the force paramter to force delete a
`DELETE /containers/(id)`
**New!**
You can now use the force paramter to force delete a
container, even if it is currently running
### v1.9
@@ -68,51 +74,58 @@ You can still call an old version of the api using
[*Docker Remote API v1.9*](../docker_remote_api_v1.9/)
#### What’s new
#### What's new
`POST /build`
: **New!** This endpoint now takes a serialized ConfigFile which it
uses to resolve the proper registry auth credentials for pulling the
base image. Clients which previously implemented the version
accepting an AuthConfig object must be updated.
`POST /build`
**New!**
This endpoint now takes a serialized ConfigFile which it
uses to resolve the proper registry auth credentials for pulling the
base image. Clients which previously implemented the version
accepting an AuthConfig object must be updated.
### v1.8
#### Full Documentation
#### What’s new
#### What's new
`POST /build`
: **New!** This endpoint now returns build status as json stream. In
case of a build error, it returns the exit status of the failed
command.
`POST /build`
`GET /containers/`(*id*)`/json`
: **New!** This endpoint now returns the host config for the
container.
**New!**
This endpoint now returns build status as json stream. In
case of a build error, it returns the exit status of the failed
command.
`POST /images/create`
:
`GET /containers/(id)/json`
`POST /images/`(*name*)`/insert`
:
**New!**
This endpoint now returns the host config for the
container.
`POST /images/`(*name*)`/push`
: **New!** progressDetail object was added in the JSON. It’s now
possible to get the current value and the total of the progress
without having to parse the string.
`POST /images/create`
`POST /images/(name)/insert`
`POST /images/(name)/push`
**New!**
progressDetail object was added in the JSON. It's now
possible to get the current value and the total of the progress
without having to parse the string.
### v1.7
#### Full Documentation
#### What’s new
#### What's new
`GET /images/json`
: The format of the json returned from this uri changed. Instead of an
entry for each repo/tag on an image, each image is only represented
once, with a nested attribute indicating the repo/tags that apply to
that image.
`GET /images/json`
The format of the json returned from this uri changed. Instead of an
entry for each repo/tag on an image, each image is only represented
once, with a nested attribute indicating the repo/tags that apply to
that image.
Instead of:
@@ -192,60 +205,74 @@ You can still call an old version of the api using
}
]
`GET /images/viz`
: This URI no longer exists. The `images --viz`
output is now generated in the client, using the
`/images/json` data.
`GET /images/viz`
This URI no longer exists. The `images --viz`
output is now generated in the client, using the
`/images/json` data.
### v1.6
#### Full Documentation
#### What’s new
#### What's new
`POST /containers/`(*id*)`/attach`
: **New!** You can now split stderr from stdout. This is done by
prefixing a header to each transmition. See
[`POST /containers/(id)/attach`
](../docker_remote_api_v1.9/#post--containers-(id)-attach "POST /containers/(id)/attach").
The WebSocket attach is unchanged. Note that attach calls on the
previous API version didn’t change. Stdout and stderr are merged.
`POST /containers/(id)/attach`
**New!**
You can now split stderr from stdout. This is done by
prefixing a header to each transmition. See
[`POST /containers/(id)/attach`](
../docker_remote_api_v1.9/#post--containers-(id)-attach "POST /containers/(id)/attach").
The WebSocket attach is unchanged. Note that attach calls on the
previous API version didn't change. Stdout and stderr are merged.
### v1.5
#### Full Documentation
#### What’s new
#### What's new
`POST /images/create`
: **New!** You can now pass registry credentials (via an AuthConfig
`POST /images/create`
**New!**
You can now pass registry credentials (via an AuthConfig
object) through the X-Registry-Auth header
`POST /images/`(*name*)`/push`
: **New!** The AuthConfig object now needs to be passed through the
`POST /images/(name)/push`
**New!**
The AuthConfig object now needs to be passed through the
X-Registry-Auth header
`GET /containers/json`
: **New!** The format of the Ports entry has been changed to a list of
dicts each containing PublicPort, PrivatePort and Type describing a
port mapping.
`GET /containers/json`
**New!**
The format of the Ports entry has been changed to a list of
dicts each containing PublicPort, PrivatePort and Type describing a
port mapping.
### v1.4
#### Full Documentation
#### What’s new
#### What's new
`POST /images/create`
: **New!** When pulling a repo, all images are now downloaded in
parallel.
`POST /images/create`
`GET /containers/`(*id*)`/top`
: **New!** You can now use ps args with docker top, like docker top
\<container\_id\> aux
**New!**
When pulling a repo, all images are now downloaded in parallel.
`GET /events:`
: **New!** Image’s name added in the events
`GET /containers/(id)/top`
**New!**
You can now use ps args with docker top, like docker top
<container_id> aux
`GET /events`
**New!**
Image's name added in the events
### v1.3
@@ -254,20 +281,23 @@ docker v0.5.0
#### Full Documentation
#### What’s new
#### What's new
`GET /containers/`(*id*)`/top`
: List the processes running inside a container.
`GET /containers/(id)/top`
`GET /events:`
: **New!** Monitor docker’s events via streaming or via polling
List the processes running inside a container.
`GET /events`
**New!**
Monitor docker's events via streaming or via polling
Builder (/build):
- Simplify the upload of the build context
- Simply stream a tarball instead of multipart upload with 4
intermediary buffers
- Simpler, less memory usage, less disk usage and faster
- Simplify the upload of the build context
- Simply stream a tarball instead of multipart upload with 4
intermediary buffers
- Simpler, less memory usage, less disk usage and faster
> **Warning**:
> The /build improvements are not reverse-compatible. Pre 1.3 clients will
@@ -275,12 +305,12 @@ Builder (/build):
List containers (/containers/json):
- You can use size=1 to get the size of the containers
- You can use size=1 to get the size of the containers
Start containers (/containers/\<id\>/start):
Start containers (/containers/<id>/start):
- You can now pass host-specific configuration (e.g. bind mounts) in
the POST body for start calls
- You can now pass host-specific configuration (e.g. bind mounts) in
the POST body for start calls
### v1.2
@@ -289,25 +319,28 @@ docker v0.4.2
#### Full Documentation
#### What’s new
#### What's new
The auth configuration is now handled by the client.
The client should send it’s authConfig as POST on each call of
/images/(name)/push
The client should send it's authConfig as POST on each call of
`/images/(name)/push`
`GET /auth`
: **Deprecated.**
`GET /auth`
`POST /auth`
: Only checks the configuration but doesn’t store it on the server
**Deprecated.**
`POST /auth`
Only checks the configuration but doesn't store it on the server
Deleting an image is now improved, will only untag the image if it
has children and remove all the untagged parents if has any.
`POST /images/<name>/delete`
: Now returns a JSON structure with the list of images
deleted/untagged.
`POST /images/<name>/delete`
Now returns a JSON structure with the list of images
deleted/untagged.
### v1.1
@@ -316,24 +349,23 @@ docker v0.4.0
#### Full Documentation
#### What’s new
#### What's new
`POST /images/create`
:
`POST /images/create`
`POST /images/`(*name*)`/insert`
:
`POST /images/(name)/insert`
`POST /images/`(*name*)`/push`
: Uses json stream instead of HTML hijack, it looks like this:
`POST /images/(name)/push`
> HTTP/1.1 200 OK
> Content-Type: application/json
>
> {"status":"Pushing..."}
> {"status":"Pushing", "progress":"1/? (n/a)"}
> {"error":"Invalid..."}
> ...
Uses json stream instead of HTML hijack, it looks like this:
HTTP/1.1 200 OK
Content-Type: application/json
{"status":"Pushing..."}
{"status":"Pushing", "progress":"1/? (n/a)"}
{"error":"Invalid..."}
...
### v1.0
@@ -342,6 +374,6 @@ docker v0.3.4
#### Full Documentation
#### What’s new
#### What's new
Initial version
docs/sources/reference/api/docker_remote_api_v1.10.md
+148 -121
View File
@@ -6,23 +6,23 @@ page_keywords: API, Docker, rcli, REST, documentation
## 1. Brief introduction
- The Remote API has replaced rcli
- The daemon listens on `unix:///var/run/docker.sock`
, but you can [*Bind Docker to another host/port or a Unix
socket*](../../../use/basics/#bind-docker).
- The API tends to be REST, but for some complex commands, like
`attach` or `pull`, the HTTP
connection is hijacked to transport `stdout, stdin`
and `stderr`
- The Remote API has replaced rcli
- The daemon listens on `unix:///var/run/docker.sock` but you can
[*Bind Docker to another host/port or a Unix socket*](
../../../use/basics/#bind-docker).
- The API tends to be REST, but for some complex commands, like `attach`
or `pull`, the HTTP connection is hijacked to transport `stdout, stdin`
and `stderr`
## 2. Endpoints
# 2. Endpoints
### 2.1 Containers
## 2.1 Containers
#### List containers
### List containers
`GET /containers/json`
: List containers
`GET /containers/json`
List containers
**Example request**:
@@ -97,10 +97,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### Create a container
### Create a container
`POST /containers/create`
: Create a container
`POST /containers/create`
Create a container
**Example request**:
@@ -149,7 +150,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **config** – the container’s configuration
- **config** – the container's configuration
Query Parameters:
@@ -165,11 +166,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **406** – impossible to attach (container not running)
- **500** – server error
#### Inspect a container
### Inspect a container
`GET /containers/`(*id*)`/json`
: Return low-level information on the container `id`
`GET /containers/(id)/json`
Return low-level information on the container `id`
**Example request**:
@@ -248,10 +249,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### List processes running inside a container
### List processes running inside a container
`GET /containers/`(*id*)`/top`
: List processes running inside the container `id`
`GET /containers/(id)/top`
List processes running inside the container `id`
**Example request**:
@@ -294,10 +296,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Inspect changes on a container’s filesystem
### Inspect changes on a container's filesystem
`GET /containers/`(*id*)`/changes`
: Inspect changes on container `id` ‘s filesystem
`GET /containers/(id)/changes`
Inspect changes on container `id` 's filesystem
**Example request**:
@@ -329,10 +332,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Export a container
### Export a container
`GET /containers/`(*id*)`/export`
: Export the contents of container `id`
`GET /containers/(id)/export`
Export the contents of container `id`
**Example request**:
@@ -351,10 +355,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Start a container
### Start a container
`POST /containers/`(*id*)`/start`
: Start the container `id`
`POST /containers/(id)/start`
Start the container `id`
**Example request**:
@@ -380,7 +385,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **hostConfig** – the container’s host configuration (optional)
- **hostConfig** – the container's host configuration (optional)
Status Codes:
@@ -388,10 +393,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Stop a container
### Stop a container
`POST /containers/`(*id*)`/stop`
: Stop the container `id`
`POST /containers/(id)/stop`
Stop the container `id`
**Example request**:
@@ -413,10 +419,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Restart a container
### Restart a container
`POST /containers/`(*id*)`/restart`
: Restart the container `id`
`POST /containers/(id)/restart`
Restart the container `id`
**Example request**:
@@ -438,10 +445,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Kill a container
### Kill a container
`POST /containers/`(*id*)`/kill`
: Kill the container `id`
`POST /containers/(id)/kill`
Kill the container `id`
**Example request**:
@@ -457,10 +465,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Attach to a container
### Attach to a container
`POST /containers/`(*id*)`/attach`
: Attach to the container `id`
`POST /containers/(id)/attach`
Attach to the container `id`
**Example request**:
@@ -500,7 +509,7 @@ page_keywords: API, Docker, rcli, REST, documentation
When using the TTY setting is enabled in
[`POST /containers/create`
](../docker_remote_api_v1.9/#post--containers-create "POST /containers/create"),
the stream is the raw data from the process PTY and client’s stdin.
the stream is the raw data from the process PTY and client's stdin.
When the TTY is disabled, then the stream is multiplexed to separate
stdout and stderr.
@@ -539,10 +548,11 @@ page_keywords: API, Docker, rcli, REST, documentation
4. Read the extracted size and output it on the correct output
5. Goto 1)
#### Wait a container
### Wait a container
`POST /containers/`(*id*)`/wait`
: Block until container `id` stops, then returns
`POST /containers/(id)/wait`
Block until container `id` stops, then returns
the exit code
**Example request**:
@@ -562,9 +572,9 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Remove a container
### Remove a container
`DELETE /containers/`(*id*)
`DELETE /containers/(id*)
: Remove the container `id` from the filesystem
**Example request**:
@@ -591,10 +601,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Copy files or folders from a container
### Copy files or folders from a container
`POST /containers/`(*id*)`/copy`
: Copy files or folders of container `id`
`POST /containers/(id)/copy`
Copy files or folders of container `id`
**Example request**:
@@ -620,10 +631,11 @@ page_keywords: API, Docker, rcli, REST, documentation
### 2.2 Images
#### List Images
### List Images
`GET /images/json`
: **Example request**:
`GET /images/json`
**Example request**:
GET /images/json?all=0 HTTP/1.1
@@ -657,10 +669,11 @@ page_keywords: API, Docker, rcli, REST, documentation
}
]
#### Create an image
### Create an image
`POST /images/create`
: Create an image, either by pull it from the registry or by importing
`POST /images/create`
Create an image, either by pull it from the registry or by importing
it
**Example request**:
@@ -702,10 +715,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Insert a file in an image
### Insert a file in an image
`POST /images/`(*name*)`/insert`
: Insert a file from `url` in the image
`POST /images/(name)/insert`
Insert a file from `url` in the image
`name` at `path`
**Example request**:
@@ -727,10 +741,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Inspect an image
### Inspect an image
`GET /images/`(*name*)`/json`
: Return low-level information on the image `name`
`GET /images/(name)/json`
Return low-level information on the image `name`
**Example request**:
@@ -774,10 +789,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### Get the history of an image
### Get the history of an image
`GET /images/`(*name*)`/history`
: Return the history of the image `name`
`GET /images/(name)/history`
Return the history of the image `name`
**Example request**:
@@ -807,10 +823,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### Push an image on the registry
### Push an image on the registry
`POST /images/`(*name*)`/push`
: Push the image `name` on the registry
`POST /images/(name)/push`
Push the image `name` on the registry
**Example request**:
@@ -845,10 +862,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### Tag an image into a repository
### Tag an image into a repository
`POST /images/`(*name*)`/tag`
: Tag the image `name` into a repository
`POST /images/(name)/tag`
Tag the image `name` into a repository
**Example request**:
@@ -873,9 +891,9 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### Remove an image
### Remove an image
`DELETE /images/`(*name*)
`DELETE /images/(name*)
: Remove the image `name` from the filesystem
**Example request**:
@@ -907,14 +925,15 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### Search images
### Search images
`GET /images/search`
: Search for an image in the docker index.
`GET /images/search`
Search for an image in the docker index.
> **Note**:
> The response keys have changed from API v1.6 to reflect the JSON
> sent by the registry server to the docker daemon’s request.
> sent by the registry server to the docker daemon's request.
**Example request**:
@@ -963,10 +982,11 @@ page_keywords: API, Docker, rcli, REST, documentation
### 2.3 Misc
#### Build an image from Dockerfile via stdin
### Build an image from Dockerfile via stdin
`POST /build`
: Build an image from Dockerfile via stdin
`POST /build`
Build an image from Dockerfile via stdin
**Example request**:
@@ -1013,10 +1033,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Check auth configuration
### Check auth configuration
`POST /auth`
: Get the default username and email
`POST /auth`
Get the default username and email
**Example request**:
@@ -1040,10 +1061,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **204** – no error
- **500** – server error
#### Display system-wide information
### Display system-wide information
`GET /info`
: Display system-wide information
`GET /info`
Display system-wide information
**Example request**:
@@ -1070,10 +1092,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Show the docker version information
### Show the docker version information
`GET /version`
: Show the docker version information
`GET /version`
Show the docker version information
**Example request**:
@@ -1095,10 +1118,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Create a new image from a container’s changes
### Create a new image from a container's changes
`POST /commit`
: Create a new image from a container’s changes
`POST /commit`
Create a new image from a container's changes
**Example request**:
@@ -1120,7 +1144,7 @@ page_keywords: API, Docker, rcli, REST, documentation
- **tag** – tag
- **m** – commit message
- **author** – author (eg. "John Hannibal Smith
\<[hannibal@a-team.com](mailto:hannibal%40a-team.com)\>")
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
- **run** – config automatically applied when the image is run.
(ex: {"Cmd": ["cat", "/world"], "PortSpecs":["22"]})
@@ -1130,10 +1154,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Monitor Docker’s events
### Monitor Docker's events
`GET /events`
: Get events from docker, either in real time via streaming, or via
`GET /events`
Get events from docker, either in real time via streaming, or via
polling (using since)
**Example request**:
@@ -1161,10 +1186,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Get a tarball containing all images and tags in a repository
### Get a tarball containing all images and tags in a repository
`GET /images/`(*name*)`/get`
: Get a tarball containing all images and metadata for the repository
`GET /images/(name)/get`
Get a tarball containing all images and metadata for the repository
specified by `name`.
**Example request**
@@ -1183,10 +1209,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Load a tarball with a set of images and tags into docker
### Load a tarball with a set of images and tags into docker
`POST /images/load`
: Load a set of images and tags into the docker repository.
`POST /images/load`
Load a set of images and tags into the docker repository.
**Example request**
@@ -1203,33 +1230,33 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
## 3. Going further
# 3. Going further
### 3.1 Inside ‘docker run’
## 3.1 Inside `docker run`
Here are the steps of ‘docker run’ :
Here are the steps of `docker run` :
- Create the container
- Create the container
- If the status code is 404, it means the image doesn’t exists:
: - Try to pull it
- Then retry to create the container
- If the status code is 404, it means the image doesn't exists:
- Try to pull it
- Then retry to create the container
- Start the container
- Start the container
- If you are not in detached mode:
: - Attach to the container, using logs=1 (to have stdout and
stderr from the container’s start) and stream=1
- If you are not in detached mode:
- Attach to the container, using logs=1 (to have stdout and
stderr from the container's start) and stream=1
- If in detached mode or only stdin is attached:
: - Display the container’s id
- If in detached mode or only stdin is attached:
- Display the container's id
### 3.2 Hijacking
## 3.2 Hijacking
In this version of the API, /attach, uses hijacking to transport stdin,
stdout and stderr on the same socket. This might change in the future.
### 3.3 CORS Requests
## 3.3 CORS Requests
To enable cross origin requests to the remote api add the flag
"–api-enable-cors" when running docker in daemon mode.
docs/sources/reference/api/docker_remote_api_v1.11.md
+160 -133
View File
@@ -6,23 +6,23 @@ page_keywords: API, Docker, rcli, REST, documentation
## 1. Brief introduction
- The Remote API has replaced rcli
- The daemon listens on `unix:///var/run/docker.sock`
, but you can [*Bind Docker to another host/port or a Unix
socket*](../../../use/basics/#bind-docker).
- The API tends to be REST, but for some complex commands, like
`attach` or `pull`, the HTTP
connection is hijacked to transport `stdout, stdin`
and `stderr`
- The Remote API has replaced rcli
- The daemon listens on `unix:///var/run/docker.sock` but you can
[*Bind Docker to another host/port or a Unix socket*](
../../../use/basics/#bind-docker).
- The API tends to be REST, but for some complex commands, like `attach`
or `pull`, the HTTP connection is hijacked to transport `stdout, stdin`
and `stderr`
## 2. Endpoints
# 2. Endpoints
### 2.1 Containers
## 2.1 Containers
#### List containers
### List containers
`GET /containers/json`
: List containers
`GET /containers/json`
List containers
**Example request**:
@@ -97,10 +97,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### Create a container
### Create a container
`POST /containers/create`
: Create a container
`POST /containers/create`
Create a container
**Example request**:
@@ -150,7 +151,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **config** – the container’s configuration
- **config** – the container's configuration
Query Parameters:
@@ -166,10 +167,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **406** – impossible to attach (container not running)
- **500** – server error
#### Inspect a container
### Inspect a container
`GET /containers/`(*id*)`/json`
: Return low-level information on the container `id`
`GET /containers/(id)/json`
Return low-level information on the container `id`
**Example request**:
@@ -251,10 +253,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### List processes running inside a container
### List processes running inside a container
`GET /containers/`(*id*)`/top`
: List processes running inside the container `id`
`GET /containers/(id)/top`
List processes running inside the container `id`
**Example request**:
@@ -289,7 +292,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **ps\_args** – ps arguments to use (eg. aux)
- **ps_args** – ps arguments to use (eg. aux)
Status Codes:
@@ -297,10 +300,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Inspect changes on a container’s filesystem
### Inspect changes on a container's filesystem
`GET /containers/`(*id*)`/changes`
: Inspect changes on container `id` ‘s filesystem
`GET /containers/(id)/changes`
Inspect changes on container `id`'s filesystem
**Example request**:
@@ -332,10 +336,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Export a container
### Export a container
`GET /containers/`(*id*)`/export`
: Export the contents of container `id`
`GET /containers/(id)/export`
Export the contents of container `id`
**Example request**:
@@ -354,10 +359,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Start a container
### Start a container
`POST /containers/`(*id*)`/start`
: Start the container `id`
`POST /containers/(id)/start`
Start the container `id`
**Example request**:
@@ -381,7 +387,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **hostConfig** – the container’s host configuration (optional)
- **hostConfig** – the container's host configuration (optional)
Status Codes:
@@ -389,10 +395,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Stop a container
### Stop a container
`POST /containers/`(*id*)`/stop`
: Stop the container `id`
`POST /containers/(id)/stop`
Stop the container `id`
**Example request**:
@@ -414,10 +421,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Restart a container
### Restart a container
`POST /containers/`(*id*)`/restart`
: Restart the container `id`
`POST /containers/(id)/restart`
Restart the container `id`
**Example request**:
@@ -439,10 +447,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Kill a container
### Kill a container
`POST /containers/`(*id*)`/kill`
: Kill the container `id`
`POST /containers/(id)/kill`
Kill the container `id`
**Example request**:
@@ -458,10 +467,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Attach to a container
### Attach to a container
`POST /containers/`(*id*)`/attach`
: Attach to the container `id`
`POST /containers/(id)/attach`
Attach to the container `id`
**Example request**:
@@ -500,8 +510,8 @@ page_keywords: API, Docker, rcli, REST, documentation
When using the TTY setting is enabled in
[`POST /containers/create`
](../docker_remote_api_v1.9/#post--containers-create "POST /containers/create"),
the stream is the raw data from the process PTY and client’s stdin.
](../docker_remote_api_v1.9/#post--containers-create "POST /containers/create"),
the stream is the raw data from the process PTY and client's stdin.
When the TTY is disabled, then the stream is multiplexed to separate
stdout and stderr.
@@ -540,11 +550,11 @@ page_keywords: API, Docker, rcli, REST, documentation
4. Read the extracted size and output it on the correct output
5. Goto 1)
#### Wait a container
### Wait a container
`POST /containers/`(*id*)`/wait`
: Block until container `id` stops, then returns
the exit code
`POST /containers/(id)/wait`
Block until container `id` stops, then returns the exit code
**Example request**:
@@ -563,10 +573,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Remove a container
### Remove a container
`DELETE /containers/`(*id*)
: Remove the container `id` from the filesystem
`DELETE /containers/(id)`
Remove the container `id` from the filesystem
**Example request**:
@@ -592,10 +603,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Copy files or folders from a container
### Copy files or folders from a container
`POST /containers/`(*id*)`/copy`
: Copy files or folders of container `id`
`POST /containers/(id)/copy`
Copy files or folders of container `id`
**Example request**:
@@ -619,12 +631,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
### 2.2 Images
## 2.2 Images
#### List Images
### List Images
`GET /images/json`
: **Example request**:
`GET /images/json`
**Example request**:
GET /images/json?all=0 HTTP/1.1
@@ -658,11 +671,11 @@ page_keywords: API, Docker, rcli, REST, documentation
}
]
#### Create an image
### Create an image
`POST /images/create`
: Create an image, either by pull it from the registry or by importing
it
`POST /images/create`
Create an image, either by pull it from the registry or by importing it
**Example request**:
@@ -703,11 +716,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Insert a file in an image
### Insert a file in an image
`POST /images/`(*name*)`/insert`
: Insert a file from `url` in the image
`name` at `path`
`POST /images/(name)/insert`
Insert a file from `url` in the image `name` at `path`
**Example request**:
@@ -728,10 +741,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Inspect an image
### Inspect an image
`GET /images/`(*name*)`/json`
: Return low-level information on the image `name`
`GET /images/(name)/json`
Return low-level information on the image `name`
**Example request**:
@@ -777,10 +791,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### Get the history of an image
### Get the history of an image
`GET /images/`(*name*)`/history`
: Return the history of the image `name`
`GET /images/(name)/history`
Return the history of the image `name`
**Example request**:
@@ -810,10 +825,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### Push an image on the registry
### Push an image on the registry
`POST /images/`(*name*)`/push`
: Push the image `name` on the registry
`POST /images/(name)/push`
Push the image `name` on the registry
**Example request**:
@@ -848,10 +864,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### Tag an image into a repository
### Tag an image into a repository
`POST /images/`(*name*)`/tag`
: Tag the image `name` into a repository
`POST /images/(name)/tag`
Tag the image `name` into a repository
**Example request**:
@@ -876,10 +893,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### Remove an image
### Remove an image
`DELETE /images/`(*name*)
: Remove the image `name` from the filesystem
`DELETE /images/(name)`
Remove the image `name` from the filesystem
**Example request**:
@@ -910,14 +928,15 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### Search images
### Search images
`GET /images/search`
: Search for an image in the docker index.
`GET /images/search`
Search for an image in the docker index.
> **Note**:
> The response keys have changed from API v1.6 to reflect the JSON
> sent by the registry server to the docker daemon’s request.
> sent by the registry server to the docker daemon's request.
**Example request**:
@@ -964,12 +983,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
### 2.3 Misc
## 2.3 Misc
#### Build an image from Dockerfile via stdin
### Build an image from Dockerfile via stdin
`POST /build`
: Build an image from Dockerfile via stdin
`POST /build`
Build an image from Dockerfile via stdin
**Example request**:
@@ -990,7 +1010,7 @@ page_keywords: API, Docker, rcli, REST, documentation
following algorithms: identity (no compression), gzip, bzip2, xz.
The archive must include a file called `Dockerfile`
at its root. It may include any number of other files,
at its root. It may include any number of other files,
which will be accessible in the build context (See the [*ADD build
command*](../../builder/#dockerbuilder)).
@@ -1016,10 +1036,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Check auth configuration
### Check auth configuration
`POST /auth`
: Get the default username and email
`POST /auth`
Get the default username and email
**Example request**:
@@ -1043,10 +1064,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **204** – no error
- **500** – server error
#### Display system-wide information
### Display system-wide information
`GET /info`
: Display system-wide information
`GET /info`
Display system-wide information
**Example request**:
@@ -1073,10 +1095,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Show the docker version information
### Show the docker version information
`GET /version`
: Show the docker version information
`GET /version`
Show the docker version information
**Example request**:
@@ -1098,10 +1121,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Create a new image from a container’s changes
### Create a new image from a container's changes
`POST /commit`
: Create a new image from a container’s changes
`POST /commit`
Create a new image from a container's changes
**Example request**:
@@ -1123,7 +1147,7 @@ page_keywords: API, Docker, rcli, REST, documentation
- **tag** – tag
- **m** – commit message
- **author** – author (eg. "John Hannibal Smith
\<[hannibal@a-team.com](mailto:hannibal%40a-team.com)\>")
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
- **run** – config automatically applied when the image is run.
(ex: {"Cmd": ["cat", "/world"], "PortSpecs":["22"]})
@@ -1133,11 +1157,12 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Monitor Docker’s events
### Monitor Docker's events
`GET /events`
: Get events from docker, either in real time via streaming, or via
polling (using since)
`GET /events`
Get events from docker, either in real time via streaming, or
via polling (using since)
**Example request**:
@@ -1165,11 +1190,12 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Get a tarball containing all images and tags in a repository
### Get a tarball containing all images and tags in a repository
`GET /images/`(*name*)`/get`
: Get a tarball containing all images and metadata for the repository
specified by `name`.
`GET /images/(name)/get`
Get a tarball containing all images and metadata for the repository
specified by `name`.
**Example request**
@@ -1187,10 +1213,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Load a tarball with a set of images and tags into docker
### Load a tarball with a set of images and tags into docker
`POST /images/load`
: Load a set of images and tags into the docker repository.
`POST /images/load`
Load a set of images and tags into the docker repository.
**Example request**
@@ -1207,33 +1234,33 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
## 3. Going further
# 3. Going further
### 3.1 Inside ‘docker run’
## 3.1 Inside `docker run`
Here are the steps of ‘docker run’ :
Here are the steps of `docker run`:
- Create the container
- Create the container
- If the status code is 404, it means the image doesn’t exists:
: - Try to pull it
- Then retry to create the container
- If the status code is 404, it means the image doesn't exists:
- Try to pull it
- Then retry to create the container
- Start the container
- Start the container
- If you are not in detached mode:
: - Attach to the container, using logs=1 (to have stdout and
stderr from the container’s start) and stream=1
- If you are not in detached mode:
- Attach to the container, using logs=1 (to have stdout and
stderr from the container's start) and stream=1
- If in detached mode or only stdin is attached:
: - Display the container’s id
- If in detached mode or only stdin is attached:
- Display the container's id
### 3.2 Hijacking
## 3.2 Hijacking
In this version of the API, /attach, uses hijacking to transport stdin,
stdout and stderr on the same socket. This might change in the future.
### 3.3 CORS Requests
## 3.3 CORS Requests
To enable cross origin requests to the remote api add the flag
"–api-enable-cors" when running docker in daemon mode.
docs/sources/reference/api/docker_remote_api_v1.9.md
+157 -131
View File
@@ -4,25 +4,25 @@ page_keywords: API, Docker, rcli, REST, documentation
# Docker Remote API v1.9
## 1. Brief introduction
# 1. Brief introduction
- The Remote API has replaced rcli
- The daemon listens on `unix:///var/run/docker.sock`
, but you can [*Bind Docker to another host/port or a Unix
socket*](../../../use/basics/#bind-docker).
- The API tends to be REST, but for some complex commands, like
`attach` or `pull`, the HTTP
connection is hijacked to transport `stdout, stdin`
and `stderr`
- The Remote API has replaced rcli
- The daemon listens on `unix:///var/run/docker.sock` but you can
[*Bind Docker to another host/port or a Unix socket*](
../../../use/basics/#bind-docker).
- The API tends to be REST, but for some complex commands, like `attach`
or `pull`, the HTTP connection is hijacked to transport `stdout, stdin`
and `stderr`
## 2. Endpoints
# 2. Endpoints
### 2.1 Containers
## 2.1 Containers
#### List containers
### List containers
`GET /containers/json`
: List containers
`GET /containers/json`
List containers.
**Example request**:
@@ -97,10 +97,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **400** – bad parameter
- **500** – server error
#### Create a container
### Create a container
`POST /containers/create`
: Create a container
`POST /containers/create`
Create a container
**Example request**:
@@ -179,11 +180,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **406** – impossible to attach (container not running)
- **500** – server error
#### Inspect a container
### Inspect a container
`GET /containers/`(*id*)`/json`
: Return low-level information on the container `id`
`GET /containers/(id)/json`
Return low-level information on the container `id`
**Example request**:
@@ -264,10 +265,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### List processes running inside a container
### List processes running inside a container
`GET /containers/`(*id*)`/top`
: List processes running inside the container `id`
`GET /containers/(id)/top`
List processes running inside the container `id`
**Example request**:
@@ -302,7 +304,7 @@ page_keywords: API, Docker, rcli, REST, documentation
 
- **ps\_args** – ps arguments to use (eg. aux)
- **ps_args** – ps arguments to use (eg. aux)
Status Codes:
@@ -310,10 +312,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Inspect changes on a container’s filesystem
### Inspect changes on a container's filesystem
`GET /containers/`(*id*)`/changes`
: Inspect changes on container `id` ‘s filesystem
`GET /containers/(id)/changes`
Inspect changes on container `id`'s filesystem
**Example request**:
@@ -345,10 +348,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Export a container
### Export a container
`GET /containers/`(*id*)`/export`
: Export the contents of container `id`
`GET /containers/(id)/export`
Export the contents of container `id`
**Example request**:
@@ -367,10 +371,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Start a container
### Start a container
`POST /containers/`(*id*)`/start`
: Start the container `id`
`POST /containers/(id)/start`
Start the container `id`
**Example request**:
@@ -411,10 +416,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Stop a container
### Stop a container
`POST /containers/`(*id*)`/stop`
: Stop the container `id`
`POST /containers/(id)/stop`
Stop the container `id`
**Example request**:
@@ -436,10 +442,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Restart a container
### Restart a container
`POST /containers/`(*id*)`/restart`
: Restart the container `id`
`POST /containers/(id)/restart`
Restart the container `id`
**Example request**:
@@ -461,10 +468,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Kill a container
### Kill a container
`POST /containers/`(*id*)`/kill`
: Kill the container `id`
`POST /containers/(id)/kill`
Kill the container `id`
**Example request**:
@@ -480,10 +488,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Attach to a container
### Attach to a container
`POST /containers/`(*id*)`/attach`
: Attach to the container `id`
`POST /containers/(id)/attach`
Attach to the container `id`
**Example request**:
@@ -521,9 +530,8 @@ page_keywords: API, Docker, rcli, REST, documentation
**Stream details**:
When using the TTY setting is enabled in
[`POST /containers/create`
](#post--containers-create "POST /containers/create"), the
stream is the raw data from the process PTY and client’s stdin. When
[`POST /containers/create`](#post--containers-create), the
stream is the raw data from the process PTY and client's stdin. When
the TTY is disabled, then the stream is multiplexed to separate
stdout and stderr.
@@ -562,11 +570,11 @@ page_keywords: API, Docker, rcli, REST, documentation
4. Read the extracted size and output it on the correct output
5. Goto 1)
#### Wait a container
### Wait a container
`POST /containers/`(*id*)`/wait`
: Block until container `id` stops, then returns
the exit code
`POST /containers/(id)/wait`
Block until container `id` stops, then returns the exit code
**Example request**:
@@ -585,10 +593,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Remove a container
### Remove a container
`DELETE /containers/`(*id*)
: Remove the container `id` from the filesystem
`DELETE /containers/(id)`
Remove the container `id` from the filesystem
**Example request**:
@@ -612,10 +621,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Copy files or folders from a container
### Copy files or folders from a container
`POST /containers/`(*id*)`/copy`
: Copy files or folders of container `id`
`POST /containers/(id)/copy`
Copy files or folders of container `id`
**Example request**:
@@ -639,12 +649,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
### 2.2 Images
## 2.2 Images
#### List Images
### List Images
`GET /images/json`
: **Example request**:
`GET /images/json`
**Example request**:
GET /images/json?all=0 HTTP/1.1
@@ -678,11 +689,11 @@ page_keywords: API, Docker, rcli, REST, documentation
}
]
#### Create an image
### Create an image
`POST /images/create`
: Create an image, either by pull it from the registry or by importing
it
`POST /images/create`
Create an image, either by pull it from the registry or by importing it
**Example request**:
@@ -723,11 +734,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Insert a file in an image
### Insert a file in an image
`POST /images/`(*name*)`/insert`
: Insert a file from `url` in the image
`name` at `path`
`POST /images/(name)/insert`
Insert a file from `url` in the image `name` at `path`
**Example request**:
@@ -748,10 +759,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Inspect an image
### Inspect an image
`GET /images/`(*name*)`/json`
: Return low-level information on the image `name`
`GET /images/(name)/json`
Return low-level information on the image `name`
**Example request**:
@@ -797,10 +809,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### Get the history of an image
### Get the history of an image
`GET /images/`(*name*)`/history`
: Return the history of the image `name`
`GET /images/(name)/history`
Return the history of the image `name`
**Example request**:
@@ -830,10 +843,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### Push an image on the registry
### Push an image on the registry
`POST /images/`(*name*)`/push`
: Push the image `name` on the registry
`POST /images/(name)/push`
Push the image `name` on the registry
**Example request**:
@@ -868,10 +882,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such image
- **500** – server error
#### Tag an image into a repository
### Tag an image into a repository
`POST /images/`(*name*)`/tag`
: Tag the image `name` into a repository
`POST /images/(name)/tag`
Tag the image `name` into a repository
**Example request**:
@@ -896,9 +911,9 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### Remove an image
### Remove an image
`DELETE /images/`(*name*)
`DELETE /images/(name*)
: Remove the image `name` from the filesystem
**Example request**:
@@ -923,14 +938,15 @@ page_keywords: API, Docker, rcli, REST, documentation
- **409** – conflict
- **500** – server error
#### Search images
### Search images
`GET /images/search`
: Search for an image in the docker index.
`GET /images/search`
Search for an image in the docker index.
> **Note**:
> The response keys have changed from API v1.6 to reflect the JSON
> sent by the registry server to the docker daemon’s request.
> sent by the registry server to the docker daemon's request.
**Example request**:
@@ -977,12 +993,13 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
### 2.3 Misc
## 2.3 Misc
#### Build an image from Dockerfile
### Build an image from Dockerfile
`POST /build`
: Build an image from Dockerfile using a POST body.
`POST /build`
Build an image from Dockerfile using a POST body.
**Example request**:
@@ -1030,10 +1047,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Check auth configuration
### Check auth configuration
`POST /auth`
: Get the default username and email
`POST /auth`
Get the default username and email
**Example request**:
@@ -1057,10 +1075,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **204** – no error
- **500** – server error
#### Display system-wide information
### Display system-wide information
`GET /info`
: Display system-wide information
`GET /info`
Display system-wide information
**Example request**:
@@ -1087,10 +1106,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Show the docker version information
### Show the docker version information
`GET /version`
: Show the docker version information
`GET /version`
Show the docker version information
**Example request**:
@@ -1112,10 +1132,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Create a new image from a container’s changes
### Create a new image from a container's changes
`POST /commit`
: Create a new image from a container’s changes
`POST /commit`
Create a new image from a container's changes
**Example request**:
@@ -1137,7 +1158,7 @@ page_keywords: API, Docker, rcli, REST, documentation
- **tag** – tag
- **m** – commit message
- **author** – author (eg. "John Hannibal Smith
\<[hannibal@a-team.com](mailto:hannibal%40a-team.com)\>")
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
- **run** – config automatically applied when the image is run.
(ex: {"Cmd": ["cat", "/world"], "PortSpecs":["22"]})
@@ -1147,11 +1168,12 @@ page_keywords: API, Docker, rcli, REST, documentation
- **404** – no such container
- **500** – server error
#### Monitor Docker’s events
### Monitor Docker's events
`GET /events`
: Get events from docker, either in real time via streaming, or via
polling (using since)
`GET /events`
Get events from docker, either in real time via streaming, or via
polling (using since)
**Example request**:
@@ -1178,11 +1200,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Get a tarball containing all images and tags in a repository
### Get a tarball containing all images and tags in a repository
`GET /images/`(*name*)`/get`
: Get a tarball containing all images and metadata for the repository
specified by `name`.
`GET /images/(name)/get`
Get a tarball containing all images and metadata for the repository specified by `name`.
**Example request**
@@ -1200,10 +1222,11 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
#### Load a tarball with a set of images and tags into docker
### Load a tarball with a set of images and tags into docker
`POST /images/load`
: Load a set of images and tags into the docker repository.
`POST /images/load`
Load a set of images and tags into the docker repository.
**Example request**
@@ -1220,33 +1243,36 @@ page_keywords: API, Docker, rcli, REST, documentation
- **200** – no error
- **500** – server error
## 3. Going further
# 3. Going further
### 3.1 Inside ‘docker run’
## 3.1 Inside `docker run`
Here are the steps of ‘docker run’ :
Here are the steps of `docker run` :
- Create the container
- Create the container
- If the status code is 404, it means the image doesn’t exists:
: - Try to pull it
- Then retry to create the container
- If the status code is 404, it means the image doesn't exists:
- Start the container
- Try to pull it
- Then retry to create the container
- If you are not in detached mode:
: - Attach to the container, using logs=1 (to have stdout and
stderr from the container’s start) and stream=1
- Start the container
- If in detached mode or only stdin is attached:
: - Display the container’s id
- If you are not in detached mode:
### 3.2 Hijacking
- Attach to the container, using logs=1 (to have stdout and
- stderr from the container's start) and stream=1
- If in detached mode or only stdin is attached:
- Display the container's id
## 3.2 Hijacking
In this version of the API, /attach, uses hijacking to transport stdin,
stdout and stderr on the same socket. This might change in the future.
### 3.3 CORS Requests
## 3.3 CORS Requests
To enable cross origin requests to the remote api add the flag
"–api-enable-cors" when running docker in daemon mode.
docs/sources/reference/api/index_api.md
+66 -56
View File
@@ -14,11 +14,11 @@ page_keywords: API, Docker, index, REST, documentation
### Repositories
### User Repo
#### User Repo
`PUT /v1/repositories/`(*namespace*)`/`(*repo\_name*)`/`
: Create a user repository with the given `namespace`
and `repo_name`.
`PUT /v1/repositories/(namespace)/(repo_name)/`
Create a user repository with the given `namespace` and `repo_name`.
**Example Request**:
@@ -34,7 +34,7 @@ page_keywords: API, Docker, index, REST, documentation
Parameters:
- **namespace** – the namespace for the repo
- **repo\_name** – the name for the repo
- **repo_name** – the name for the repo
**Example Response**:
@@ -54,9 +54,9 @@ page_keywords: API, Docker, index, REST, documentation
- **401** – Unauthorized
- **403** – Account is not Active
`DELETE /v1/repositories/`(*namespace*)`/`(*repo\_name*)`/`
: Delete a user repository with the given `namespace`
and `repo_name`.
`DELETE /v1/repositories/(namespace)/(repo_name)/`
Delete a user repository with the given `namespace` and `repo_name`.
**Example Request**:
@@ -72,7 +72,7 @@ page_keywords: API, Docker, index, REST, documentation
Parameters:
- **namespace** – the namespace for the repo
- **repo\_name** – the name for the repo
- **repo_name** – the name for the repo
**Example Response**:
@@ -93,12 +93,12 @@ page_keywords: API, Docker, index, REST, documentation
- **401** – Unauthorized
- **403** – Account is not Active
### Library Repo
#### Library Repo
`PUT /v1/repositories/`(*repo\_name*)`/`
: Create a library repository with the given `repo_name`
. This is a restricted feature only available to docker
admins.
`PUT /v1/repositories/(repo_name)/`
Create a library repository with the given `repo_name`.
This is a restricted feature only available to docker admins.
When namespace is missing, it is assumed to be `library`
@@ -116,7 +116,7 @@ page_keywords: API, Docker, index, REST, documentation
Parameters:
- **repo\_name** – the library name for the repo
- **repo_name** – the library name for the repo
**Example Response**:
@@ -136,10 +136,10 @@ page_keywords: API, Docker, index, REST, documentation
- **401** – Unauthorized
- **403** – Account is not Active
`DELETE /v1/repositories/`(*repo\_name*)`/`
: Delete a library repository with the given `repo_name`
. This is a restricted feature only available to docker
admins.
`DELETE /v1/repositories/(repo_name)/`
Delete a library repository with the given `repo_name`.
This is a restricted feature only available to docker admins.
When namespace is missing, it is assumed to be `library`
@@ -157,7 +157,7 @@ page_keywords: API, Docker, index, REST, documentation
Parameters:
- **repo\_name** – the library name for the repo
- **repo_name** – the library name for the repo
**Example Response**:
@@ -180,10 +180,11 @@ page_keywords: API, Docker, index, REST, documentation
### Repository Images
### User Repo Images
#### User Repo Images
`PUT /v1/repositories/`(*namespace*)`/`(*repo\_name*)`/images`
: Update the images for a user repo.
`PUT /v1/repositories/(namespace)/(repo_name)/images`
Update the images for a user repo.
**Example Request**:
@@ -199,7 +200,7 @@ page_keywords: API, Docker, index, REST, documentation
Parameters:
- **namespace** – the namespace for the repo
- **repo\_name** – the name for the repo
- **repo_name** – the name for the repo
**Example Response**:
@@ -216,8 +217,9 @@ page_keywords: API, Docker, index, REST, documentation
- **401** – Unauthorized
- **403** – Account is not Active or permission denied
`GET /v1/repositories/`(*namespace*)`/`(*repo\_name*)`/images`
: get the images for a user repo.
`GET /v1/repositories/(namespace)/(repo_name)/images`
Get the images for a user repo.
**Example Request**:
@@ -228,7 +230,7 @@ page_keywords: API, Docker, index, REST, documentation
Parameters:
- **namespace** – the namespace for the repo
- **repo\_name** – the name for the repo
- **repo_name** – the name for the repo
**Example Response**:
@@ -246,10 +248,11 @@ page_keywords: API, Docker, index, REST, documentation
- **200** – OK
- **404** – Not found
### Library Repo Images
#### Library Repo Images
`PUT /v1/repositories/`(*repo\_name*)`/images`
: Update the images for a library repo.
`PUT /v1/repositories/(repo_name)/images`
Update the images for a library repo.
**Example Request**:
@@ -264,7 +267,7 @@ page_keywords: API, Docker, index, REST, documentation
Parameters:
- **repo\_name** – the library name for the repo
- **repo_name** – the library name for the repo
**Example Response**:
@@ -281,8 +284,9 @@ page_keywords: API, Docker, index, REST, documentation
- **401** – Unauthorized
- **403** – Account is not Active or permission denied
`GET /v1/repositories/`(*repo\_name*)`/images`
: get the images for a library repo.
`GET /v1/repositories/(repo_name)/images`
Get the images for a library repo.
**Example Request**:
@@ -292,7 +296,7 @@ page_keywords: API, Docker, index, REST, documentation
Parameters:
- **repo\_name** – the library name for the repo
- **repo_name** – the library name for the repo
**Example Response**:
@@ -312,10 +316,11 @@ page_keywords: API, Docker, index, REST, documentation
### Repository Authorization
### Library Repo
#### Library Repo
`PUT /v1/repositories/`(*repo\_name*)`/auth`
: authorize a token for a library repo
`PUT /v1/repositories/(repo_name)/auth`
Authorize a token for a library repo
**Example Request**:
@@ -326,7 +331,7 @@ page_keywords: API, Docker, index, REST, documentation
Parameters:
- **repo\_name** – the library name for the repo
- **repo_name** – the library name for the repo
**Example Response**:
@@ -342,10 +347,11 @@ page_keywords: API, Docker, index, REST, documentation
- **403** – Permission denied
- **404** – Not found
### User Repo
#### User Repo
`PUT /v1/repositories/`(*namespace*)`/`(*repo\_name*)`/auth`
: authorize a token for a user repo
`PUT /v1/repositories/(namespace)/(repo_name)/auth`
Authorize a token for a user repo
**Example Request**:
@@ -357,7 +363,7 @@ page_keywords: API, Docker, index, REST, documentation
Parameters:
- **namespace** – the namespace for the repo
- **repo\_name** – the name for the repo
- **repo_name** – the name for the repo
**Example Response**:
@@ -375,10 +381,11 @@ page_keywords: API, Docker, index, REST, documentation
### Users
### User Login
#### User Login
`GET /v1/users`
: If you want to check your login, you can try this endpoint
`GET /v1/users`
If you want to check your login, you can try this endpoint
**Example Request**:
@@ -401,10 +408,11 @@ page_keywords: API, Docker, index, REST, documentation
- **401** – Unauthorized
- **403** – Account is not Active
### User Register
#### User Register
`POST /v1/users`
: Registering a new account.
`POST /v1/users`
Registering a new account.
**Example request**:
@@ -423,7 +431,7 @@ page_keywords: API, Docker, index, REST, documentation
- **email** – valid email address, that needs to be confirmed
- **username** – min 4 character, max 30 characters, must match
the regular expression [a-z0-9\_].
the regular expression [a-z0-9_].
- **password** – min 5 characters
**Example Response**:
@@ -439,10 +447,12 @@ page_keywords: API, Docker, index, REST, documentation
- **201** – User Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
### Update User
#### Update User
`PUT /v1/users/(username)/`
Change a password or email address for given user. If you pass in an
`PUT /v1/users/`(*username*)`/`
: Change a password or email address for given user. If you pass in an
email, it will add it to your account, it will not remove the old
one. Passwords will be updated.
@@ -487,8 +497,10 @@ If you need to search the index, this is the endpoint you would use.
### Search
`GET /v1/search`
: Search the Index given a search term. It accepts
`GET /v1/search`
Search the Index given a search term. It accepts
[GET](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.3)
only.
@@ -521,5 +533,3 @@ If you need to search the index, this is the endpoint you would use.
- **200** – no error
- **500** – server error
docs/sources/reference/api/registry_api.md
+87 -77
View File
@@ -6,51 +6,51 @@ page_keywords: API, Docker, index, registry, REST, documentation
## Introduction
- This is the REST API for the Docker Registry
- It stores the images and the graph for a set of repositories
- It does not have user accounts data
- It has no notion of user accounts or authorization
- It delegates authentication and authorization to the Index Auth
service using tokens
- It supports different storage backends (S3, cloud files, local FS)
- It doesn’t have a local database
- It will be open-sourced at some point
- This is the REST API for the Docker Registry
- It stores the images and the graph for a set of repositories
- It does not have user accounts data
- It has no notion of user accounts or authorization
- It delegates authentication and authorization to the Index Auth
service using tokens
- It supports different storage backends (S3, cloud files, local FS)
- It doesn't have a local database
- It will be open-sourced at some point
We expect that there will be multiple registries out there. To help to
grasp the context, here are some examples of registries:
- **sponsor registry**: such a registry is provided by a third-party
hosting infrastructure as a convenience for their customers and the
docker community as a whole. Its costs are supported by the third
party, but the management and operation of the registry are
supported by dotCloud. It features read/write access, and delegates
authentication and authorization to the Index.
- **mirror registry**: such a registry is provided by a third-party
hosting infrastructure but is targeted at their customers only. Some
mechanism (unspecified to date) ensures that public images are
pulled from a sponsor registry to the mirror registry, to make sure
that the customers of the third-party provider can “docker pull”
those images locally.
- **vendor registry**: such a registry is provided by a software
vendor, who wants to distribute docker images. It would be operated
and managed by the vendor. Only users authorized by the vendor would
be able to get write access. Some images would be public (accessible
for anyone), others private (accessible only for authorized users).
Authentication and authorization would be delegated to the Index.
The goal of vendor registries is to let someone do “docker pull
basho/riak1.3” and automatically push from the vendor registry
(instead of a sponsor registry); i.e. get all the convenience of a
sponsor registry, while retaining control on the asset distribution.
- **private registry**: such a registry is located behind a firewall,
or protected by an additional security layer (HTTP authorization,
SSL client-side certificates, IP address authorization...). The
registry is operated by a private entity, outside of dotCloud’s
control. It can optionally delegate additional authorization to the
Index, but it is not mandatory.
- **sponsor registry**: such a registry is provided by a third-party
hosting infrastructure as a convenience for their customers and the
docker community as a whole. Its costs are supported by the third
party, but the management and operation of the registry are
supported by dotCloud. It features read/write access, and delegates
authentication and authorization to the Index.
- **mirror registry**: such a registry is provided by a third-party
hosting infrastructure but is targeted at their customers only. Some
mechanism (unspecified to date) ensures that public images are
pulled from a sponsor registry to the mirror registry, to make sure
that the customers of the third-party provider can “docker pull”
those images locally.
- **vendor registry**: such a registry is provided by a software
vendor, who wants to distribute docker images. It would be operated
and managed by the vendor. Only users authorized by the vendor would
be able to get write access. Some images would be public (accessible
for anyone), others private (accessible only for authorized users).
Authentication and authorization would be delegated to the Index.
The goal of vendor registries is to let someone do “docker pull
basho/riak1.3” and automatically push from the vendor registry
(instead of a sponsor registry); i.e. get all the convenience of a
sponsor registry, while retaining control on the asset distribution.
- **private registry**: such a registry is located behind a firewall,
or protected by an additional security layer (HTTP authorization,
SSL client-side certificates, IP address authorization...). The
registry is operated by a private entity, outside of dotCloud's
control. It can optionally delegate additional authorization to the
Index, but it is not mandatory.
> **Note**:
> Mirror registries and private registries which do not use the Index
> don’t even need to run the registry code. They can be implemented by any
> don't even need to run the registry code. They can be implemented by any
> kind of transport implementing HTTP GET and PUT. Read-only registries
> can be powered by a simple static HTTP server.
@@ -63,19 +63,19 @@ grasp the context, here are some examples of registries:
> - remote docker addressed through SSH.
The latter would only require two new commands in docker, e.g.
`registryget` and `registryput`,
wrapping access to the local filesystem (and optionally doing
consistency checks). Authentication and authorization are then delegated
to SSH (e.g. with public keys).
`registryget` and `registryput`, wrapping access to the local filesystem
(and optionally doing consistency checks). Authentication and authorization
are then delegated to SSH (e.g. with public keys).
## Endpoints
# Endpoints
### Images
## Images
### Layer
`GET /v1/images/`(*image\_id*)`/layer`
: get image layer for a given `image_id`
`GET /v1/images/(image_id)/layer`
Get image layer for a given `image_id`
**Example Request**:
@@ -87,7 +87,7 @@ to SSH (e.g. with public keys).
Parameters:
- **image\_id** – the id for the layer you want to get
- **image_id** – the id for the layer you want to get
**Example Response**:
@@ -104,8 +104,9 @@ to SSH (e.g. with public keys).
- **401** – Requires authorization
- **404** – Image not found
`PUT /v1/images/`(*image\_id*)`/layer`
: put image layer for a given `image_id`
`PUT /v1/images/(image_id)/layer`
Put image layer for a given `image_id`
**Example Request**:
@@ -118,7 +119,7 @@ to SSH (e.g. with public keys).
Parameters:
- **image\_id** – the id for the layer you want to get
- **image_id** – the id for the layer you want to get
**Example Response**:
@@ -135,10 +136,11 @@ to SSH (e.g. with public keys).
- **401** – Requires authorization
- **404** – Image not found
### Image
## Image
`PUT /v1/images/`(*image\_id*)`/json`
: put image for a given `image_id`
`PUT /v1/images/(image_id)/json`
Put image for a given `image_id`
**Example Request**:
@@ -181,7 +183,7 @@ to SSH (e.g. with public keys).
Parameters:
- **image\_id** – the id for the layer you want to get
- **image_id** – the id for the layer you want to get
**Example Response**:
@@ -197,8 +199,9 @@ to SSH (e.g. with public keys).
- **200** – OK
- **401** – Requires authorization
`GET /v1/images/`(*image\_id*)`/json`
: get image for a given `image_id`
`GET /v1/images/(image_id)/json`
Get image for a given `image_id`
**Example Request**:
@@ -210,7 +213,7 @@ to SSH (e.g. with public keys).
Parameters:
- **image\_id** – the id for the layer you want to get
- **image_id** – the id for the layer you want to get
**Example Response**:
@@ -258,10 +261,11 @@ to SSH (e.g. with public keys).
- **401** – Requires authorization
- **404** – Image not found
### Ancestry
## Ancestry
`GET /v1/images/`(*image\_id*)`/ancestry`
: get ancestry for an image given an `image_id`
`GET /v1/images/(image_id)/ancestry`
Get ancestry for an image given an `image_id`
**Example Request**:
@@ -273,7 +277,7 @@ to SSH (e.g. with public keys).
Parameters:
- **image\_id** – the id for the layer you want to get
- **image_id** – the id for the layer you want to get
**Example Response**:
@@ -293,10 +297,11 @@ to SSH (e.g. with public keys).
- **401** – Requires authorization
- **404** – Image not found
### Tags
## Tags
`GET /v1/repositories/`(*namespace*)`/`(*repository*)`/tags`
: get all of the tags for the given repo.
`GET /v1/repositories/(namespace)/(repository)/tags`
Get all of the tags for the given repo.
**Example Request**:
@@ -330,8 +335,9 @@ to SSH (e.g. with public keys).
- **401** – Requires authorization
- **404** – Repository not found
`GET /v1/repositories/`(*namespace*)`/`(*repository*)`/tags/`(*tag*)
: get a tag for the given repo.
`GET /v1/repositories/(namespace)/(repository)/tags/(tag*):
Get a tag for the given repo.
**Example Request**:
@@ -363,8 +369,9 @@ to SSH (e.g. with public keys).
- **401** – Requires authorization
- **404** – Tag not found
`DELETE /v1/repositories/`(*namespace*)`/`(*repository*)`/tags/`(*tag*)
: delete the tag for the repo
`DELETE /v1/repositories/(namespace)/(repository)/tags/(tag*):
Delete the tag for the repo
**Example Request**:
@@ -395,8 +402,9 @@ to SSH (e.g. with public keys).
- **401** – Requires authorization
- **404** – Tag not found
`PUT /v1/repositories/`(*namespace*)`/`(*repository*)`/tags/`(*tag*)
: put a tag for the given repo.
`PUT /v1/repositories/(namespace)/(repository)/tags/(tag*):
Put a tag for the given repo.
**Example Request**:
@@ -430,10 +438,11 @@ to SSH (e.g. with public keys).
- **401** – Requires authorization
- **404** – Image not found
### Repositories
## Repositories
`DELETE /v1/repositories/`(*namespace*)`/`(*repository*)`/`
: delete a repository
`DELETE /v1/repositories/(namespace)/(repository)/`
Delete a repository
**Example Request**:
@@ -465,11 +474,12 @@ to SSH (e.g. with public keys).
- **401** – Requires authorization
- **404** – Repository not found
### Status
## Status
`GET /v1/_ping`
: Check status of the registry. This endpoint is also used to
determine if the registry supports SSL.
`GET /v1/_ping`
Check status of the registry. This endpoint is also used to
determine if the registry supports SSL.
**Example Request**:
docs/sources/reference/api/registry_index_spec.md
+310 -303
View File
@@ -10,16 +10,16 @@ page_keywords: docker, registry, api, index
The Index is responsible for centralizing information about:
- User accounts
- Checksums of the images
- Public namespaces
- User accounts
- Checksums of the images
- Public namespaces
The Index has different components:
- Web UI
- Meta-data store (comments, stars, list public repositories)
- Authentication service
- Tokenization
- Web UI
- Meta-data store (comments, stars, list public repositories)
- Authentication service
- Tokenization
The index is authoritative for those information.
@@ -28,46 +28,46 @@ managed by Docker Inc.
### Registry
- It stores the images and the graph for a set of repositories
- It does not have user accounts data
- It has no notion of user accounts or authorization
- It delegates authentication and authorization to the Index Auth
service using tokens
- It supports different storage backends (S3, cloud files, local FS)
- It doesn’t have a local database
- [Source Code](https://github.com/dotcloud/docker-registry)
- It stores the images and the graph for a set of repositories
- It does not have user accounts data
- It has no notion of user accounts or authorization
- It delegates authentication and authorization to the Index Auth
service using tokens
- It supports different storage backends (S3, cloud files, local FS)
- It doesn't have a local database
- [Source Code](https://github.com/dotcloud/docker-registry)
We expect that there will be multiple registries out there. To help to
grasp the context, here are some examples of registries:
- **sponsor registry**: such a registry is provided by a third-party
hosting infrastructure as a convenience for their customers and the
docker community as a whole. Its costs are supported by the third
party, but the management and operation of the registry are
supported by dotCloud. It features read/write access, and delegates
authentication and authorization to the Index.
- **mirror registry**: such a registry is provided by a third-party
hosting infrastructure but is targeted at their customers only. Some
mechanism (unspecified to date) ensures that public images are
pulled from a sponsor registry to the mirror registry, to make sure
that the customers of the third-party provider can “docker pull”
those images locally.
- **vendor registry**: such a registry is provided by a software
vendor, who wants to distribute docker images. It would be operated
and managed by the vendor. Only users authorized by the vendor would
be able to get write access. Some images would be public (accessible
for anyone), others private (accessible only for authorized users).
Authentication and authorization would be delegated to the Index.
The goal of vendor registries is to let someone do “docker pull
basho/riak1.3” and automatically push from the vendor registry
(instead of a sponsor registry); i.e. get all the convenience of a
sponsor registry, while retaining control on the asset distribution.
- **private registry**: such a registry is located behind a firewall,
or protected by an additional security layer (HTTP authorization,
SSL client-side certificates, IP address authorization...). The
registry is operated by a private entity, outside of dotCloud’s
control. It can optionally delegate additional authorization to the
Index, but it is not mandatory.
- **sponsor registry**: such a registry is provided by a third-party
hosting infrastructure as a convenience for their customers and the
docker community as a whole. Its costs are supported by the third
party, but the management and operation of the registry are
supported by dotCloud. It features read/write access, and delegates
authentication and authorization to the Index.
- **mirror registry**: such a registry is provided by a third-party
hosting infrastructure but is targeted at their customers only. Some
mechanism (unspecified to date) ensures that public images are
pulled from a sponsor registry to the mirror registry, to make sure
that the customers of the third-party provider can “docker pull”
those images locally.
- **vendor registry**: such a registry is provided by a software
vendor, who wants to distribute docker images. It would be operated
and managed by the vendor. Only users authorized by the vendor would
be able to get write access. Some images would be public (accessible
for anyone), others private (accessible only for authorized users).
Authentication and authorization would be delegated to the Index.
The goal of vendor registries is to let someone do “docker pull
basho/riak1.3” and automatically push from the vendor registry
(instead of a sponsor registry); i.e. get all the convenience of a
sponsor registry, while retaining control on the asset distribution.
- **private registry**: such a registry is located behind a firewall,
or protected by an additional security layer (HTTP authorization,
SSL client-side certificates, IP address authorization...). The
registry is operated by a private entity, outside of dotCloud's
control. It can optionally delegate additional authorization to the
Index, but it is not mandatory.
> **Note:** The latter implies that while HTTP is the protocol
> of choice for a registry, multiple schemes are possible (and
@@ -88,36 +88,33 @@ to SSH (e.g. with public keys).
On top of being a runtime for LXC, Docker is the Registry client. It
supports:
- Push / Pull on the registry
- Client authentication on the Index
- Push / Pull on the registry
- Client authentication on the Index
## Workflow
### Pull
![](../../../_images/docker_pull_chart.png)
![](../../../static_files/docker_pull_chart.png)
1. Contact the Index to know where I should download “samalba/busybox”
2. Index replies: a. `samalba/busybox` is on
Registry A b. here are the checksums for `samalba/busybox`
(for all layers) c. token
3. Contact Registry A to receive the layers for
`samalba/busybox` (all of them to the base
image). Registry A is authoritative for “samalba/busybox” but keeps
a copy of all inherited layers and serve them all from the same
2. Index replies: a. `samalba/busybox` is on Registry A b. here are the
checksums for `samalba/busybox` (for all layers) c. token
3. Contact Registry A to receive the layers for `samalba/busybox` (all of
them to the base image). Registry A is authoritative for “samalba/busybox”
but keeps a copy of all inherited layers and serve them all from the same
location.
4. registry contacts index to verify if token/user is allowed to
download images
5. Index returns true/false lettings registry know if it should proceed
or error out
4. registry contacts index to verify if token/user is allowed to download images
5. Index returns true/false lettings registry know if it should proceed or error
out
6. Get the payload for all layers
It’s possible to run:
It's possible to run:
docker pull https://<registry>/repositories/samalba/busybox
In this case, Docker bypasses the Index. However the security is not
guaranteed (in case Registry A is corrupted) because there won’t be any
guaranteed (in case Registry A is corrupted) because there won't be any
checksum checks.
Currently registry redirects to s3 urls for downloads, going forward all
@@ -128,60 +125,61 @@ sub-classes for S3 and local storage.
Token is only returned when the `X-Docker-Token`
header is sent with request.
Basic Auth is required to pull private repos. Basic auth isn’t required
Basic Auth is required to pull private repos. Basic auth isn't required
for pulling public repos, but if one is provided, it needs to be valid
and for an active account.
#### API (pulling repository foo/bar):
**API (pulling repository foo/bar):**
1. (Docker -\> Index) GET /v1/repositories/foo/bar/images
: **Headers**:
: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
X-Docker-Token: true
1. (Docker -> Index) GET /v1/repositories/foo/bar/images:
**Headers**:
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
X-Docker-Token: true
**Action**:
(looking up the foo/bar in db and gets images and checksums
for that repo (all if no tag is specified, if tag, only
checksums for those tags) see part 4.4.1)
2. (Index -> Docker) HTTP 200 OK
**Headers**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=write
X-Docker-Endpoints: registry.docker.io [,registry2.docker.io]
**Body**:
Jsonified checksums (see part 4.4.1)
3. (Docker -> Registry) GET /v1/repositories/foo/bar/tags/latest
**Headers**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=write
4. (Registry -> Index) GET /v1/repositories/foo/bar/images
**Headers**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=read
**Body**:
<ids and checksums in payload>
**Action**:
(Lookup token see if they have access to pull.)
If good:
HTTP 200 OK Index will invalidate the token
If bad:
HTTP 401 Unauthorized
5. (Docker -> Registry) GET /v1/images/928374982374/ancestry
**Action**:
: (looking up the foo/bar in db and gets images and checksums
for that repo (all if no tag is specified, if tag, only
checksums for those tags) see part 4.4.1)
2. (Index -\> Docker) HTTP 200 OK
> **Headers**:
> : - Authorization: Token
> signature=123abc,repository=”foo/bar”,access=write
> - X-Docker-Endpoints: registry.docker.io [,
> registry2.docker.io]
>
> **Body**:
> : Jsonified checksums (see part 4.4.1)
>
3. (Docker -\> Registry) GET /v1/repositories/foo/bar/tags/latest
: **Headers**:
: Authorization: Token
signature=123abc,repository=”foo/bar”,access=write
4. (Registry -\> Index) GET /v1/repositories/foo/bar/images
> **Headers**:
> : Authorization: Token
> signature=123abc,repository=”foo/bar”,access=read
>
> **Body**:
> : \<ids and checksums in payload\>
>
> **Action**:
> : ( Lookup token see if they have access to pull.)
>
> If good:
> : HTTP 200 OK Index will invalidate the token
>
> If bad:
> : HTTP 401 Unauthorized
>
5. (Docker -\> Registry) GET /v1/images/928374982374/ancestry
: **Action**:
: (for each image id returned in the registry, fetch /json +
/layer)
(for each image id returned in the registry, fetch /json + /layer)
> **Note**:
> If someone makes a second request, then we will always give a new token,
@@ -189,7 +187,7 @@ and for an active account.
### Push
![](../../../_images/docker_push_chart.png)
![](../../../static_files/docker_push_chart.png)
1. Contact the index to allocate the repository name “samalba/busybox”
(authentication required with user credentials)
@@ -204,7 +202,7 @@ and for an active account.
6. docker contacts the index to give checksums for upload images
> **Note:**
> **It’s possible not to use the Index at all!** In this case, a deployed
> **It's possible not to use the Index at all!** In this case, a deployed
> version of the Registry is deployed to store and serve images. Those
> images are not authenticated and the security is not guaranteed.
@@ -218,89 +216,96 @@ the push. When a repository name does not have checksums on the Index,
it means that the push is in progress (since checksums are submitted at
the end).
#### API (pushing repos foo/bar):
**API (pushing repos foo/bar):**
1. (Docker -\> Index) PUT /v1/repositories/foo/bar/
: **Headers**:
: Authorization: Basic sdkjfskdjfhsdkjfh== X-Docker-Token:
true
1. (Docker -> Index) PUT /v1/repositories/foo/bar/
**Action**::
: - in index, we allocated a new repository, and set to
initialized
**Headers**:
Authorization: Basic sdkjfskdjfhsdkjfh== X-Docker-Token:
true
**Body**::
: (The body contains the list of images that are going to be
pushed, with empty checksums. The checksums will be set at
the end of the push):
[{“id”: “9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f”}]
2. (Index -\> Docker) 200 Created
: **Headers**:
: - WWW-Authenticate: Token
signature=123abc,repository=”foo/bar”,access=write
- X-Docker-Endpoints: registry.docker.io [,
registry2.docker.io]
3. (Docker -\> Registry) PUT /v1/images/98765432\_parent/json
: **Headers**:
: Authorization: Token
signature=123abc,repository=”foo/bar”,access=write
4. (Registry-\>Index) GET /v1/repositories/foo/bar/images
: **Headers**:
: Authorization: Token
signature=123abc,repository=”foo/bar”,access=write
**Action**::
: - Index:
: will invalidate the token.
- Registry:
: grants a session (if token is approved) and fetches
the images id
5. (Docker -\> Registry) PUT /v1/images/98765432\_parent/json
: **Headers**::
: - Authorization: Token
signature=123abc,repository=”foo/bar”,access=write
- Cookie: (Cookie provided by the Registry)
6. (Docker -\> Registry) PUT /v1/images/98765432/json
: **Headers**:
: Cookie: (Cookie provided by the Registry)
7. (Docker -\> Registry) PUT /v1/images/98765432\_parent/layer
: **Headers**:
: Cookie: (Cookie provided by the Registry)
8. (Docker -\> Registry) PUT /v1/images/98765432/layer
: **Headers**:
: X-Docker-Checksum: sha256:436745873465fdjkhdfjkgh
9. (Docker -\> Registry) PUT /v1/repositories/foo/bar/tags/latest
: **Headers**:
: Cookie: (Cookie provided by the Registry)
**Action**:
- in index, we allocated a new repository, and set to
initialized
**Body**:
: “98765432”
(The body contains the list of images that are going to be
pushed, with empty checksums. The checksums will be set at
the end of the push):
10. (Docker -\> Index) PUT /v1/repositories/foo/bar/images
[{“id”: “9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f”}]
**Headers**:
: Authorization: Basic 123oislifjsldfj== X-Docker-Endpoints:
2. (Index -> Docker) 200 Created
**Headers**:
- WWW-Authenticate: Token
signature=123abc,repository=”foo/bar”,access=write
- X-Docker-Endpoints: registry.docker.io [,
registry2.docker.io]
3. (Docker -> Registry) PUT /v1/images/98765432_parent/json
**Headers**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=write
4. (Registry->Index) GET /v1/repositories/foo/bar/images
**Headers**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=write
**Action**:
- Index:
will invalidate the token.
- Registry:
grants a session (if token is approved) and fetches
the images id
5. (Docker -> Registry) PUT /v1/images/98765432_parent/json
**Headers**::
- Authorization: Token
signature=123abc,repository=”foo/bar”,access=write
- Cookie: (Cookie provided by the Registry)
6. (Docker -> Registry) PUT /v1/images/98765432/json
**Headers**:
- Cookie: (Cookie provided by the Registry)
7. (Docker -> Registry) PUT /v1/images/98765432_parent/layer
**Headers**:
- Cookie: (Cookie provided by the Registry)
8. (Docker -> Registry) PUT /v1/images/98765432/layer
**Headers**:
X-Docker-Checksum: sha256:436745873465fdjkhdfjkgh
9. (Docker -> Registry) PUT /v1/repositories/foo/bar/tags/latest
**Headers**:
- Cookie: (Cookie provided by the Registry)
**Body**:
“98765432”
10. (Docker -> Index) PUT /v1/repositories/foo/bar/images
**Headers**:
Authorization: Basic 123oislifjsldfj== X-Docker-Endpoints:
registry1.docker.io (no validation on this right now)
**Body**:
: (The image, id’s, tags and checksums)
**Body**:
(The image, id`s, tags and checksums)
[{“id”:
“9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f”,
“checksum”:
“b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087”}]
**Return** HTTP 204
**Return**: HTTP 204
> **Note:** If push fails and they need to start again, what happens in the index,
> there will already be a record for the namespace/name, but it will be
@@ -308,8 +313,8 @@ the end).
> case could be if someone pushes the same thing at the same time with two
> different shells.
If it’s a retry on the Registry, Docker has a cookie (provided by the
registry after token validation). So the Index won’t have to provide a
If it's a retry on the Registry, Docker has a cookie (provided by the
registry after token validation). So the Index won't have to provide a
new token.
### Delete
@@ -318,11 +323,9 @@ If you need to delete something from the index or registry, we need a
nice clean way to do that. Here is the workflow.
1. Docker contacts the index to request a delete of a repository
`samalba/busybox` (authentication required with
user credentials)
2. If authentication works and repository is valid,
`samalba/busybox` is marked as deleted and a
temporary token is returned
`samalba/busybox` (authentication required with user credentials)
2. If authentication works and repository is valid, `samalba/busybox`
is marked as deleted and a temporary token is returned
3. Send a delete request to the registry for the repository (along with
the token)
4. Registry A contacts the Index to verify the token (token must
@@ -334,74 +337,79 @@ nice clean way to do that. Here is the workflow.
> **Note**:
> The Docker client should present an "Are you sure?" prompt to confirm
> the deletion before starting the process. Once it starts it can’t be
> the deletion before starting the process. Once it starts it can't be
> undone.
#### API (deleting repository foo/bar):
**API (deleting repository foo/bar):**
1. (Docker -\> Index) DELETE /v1/repositories/foo/bar/
: **Headers**:
: Authorization: Basic sdkjfskdjfhsdkjfh== X-Docker-Token:
true
1. (Docker -> Index) DELETE /v1/repositories/foo/bar/
**Action**::
: - in index, we make sure it is a valid repository, and set
to deleted (logically)
**Headers**:
Authorization: Basic sdkjfskdjfhsdkjfh== X-Docker-Token:
true
**Body**::
: Empty
**Action**:
- in index, we make sure it is a valid repository, and set
to deleted (logically)
2. (Index -\> Docker) 202 Accepted
: **Headers**:
: - WWW-Authenticate: Token
signature=123abc,repository=”foo/bar”,access=delete
- X-Docker-Endpoints: registry.docker.io [,
registry2.docker.io] \# list of endpoints where this
repo lives.
**Body**:
Empty
3. (Docker -\> Registry) DELETE /v1/repositories/foo/bar/
: **Headers**:
: Authorization: Token
signature=123abc,repository=”foo/bar”,access=delete
2. (Index -> Docker) 202 Accepted
4. (Registry-\>Index) PUT /v1/repositories/foo/bar/auth
: **Headers**:
: Authorization: Token
signature=123abc,repository=”foo/bar”,access=delete
**Headers**:
- WWW-Authenticate: Token
signature=123abc,repository=”foo/bar”,access=delete
- X-Docker-Endpoints: registry.docker.io [,
registry2.docker.io]
# list of endpoints where this repo lives.
**Action**::
: - Index:
: will invalidate the token.
3. (Docker -> Registry) DELETE /v1/repositories/foo/bar/
- Registry:
: deletes the repository (if token is approved)
**Headers**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=delete
5. (Registry -\> Docker) 200 OK
: 200 If success 403 if forbidden 400 if bad request 404 if
repository isn’t found
4. (Registry->Index) PUT /v1/repositories/foo/bar/auth
6. (Docker -\> Index) DELETE /v1/repositories/foo/bar/
**Headers**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=delete
> **Headers**:
> : Authorization: Basic 123oislifjsldfj== X-Docker-Endpoints:
> registry-1.docker.io (no validation on this right now)
>
> **Body**:
> : Empty
>
> **Return** HTTP 200
**Action**:
- Index:
will invalidate the token.
- Registry:
deletes the repository (if token is approved)
5. (Registry -> Docker) 200 OK
200 If success 403 if forbidden 400 if bad request 404
if repository isn't found
6. (Docker -> Index) DELETE /v1/repositories/foo/bar/
**Headers**:
Authorization: Basic 123oislifjsldfj== X-Docker-Endpoints:
registry-1.docker.io (no validation on this right now)
**Body**:
Empty
**Return**: HTTP 200
## How to use the Registry in standalone mode
The Index has two main purposes (along with its fancy social features):
- Resolve short names (to avoid passing absolute URLs all the time)
: - username/projectname -\>
https://registry.docker.io/users/\<username\>/repositories/\<projectname\>/
- team/projectname -\>
https://registry.docker.io/team/\<team\>/repositories/\<projectname\>/
- Resolve short names (to avoid passing absolute URLs all the time):
- Authenticate a user as a repos owner (for a central referenced
username/projectname ->
https://registry.docker.io/users/<username>/repositories/<projectname>/
team/projectname ->
https://registry.docker.io/team/<team>/repositories/<projectname>/
- Authenticate a user as a repos owner (for a central referenced
repository)
### Without an Index
@@ -429,17 +437,17 @@ no write access is necessary).
The Index data needed by the Registry are simple:
- Serve the checksums
- Provide and authorize a Token
- Serve the checksums
- Provide and authorize a Token
In the scenario of a Registry running on a private network with the need
of centralizing and authorizing, it’s easy to use a custom Index.
of centralizing and authorizing, it's easy to use a custom Index.
The only challenge will be to tell Docker to contact (and trust) this
custom Index. Docker will be configurable at some point to use a
specific Index, it’ll be the private entity responsibility (basically
specific Index, it'll be the private entity responsibility (basically
the organization who uses Docker in a private environment) to maintain
the Index and the Docker’s configuration among its consumers.
the Index and the Docker's configuration among its consumers.
## The API
@@ -453,7 +461,7 @@ JSON), basically because Registry stores exactly the same kind of
information as Docker uses to manage them.
The format of ancestry is a line-separated list of image ids, in age
order, i.e. the image’s parent is on the last line, the parent of the
order, i.e. the image's parent is on the last line, the parent of the
parent on the next-to-last line, etc.; if the image has no parent, the
file is empty.
@@ -468,17 +476,18 @@ file is empty.
### Create a user (Index)
POST /v1/users
POST /v1/users:
**Body**:
: {"email": "[sam@dotcloud.com](mailto:sam%40dotcloud.com)",
"password": "toto42", "username": "foobar"’}
**Validation**:
: - **username**: min 4 character, max 30 characters, must match the
regular expression [a-z0-9\_].
**Body**:
{"email": "[sam@dotcloud.com](mailto:sam%40dotcloud.com)",
"password": "toto42", "username": "foobar"`}
**Validation**:
- **username**: min 4 character, max 30 characters, must match the
regular expression [a-z0-9_].
- **password**: min 5 characters
**Valid**: return HTTP 200
**Valid**: return HTTP 200
Errors: HTTP 400 (we should create error codes for possible errors) -
invalid json - missing field - wrong format (username, password, email,
@@ -490,10 +499,10 @@ etc) - forbidden name - name already exists
### Update a user (Index)
PUT /v1/users/\<username\>
PUT /v1/users/<username>
**Body**:
: {"password": "toto"}
**Body**:
{"password": "toto"}
> **Note**:
> We can also update email address, if they do, they will need to reverify
@@ -506,44 +515,44 @@ validate credentials. HTTP Basic Auth for now, maybe change in future.
GET /v1/users
**Return**:
: - Valid: HTTP 200
- Invalid login: HTTP 401
- Account inactive: HTTP 403 Account is not Active
**Return**:
- Valid: HTTP 200
- Invalid login: HTTP 401
- Account inactive: HTTP 403 Account is not Active
### Tags (Registry)
The Registry does not know anything about users. Even though
repositories are under usernames, it’s just a namespace for the
repositories are under usernames, it's just a namespace for the
registry. Allowing us to implement organizations or different namespaces
per user later, without modifying the Registry’s API.
per user later, without modifying the Registry'sAPI.
The following naming restrictions apply:
- Namespaces must match the same regular expression as usernames (See
- Namespaces must match the same regular expression as usernames (See
4.2.1.)
- Repository names must match the regular expression [a-zA-Z0-9-\_.]
- Repository names must match the regular expression [a-zA-Z0-9-_.]
### Get all tags:
GET /v1/repositories/\<namespace\>/\<repository\_name\>/tags
GET /v1/repositories/<namespace>/<repository_name>/tags
**Return**: HTTP 200
: { "latest":
**Return**: HTTP 200
{ "latest":
"9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
“0.1.1”:
“b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087” }
#### 4.3.2 Read the content of a tag (resolve the image id)
**4.3.2 Read the content of a tag (resolve the image id):**
GET /v1/repositories/\<namespace\>/\<repo\_name\>/tags/\<tag\>
GET /v1/repositories/<namespace>/<repo_name>/tags/<tag>
**Return**:
: "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"
**Return**:
"9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"
#### 4.3.3 Delete a tag (registry)
**4.3.3 Delete a tag (registry):**
DELETE /v1/repositories/\<namespace\>/\<repo\_name\>/tags/\<tag\>
DELETE /v1/repositories/<namespace>/<repo_name>/tags/<tag>
### 4.4 Images (Index)
@@ -552,12 +561,12 @@ it uses the X-Docker-Endpoints header. In other terms, this requests
always add a `X-Docker-Endpoints` to indicate the
location of the registry which hosts this repository.
#### 4.4.1 Get the images
**4.4.1 Get the images:**
GET /v1/repositories/\<namespace\>/\<repo\_name\>/images
GET /v1/repositories/<namespace>/<repo_name>/images
**Return**: HTTP 200
: [{“id”:
**Return**: HTTP 200
[{“id”:
“9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f”,
“checksum”:
“[md5:b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087](md5:b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087)”}]
@@ -566,22 +575,22 @@ GET /v1/repositories/\<namespace\>/\<repo\_name\>/images
You always add images, you never remove them.
PUT /v1/repositories/\<namespace\>/\<repo\_name\>/images
PUT /v1/repositories/<namespace>/<repo_name>/images
**Body**:
: [ {“id”:
**Body**:
[ {“id”:
“9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f”,
“checksum”:
“sha256:b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087”}
]
**Return** 204
**Return**: 204
### Repositories
### Remove a Repository (Registry)
DELETE /v1/repositories/\<namespace\>/\<repo\_name\>
DELETE /v1/repositories/<namespace>/<repo_name>
Return 200 OK
@@ -589,16 +598,16 @@ Return 200 OK
This starts the delete process. see 2.3 for more details.
DELETE /v1/repositories/\<namespace\>/\<repo\_name\>
DELETE /v1/repositories/<namespace>/<repo_name>
Return 202 OK
## Chaining Registries
It’s possible to chain Registries server for several reasons:
It's possible to chain Registries server for several reasons:
- Load balancing
- Delegate the next request to another server
- Load balancing
- Delegate the next request to another server
When a Registry is a reference for a repository, it should host the
entire images chain in order to avoid breaking the chain during the
@@ -631,32 +640,30 @@ You have 3 options:
1. Provide user credentials and ask for a token
> **Header**:
> : - Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
> - X-Docker-Token: true
>
> In this case, along with the 200 response, you’ll get a new token
> (if user auth is ok): If authorization isn’t correct you get a 401
> response. If account isn’t active you will get a 403 response.
>
> **Response**:
> : - 200 OK
> - X-Docker-Token: Token
> signature=123abc,repository=”foo/bar”,access=read
>
**Header**:
- Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
- X-Docker-Token: true
In this case, along with the 200 response, you'll get a new token
(if user auth is ok): If authorization isn't correct you get a 401
response. If account isn't active you will get a 403 response.
**Response**:
- 200 OK
- X-Docker-Token: Token
signature=123abc,repository=”foo/bar”,access=read
2. Provide user credentials only
> **Header**:
> : Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
>
**Header**:
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
3. Provide Token
> **Header**:
> : Authorization: Token
> signature=123abc,repository=”foo/bar”,access=read
>
**Header**:
Authorization: Token
signature=123abc,repository=”foo/bar”,access=read
### 6.2 On the Registry
@@ -684,7 +691,7 @@ Next request:
## Document Version
- 1.0 : May 6th 2013 : initial release
- 1.1 : June 1st 2013 : Added Delete Repository and way to handle new
- 1.0 : May 6th 2013 : initial release
- 1.1 : June 1st 2013 : Added Delete Repository and way to handle new
source namespace.
docs/sources/reference/api/remote_api_client_libraries.md
+121 -78
View File
@@ -9,81 +9,124 @@ compatibility. Please file issues with the library owners. If you find
more library implementations, please list them in Docker doc bugs and we
will add the libraries here.
-------------------------------------------------------------------------
Language/Framewor Name Repository Status
k
----------------- ------------ ---------------------------------- -------
Python docker-py [https://github.com/dotcloud/docke Active
r-py](https://github.com/dotcloud/
docker-py)
Ruby docker-clien [https://github.com/geku/docker-cl Outdate
t ient](https://github.com/geku/dock d
er-client)
Ruby docker-api [https://github.com/swipely/docker Active
-api](https://github.com/swipely/d
ocker-api)
JavaScript dockerode [https://github.com/apocas/dockero Active
(NodeJS) de](https://github.com/apocas/dock
erode)
Install via NPM: npm install
dockerode
JavaScript docker.io [https://github.com/appersonlabs/d Active
(NodeJS) ocker.io](https://github.com/apper
sonlabs/docker.io)
Install via NPM: npm install
docker.io
JavaScript docker-js [https://github.com/dgoujard/docke Outdate
r-js](https://github.com/dgoujard/ d
docker-js)
JavaScript docker-cp [https://github.com/13W/docker-cp] Active
(Angular) (https://github.com/13W/docker-cp)
**WebUI**
JavaScript dockerui [https://github.com/crosbymichael/ Active
(Angular) dockerui](https://github.com/crosb
**WebUI** ymichael/dockerui)
Java docker-java [https://github.com/kpelykh/docker Active
-java](https://github.com/kpelykh/
docker-java)
Erlang erldocker [https://github.com/proger/erldock Active
er](https://github.com/proger/erld
ocker)
Go go-dockercli [https://github.com/fsouza/go-dock Active
ent erclient](https://github.com/fsouz
a/go-dockerclient)
Go dockerclient [https://github.com/samalba/docker Active
client](https://github.com/samalba
/dockerclient)
PHP Alvine [http://pear.alvine.io/](http://pe Active
ar.alvine.io/)
(alpha)
PHP Docker-PHP [http://stage1.github.io/docker-ph Active
p/](http://stage1.github.io/docker
-php/)
Perl Net::Docker [https://metacpan.org/pod/Net::Doc Active
ker](https://metacpan.org/pod/Net:
:Docker)
Perl Eixo::Docker [https://github.com/alambike/eixo- Active
docker](https://github.com/alambik
e/eixo-docker)
Scala reactive-doc [https://github.com/almoehi/reacti Active
ker ve-docker](https://github.com/almo
ehi/reactive-docker)
-------------------------------------------------------------------------
<table border="1" class="docutils">
<colgroup>
<col width="24%">
<col width="17%">
<col width="48%">
<col width="11%">
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Language/Framework</th>
<th class="head">Name</th>
<th class="head">Repository</th>
<th class="head">Status</th>
</tr>
</thead>
<tbody valign = "top">
<tr class="row-even">
<td>Python</td>
<td>docker-py</td>
<td><a class="reference external" href="https://github.com/dotcloud/docker-py">https://github.com/dotcloud/docker-py</a></td>
<td>Active</td>
</tr>
<tr class="row-odd">
<td>Ruby</td>
<td>docker-client</td>
<td><a class="reference external" href="https://github.com/geku/docker-client">https://github.com/geku/docker-client</a></td>
<td>Outdated</td>
</tr>
<tr class="row-even">
<td>Ruby</td>
<td>docker-api</td>
<td><a class="reference external" href="https://github.com/swipely/docker-api">https://github.com/swipely/docker-api</a></td>
<td>Active</td>
</tr>
<tr class="row-odd">
<td>JavaScript (NodeJS)</td>
<td>dockerode</td>
<td><a class="reference external" href="https://github.com/apocas/dockerode">https://github.com/apocas/dockerode</a>
Install via NPM: <cite>npm install dockerode</cite></td>
<td>Active</td>
</tr>
<tr class="row-even">
<td>JavaScript (NodeJS)</td>
<td>docker.io</td>
<td><a class="reference external" href="https://github.com/appersonlabs/docker.io">https://github.com/appersonlabs/docker.io</a>
Install via NPM: <cite>npm install docker.io</cite></td>
<td>Active</td>
</tr>
<tr class="row-odd">
<td>JavaScript</td>
<td>docker-js</td>
<td><a class="reference external" href="https://github.com/dgoujard/docker-js">https://github.com/dgoujard/docker-js</a></td>
<td>Outdated</td>
</tr>
<tr class="row-even">
<td>JavaScript (Angular) <strong>WebUI</strong></td>
<td>docker-cp</td>
<td><a class="reference external" href="https://github.com/13W/docker-cp">https://github.com/13W/docker-cp</a></td>
<td>Active</td>
</tr>
<tr class="row-odd">
<td>JavaScript (Angular) <strong>WebUI</strong></td>
<td>dockerui</td>
<td><a class="reference external" href="https://github.com/crosbymichael/dockerui">https://github.com/crosbymichael/dockerui</a></td>
<td>Active</td>
</tr>
<tr class="row-even">
<td>Java</td>
<td>docker-java</td>
<td><a class="reference external" href="https://github.com/kpelykh/docker-java">https://github.com/kpelykh/docker-java</a></td>
<td>Active</td>
</tr>
<tr class="row-odd">
<td>Erlang</td>
<td>erldocker</td>
<td><a class="reference external" href="https://github.com/proger/erldocker">https://github.com/proger/erldocker</a></td>
<td>Active</td>
</tr>
<tr class="row-even">
<td>Go</td>
<td>go-dockerclient</td>
<td><a class="reference external" href="https://github.com/fsouza/go-dockerclient">https://github.com/fsouza/go-dockerclient</a></td>
<td>Active</td>
</tr>
<tr class="row-odd">
<td>Go</td>
<td>dockerclient</td>
<td><a class="reference external" href="https://github.com/samalba/dockerclient">https://github.com/samalba/dockerclient</a></td>
<td>Active</td>
</tr>
<tr class="row-even">
<td>PHP</td>
<td>Alvine</td>
<td><a class="reference external" href="http://pear.alvine.io/">http://pear.alvine.io/</a> (alpha)</td>
<td>Active</td>
</tr>
<tr class="row-odd">
<td>PHP</td>
<td>Docker-PHP</td>
<td><a class="reference external" href="http://stage1.github.io/docker-php/">http://stage1.github.io/docker-php/</a></td>
<td>Active</td>
</tr>
<tr class="row-even">
<td>Perl</td>
<td>Net::Docker</td>
<td><a class="reference external" href="https://metacpan.org/pod/Net::Docker">https://metacpan.org/pod/Net::Docker</a></td>
<td>Active</td>
</tr>
<tr class="row-odd">
<td>Perl</td>
<td>Eixo::Docker</td>
<td><a class="reference external" href="https://github.com/alambike/eixo-docker">https://github.com/alambike/eixo-docker</a></td>
<td>Active</td>
</tr>
<tr class="row-odd">
<td>Scala</td>
<td>reactive-docker</td>
<td><a class="reference external" href="https://github.com/almoehi/reactive-docker">https://github.com/almoehi/reactive-docker</a></td>
<td>Active</td>
</tr>
</tbody>
</table>