clearlinux/docker
2
0
Fork 0
mirror of https://github.com/clearlinux/docker.git synced 2026-10-03 15:28:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

now, with shiney markdown

Browse Source 
Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@fosiki.com> (github: SvenDowideit)
This commit is contained in:
Sven Dowideit
2014-04-16 11:04:14 +10:00
parent a777ebcee6
commit ac999a9cb2
76 changed files with 14766 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/reference/api/docker_io_accounts_api.md
+355
View File
@@ -0,0 +1,355 @@
page_title: docker.io Accounts API
page_description: API Documentation for docker.io accounts.
page_keywords: API, Docker, accounts, REST, documentation
# docker.io Accounts API
## 1. Endpoints
### 1.1 Get a single user
`GET /api/v1.1/users/:username/`
: Get profile info for the specified user.
Parameters:
- **username** – username of the user whose profile info is being
requested.
Request Headers:
 
- **Authorization** – required authentication credentials of
either type HTTP Basic or OAuth Bearer Token.
Status Codes:
- **200** – success, user data returned.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
whose data is being requested, OAuth access tokens must have
`profile_read` scope.
- **404** – the specified username does not exist.
**Example request**:
GET /api/v1.1/users/janedoe/ HTTP/1.1
Host: www.docker.io
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 2,
"username": "janedoe",
"url": "https://www.docker.io/api/v1.1/users/janedoe/",
"date_joined": "2014-02-12T17:58:01.431312Z",
"type": "User",
"full_name": "Jane Doe",
"location": "San Francisco, CA",
"company": "Success, Inc.",
"profile_url": "https://docker.io/",
"gravatar_url": "https://secure.gravatar.com/avatar/0212b397124be4acd4e7dea9aa357.jpg?s=80&r=g&d=mm"
"email": "jane.doe@example.com",
"is_active": true
}
### 1.2 Update a single user
`PATCH /api/v1.1/users/:username/`
: Update profile info for the specified user.
Parameters:
- **username** – username of the user whose profile info is being
updated.
Json Parameters:
 
- **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
email address.
Request Headers:
 
- **Authorization** – required authentication credentials of
either type HTTP Basic or OAuth Bearer Token.
- **Content-Type** – MIME Type of post data. JSON, url-encoded
form data, etc.
Status Codes:
- **200** – success, user data updated.
- **400** – post data validation error.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
whose data is being updated, OAuth access tokens must have
`profile_write` scope.
- **404** – the specified username does not exist.
**Example request**:
PATCH /api/v1.1/users/janedoe/ HTTP/1.1
Host: www.docker.io
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
{
"location": "Private Island",
"profile_url": "http://janedoe.com/",
"company": "Retired",
}
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 2,
"username": "janedoe",
"url": "https://www.docker.io/api/v1.1/users/janedoe/",
"date_joined": "2014-02-12T17:58:01.431312Z",
"type": "User",
"full_name": "Jane Doe",
"location": "Private Island",
"company": "Retired",
"profile_url": "http://janedoe.com/",
"gravatar_url": "https://secure.gravatar.com/avatar/0212b397124be4acd4e7dea9aa357.jpg?s=80&r=g&d=mm"
"email": "jane.doe@example.com",
"is_active": true
}
### 1.3 List email addresses for a user
`GET /api/v1.1/users/:username/emails/`
: List email info for the specified user.
Parameters:
- **username** – username of the user whose profile info is being
updated.
Request Headers:
 
- **Authorization** – required authentication credentials of
either type HTTP Basic or OAuth Bearer Token
Status Codes:
- **200** – success, user data updated.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
whose data is being requested, OAuth access tokens must have
`email_read` scope.
- **404** – the specified username does not exist.
**Example request**:
GET /api/v1.1/users/janedoe/emails/ HTTP/1.1
Host: www.docker.io
Accept: application/json
Authorization: Bearer zAy0BxC1wDv2EuF3tGs4HrI6qJp6KoL7nM
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"email": "jane.doe@example.com",
"verified": true,
"primary": true
}
]
### 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.
Json Parameters:
 
- **email** (*string*) – email address to be added.
Request Headers:
 
- **Authorization** – required authentication credentials of
either type HTTP Basic or OAuth Bearer Token.
- **Content-Type** – MIME Type of post data. JSON, url-encoded
form data, etc.
Status Codes:
- **201** – success, new email added.
- **400** – data validation error.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
whose data is being requested, OAuth access tokens must have
`email_write` scope.
- **404** – the specified username does not exist.
**Example request**:
POST /api/v1.1/users/janedoe/emails/ HTTP/1.1
Host: www.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Bearer zAy0BxC1wDv2EuF3tGs4HrI6qJp6KoL7nM
{
"email": "jane.doe+other@example.com"
}
**Example response**:
HTTP/1.1 201 Created
Content-Type: application/json
{
"email": "jane.doe+other@example.com",
"verified": false,
"primary": false
}
### 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.
Parameters:
- **username** – username of the user whose email info is being
updated.
Json Parameters:
 
- **email** (*string*) – the email address to be updated.
- **verified** (*boolean*) – (optional) whether the email address
is verified, must be `true` or absent.
- **primary** (*boolean*) – (optional) whether to set the email
address as the primary email, must be `true`
or absent.
Request Headers:
 
- **Authorization** – required authentication credentials of
either type HTTP Basic or OAuth Bearer Token.
- **Content-Type** – MIME Type of post data. JSON, url-encoded
form data, etc.
Status Codes:
- **200** – success, user’s email updated.
- **400** – data validation error.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
whose data is being updated, OAuth access tokens must have
`email_write` scope.
- **404** – the specified username or email address does not
exist.
**Example request**:
Once you have independently verified an email address.
PATCH /api/v1.1/users/janedoe/emails/ HTTP/1.1
Host: www.docker.io
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
{
"email": "jane.doe+other@example.com",
"verified": true,
}
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{
"email": "jane.doe+other@example.com",
"verified": true,
"primary": false
}
### 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.
Json Parameters:
 
- **email** (*string*) – email address to be deleted.
Request Headers:
 
- **Authorization** – required authentication credentials of
either type HTTP Basic or OAuth Bearer Token.
- **Content-Type** – MIME Type of post data. JSON, url-encoded
form data, etc.
Status Codes:
- **204** – success, email address removed.
- **400** – validation error.
- **401** – authentication error.
- **403** – permission error, authenticated user must be the user
whose data is being requested, OAuth access tokens must have
`email_write` scope.
- **404** – the specified username or email address does not
exist.
**Example request**:
DELETE /api/v1.1/users/janedoe/emails/ HTTP/1.1
Host: www.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Bearer zAy0BxC1wDv2EuF3tGs4HrI6qJp6KoL7nM
{
"email": "jane.doe+other@example.com"
}
**Example response**:
HTTP/1.1 204 NO CONTENT
Content-Length: 0
docs/sources/reference/api/docker_io_oauth_api.md
+256
View File
@@ -0,0 +1,256 @@
page_title: docker.io OAuth API
page_description: API Documentation for docker.io's OAuth flow.
page_keywords: API, Docker, oauth, REST, documentation
# docker.io OAuth API
## 1. Brief introduction
Some docker.io API requests will require an access token to
authenticate. To get an access token for a user, that user must first
grant your application access to their docker.io account. In order for
them to grant your application access you must first register your
application.
Before continuing, we encourage you to familiarize yourself with [The
OAuth 2.0 Authorization Framework](http://tools.ietf.org/html/rfc6749).
*Also note that all OAuth interactions must take place over https
connections*
## 2. Register Your Application
You will need to register your application with docker.io before users
will be able to grant your application access to their account
information. We are currently only allowing applications selectively. To
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.
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.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.
Query Parameters:
 
- **client\_id** – The `client_id` given to
your application at registration.
- **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
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
registering your application.
- **scope** – The extent of access permissions you are requesting.
Currently, the scope options are `profile_read`
.literal}, `profile_write`,
`email_read`, and `email_write`
.literal}. Scopes must be separated by a space. If omitted, the
default scopes `profile_read email_read` are
used.
- **state** – (Recommended) Used by your application to maintain
state between the authorization request and callback to protect
against CSRF attacks.
**Example Request**
Asking the user for authorization.
GET /api/v1.1/o/authorize/?client_id=TestClientID&response_type=code&redirect_uri=https%3A//my.app/auth_complete/&scope=profile_read%20email_read&state=abc123 HTTP/1.1
Host: www.docker.io
**Authorization Page**
When the user follows a link, making the above GET request, they
will be asked to login to their docker.io account if they are not
already and then be presented with the following authorization
prompt which asks the user to authorize your application with a
description of the requested scopes.
![](../../../_images/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
request will be the following query parameters:
`code`
: The Authorization code generated by the docker.io authorization
server. Present it again to request an Access Token. This code
expires in 60 seconds.
`state`
: If the `state` parameter was present in the
authorization request this will be the exact value received from
that request.
`error`
: 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
Once the user has authorized your application, a request will be made to
your application’s specified `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.
Request Headers:
 
- **Authorization** – HTTP basic authentication using your
application’s `client_id` and
`client_secret`
Form Parameters:
 
- **grant\_type** – MUST be set to `authorization_code`
.literal}
- **code** – The authorization code received from the user’s
redirect request.
- **redirect\_uri** – The same `redirect_uri`
used in the authentication request.
**Example Request**
Using an authorization code to get an access token.
POST /api/v1.1/o/token/ HTTP/1.1
Host: www.docker.io
Authorization: Basic VGVzdENsaWVudElEOlRlc3RDbGllbnRTZWNyZXQ=
Accept: application/json
Content-Type: application/json
{
"grant_type": "code",
"code": "YXV0aG9yaXphdGlvbl9jb2Rl",
"redirect_uri": "https://my.app/auth_complete/"
}
**Example Response**
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"username": "janedoe",
"user_id": 42,
"access_token": "t6k2BqgRw59hphQBsbBoPPWLqu6FmS",
"expires_in": 15552000,
"token_type": "Bearer",
"scope": "profile_read email_read",
"refresh_token": "hJDhLH3cfsUrQlT4MxA6s8xAFEqdgc"
}
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
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.
Request Headers:
 
- **Authorization** – HTTP basic authentication using your
application’s `client_id` and
`client_secret`
Form Parameters:
 
- **grant\_type** – MUST be set to `refresh_token`
.literal}
- **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
the user and if omitted is treated as equal to the scope
originally granted.
**Example Request**
Refreshing an access token.
POST /api/v1.1/o/token/ HTTP/1.1
Host: www.docker.io
Authorization: Basic VGVzdENsaWVudElEOlRlc3RDbGllbnRTZWNyZXQ=
Accept: application/json
Content-Type: application/json
{
"grant_type": "refresh_token",
"refresh_token": "hJDhLH3cfsUrQlT4MxA6s8xAFEqdgc",
}
**Example Response**
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"username": "janedoe",
"user_id": 42,
"access_token": "t6k2BqgRw59hphQBsbBoPPWLqu6FmS",
"expires_in": 15552000,
"token_type": "Bearer",
"scope": "profile_read email_read",
"refresh_token": "hJDhLH3cfsUrQlT4MxA6s8xAFEqdgc"
}
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
Many of the docker.io API requests will require a Authorization request
header field. Simply ensure you add this header with "Bearer
\<`access_token`\>":
GET /api/v1.1/resource HTTP/1.1
Host: docker.io
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
docs/sources/reference/api/docker_remote_api.md
+348
View File
@@ -0,0 +1,348 @@
page_title: Remote API
page_description: API Documentation for Docker
page_keywords: API, Docker, rcli, REST, documentation
# Docker Remote API
## 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}`
## 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
You can still call an old version of the api using
/v1.11/images/\<name\>/insert
### v1.11
#### Full Documentation
[*Docker Remote API v1.11*](../docker_remote_api_v1.11/)
#### What’s new
`GET /events`
: **New!** You can now use the `-until` parameter
to close connection after timestamp.
### v1.10
#### Full Documentation
[*Docker Remote API v1.10*](../docker_remote_api_v1.10/)
#### 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
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
container, even if it is currently running
### v1.9
#### Full Documentation
[*Docker Remote API v1.9*](../docker_remote_api_v1.9/)
#### 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.
### v1.8
#### Full Documentation
#### 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.
`GET /containers/`(*id*)`/json`
: **New!** This endpoint now returns the host config for the
container.
`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
`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:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"VirtualSize": 131506275,
"Size": 131506275,
"Created": 1365714795,
"Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
"Tag": "12.04",
"Repository": "ubuntu"
},
{
"VirtualSize": 131506275,
"Size": 131506275,
"Created": 1365714795,
"Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
"Tag": "latest",
"Repository": "ubuntu"
},
{
"VirtualSize": 131506275,
"Size": 131506275,
"Created": 1365714795,
"Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
"Tag": "precise",
"Repository": "ubuntu"
},
{
"VirtualSize": 180116135,
"Size": 24653,
"Created": 1364102658,
"Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
"Tag": "12.10",
"Repository": "ubuntu"
},
{
"VirtualSize": 180116135,
"Size": 24653,
"Created": 1364102658,
"Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
"Tag": "quantal",
"Repository": "ubuntu"
}
]
The returned json looks like this:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"RepoTags": [
"ubuntu:12.04",
"ubuntu:precise",
"ubuntu:latest"
],
"Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
"Created": 1365714795,
"Size": 131506275,
"VirtualSize": 131506275
},
{
"RepoTags": [
"ubuntu:12.10",
"ubuntu:quantal"
],
"ParentId": "27cf784147099545",
"Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
"Created": 1364102658,
"Size": 24653,
"VirtualSize": 180116135
}
]
`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
`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
`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
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.
### v1.4
#### Full Documentation
#### What’s new
`POST /images/create`
: **New!** When pulling a repo, all images are now downloaded in
parallel.
`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
docker v0.5.0
[51f6c4a](https://github.com/dotcloud/docker/commit/51f6c4a7372450d164c61e0054daf0223ddbd909)
#### Full Documentation
#### What’s new
`GET /containers/`(*id*)`/top`
: 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
Warning
The /build improvements are not reverse-compatible. Pre 1.3 clients will
break on /build.
List containers (/containers/json):
- You can use size=1 to get the size of the containers
Start containers (/containers/\<id\>/start):
- You can now pass host-specific configuration (e.g. bind mounts) in
the POST body for start calls
### v1.2
docker v0.4.2
[2e7649b](https://github.com/dotcloud/docker/commit/2e7649beda7c820793bd46766cbc2cfeace7b168)
#### Full Documentation
#### 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
`GET /auth`
: **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.
### v1.1
docker v0.4.0
[a8ae398](https://github.com/dotcloud/docker/commit/a8ae398bf52e97148ee7bd0d5868de2e15bd297f)
#### Full Documentation
#### What’s new
`POST /images/create`
:
`POST /images/`(*name*)`/insert`
:
`POST /images/`(*name*)`/push`
: 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
docker v0.3.4
[8d73740](https://github.com/dotcloud/docker/commit/8d73740343778651c09160cde9661f5f387b36f4)
#### Full Documentation
#### What’s new
Initial version
docs/sources/reference/api/docker_remote_api_v1.10.md
+1238
View File
File diff suppressed because it is too large Load Diff
docs/sources/reference/api/docker_remote_api_v1.11.md
+1242
View File
File diff suppressed because it is too large Load Diff
docs/sources/reference/api/docker_remote_api_v1.9.md
+1255
View File
File diff suppressed because it is too large Load Diff
docs/sources/reference/api/index_api.md
+525
View File
@@ -0,0 +1,525 @@
page_title: Index API
page_description: API Documentation for Docker Index
page_keywords: API, Docker, index, REST, documentation
# Docker Index API
## Introduction
- This is the REST API for the Docker index
- Authorization is done with basic auth over SSL
- Not all commands require authentication, only those noted as such.
## Repository
### Repositories
### User Repo
`PUT /v1/repositories/`(*namespace*)`/`(*repo\_name*)`/`
: Create a user repository with the given `namespace`
and `repo_name`.
**Example Request**:
PUT /v1/repositories/foo/bar/ HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Basic akmklmasadalkm==
X-Docker-Token: true
[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"}]
Parameters:
- **namespace** – the namespace for the repo
- **repo\_name** – the name for the repo
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
WWW-Authenticate: Token signature=123abc,repository="foo/bar",access=write
X-Docker-Token: signature=123abc,repository="foo/bar",access=write
X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]
""
Status Codes:
- **200** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active
`DELETE /v1/repositories/`(*namespace*)`/`(*repo\_name*)`/`
: Delete a user repository with the given `namespace`
and `repo_name`.
**Example Request**:
DELETE /v1/repositories/foo/bar/ HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Basic akmklmasadalkm==
X-Docker-Token: true
""
Parameters:
- **namespace** – the namespace for the repo
- **repo\_name** – the name for the repo
**Example Response**:
HTTP/1.1 202
Vary: Accept
Content-Type: application/json
WWW-Authenticate: Token signature=123abc,repository="foo/bar",access=delete
X-Docker-Token: signature=123abc,repository="foo/bar",access=delete
X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]
""
Status Codes:
- **200** – Deleted
- **202** – Accepted
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active
### 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.
When namespace is missing, it is assumed to be `library`
**Example Request**:
PUT /v1/repositories/foobar/ HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Basic akmklmasadalkm==
X-Docker-Token: true
[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"}]
Parameters:
- **repo\_name** – the library name for the repo
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
WWW-Authenticate: Token signature=123abc,repository="library/foobar",access=write
X-Docker-Token: signature=123abc,repository="foo/bar",access=write
X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]
""
Status Codes:
- **200** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **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.
When namespace is missing, it is assumed to be `library`
**Example Request**:
DELETE /v1/repositories/foobar/ HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Basic akmklmasadalkm==
X-Docker-Token: true
""
Parameters:
- **repo\_name** – the library name for the repo
**Example Response**:
HTTP/1.1 202
Vary: Accept
Content-Type: application/json
WWW-Authenticate: Token signature=123abc,repository="library/foobar",access=delete
X-Docker-Token: signature=123abc,repository="foo/bar",access=delete
X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]
""
Status Codes:
- **200** – Deleted
- **202** – Accepted
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active
### Repository Images
### User Repo Images
`PUT /v1/repositories/`(*namespace*)`/`(*repo\_name*)`/images`
: Update the images for a user repo.
**Example Request**:
PUT /v1/repositories/foo/bar/images HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Basic akmklmasadalkm==
[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
"checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"}]
Parameters:
- **namespace** – the namespace for the repo
- **repo\_name** – the name for the repo
**Example Response**:
HTTP/1.1 204
Vary: Accept
Content-Type: application/json
""
Status Codes:
- **204** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active or permission denied
`GET /v1/repositories/`(*namespace*)`/`(*repo\_name*)`/images`
: get the images for a user repo.
**Example Request**:
GET /v1/repositories/foo/bar/images HTTP/1.1
Host: index.docker.io
Accept: application/json
Parameters:
- **namespace** – the namespace for the repo
- **repo\_name** – the name for the repo
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
"checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"},
{"id": "ertwetewtwe38722009fe6857087b486531f9a779a0c1dfddgfgsdgdsgds",
"checksum": "34t23f23fc17e3ed29dae8f12c4f9e89cc6f0bsdfgfsdgdsgdsgerwgew"}]
Status Codes:
- **200** – OK
- **404** – Not found
### Library Repo Images
`PUT /v1/repositories/`(*repo\_name*)`/images`
: Update the images for a library repo.
**Example Request**:
PUT /v1/repositories/foobar/images HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Basic akmklmasadalkm==
[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
"checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"}]
Parameters:
- **repo\_name** – the library name for the repo
**Example Response**:
HTTP/1.1 204
Vary: Accept
Content-Type: application/json
""
Status Codes:
- **204** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active or permission denied
`GET /v1/repositories/`(*repo\_name*)`/images`
: get the images for a library repo.
**Example Request**:
GET /v1/repositories/foobar/images HTTP/1.1
Host: index.docker.io
Accept: application/json
Parameters:
- **repo\_name** – the library name for the repo
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
"checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"},
{"id": "ertwetewtwe38722009fe6857087b486531f9a779a0c1dfddgfgsdgdsgds",
"checksum": "34t23f23fc17e3ed29dae8f12c4f9e89cc6f0bsdfgfsdgdsgdsgerwgew"}]
Status Codes:
- **200** – OK
- **404** – Not found
### Repository Authorization
### Library Repo
`PUT /v1/repositories/`(*repo\_name*)`/auth`
: authorize a token for a library repo
**Example Request**:
PUT /v1/repositories/foobar/auth HTTP/1.1
Host: index.docker.io
Accept: application/json
Authorization: Token signature=123abc,repository="library/foobar",access=write
Parameters:
- **repo\_name** – the library name for the repo
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
"OK"
Status Codes:
- **200** – OK
- **403** – Permission denied
- **404** – Not found
### User Repo
`PUT /v1/repositories/`(*namespace*)`/`(*repo\_name*)`/auth`
: authorize a token for a user repo
**Example Request**:
PUT /v1/repositories/foo/bar/auth HTTP/1.1
Host: index.docker.io
Accept: application/json
Authorization: Token signature=123abc,repository="foo/bar",access=write
Parameters:
- **namespace** – the namespace for the repo
- **repo\_name** – the name for the repo
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
"OK"
Status Codes:
- **200** – OK
- **403** – Permission denied
- **404** – Not found
### Users
### User Login
`GET /v1/users`
: If you want to check your login, you can try this endpoint
**Example Request**:
GET /v1/users HTTP/1.1
Host: index.docker.io
Accept: application/json
Authorization: Basic akmklmasadalkm==
**Example Response**:
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
OK
Status Codes:
- **200** – no error
- **401** – Unauthorized
- **403** – Account is not Active
### User Register
`POST /v1/users`
: Registering a new account.
**Example request**:
POST /v1/users HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json
{"email": "sam@dotcloud.com",
"password": "toto42",
"username": "foobar"'}
Json Parameters:
 
- **email** – valid email address, that needs to be confirmed
- **username** – min 4 character, max 30 characters, must match
the regular expression [a-z0-9\_].
- **password** – min 5 characters
**Example Response**:
HTTP/1.1 201 OK
Vary: Accept
Content-Type: application/json
"User Created"
Status Codes:
- **201** – User Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
### Update User
`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.
It is up to the client to verify that that password that is sent is
the one that they want. Common approach is to have them type it
twice.
**Example Request**:
PUT /v1/users/fakeuser/ HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Basic akmklmasadalkm==
{"email": "sam@dotcloud.com",
"password": "toto42"}
Parameters:
- **username** – username for the person you want to update
**Example Response**:
HTTP/1.1 204
Vary: Accept
Content-Type: application/json
""
Status Codes:
- **204** – User Updated
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Account is not Active
- **404** – User not found
## Search
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](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.3)
only.
**Example request**:
GET /v1/search?q=search_term HTTP/1.1
Host: example.com
Accept: application/json
**Example response**:
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{"query":"search_term",
"num_results": 3,
"results" : [
{"name": "ubuntu", "description": "An ubuntu image..."},
{"name": "centos", "description": "A centos image..."},
{"name": "fedora", "description": "A fedora image..."}
]
}
Query Parameters:
- **q** – what you want to search for
Status Codes:
- **200** – no error
- **500** – server error
docs/sources/reference/api/registry_api.md
+501
View File
@@ -0,0 +1,501 @@
page_title: Registry API
page_description: API Documentation for Docker Registry
page_keywords: API, Docker, index, registry, REST, documentation
# Docker Registry API
## 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
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.
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
kind of transport implementing HTTP GET and PUT. Read-only registries
can be powered by a simple static HTTP server.
Note
The latter implies that while HTTP is the protocol of choice for a registry, multiple schemes are possible (and in some cases, trivial):
: - HTTP with GET (and PUT for read-write registries);
- local mount point;
- 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).
## Endpoints
### Images
### Layer
`GET /v1/images/`(*image\_id*)`/layer`
: get image layer for a given `image_id`
**Example Request**:
GET /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/layer HTTP/1.1
Host: registry-1.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Token signature=123abc,repository="foo/bar",access=read
Parameters:
- **image\_id** – the id for the layer you want to get
**Example Response**:
HTTP/1.1 200
Vary: Accept
X-Docker-Registry-Version: 0.6.0
Cookie: (Cookie provided by the Registry)
{layer binary data stream}
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Image not found
`PUT /v1/images/`(*image\_id*)`/layer`
: put image layer for a given `image_id`
**Example Request**:
PUT /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/layer HTTP/1.1
Host: registry-1.docker.io
Transfer-Encoding: chunked
Authorization: Token signature=123abc,repository="foo/bar",access=write
{layer binary data stream}
Parameters:
- **image\_id** – the id for the layer you want to get
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
X-Docker-Registry-Version: 0.6.0
""
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Image not found
### Image
`PUT /v1/images/`(*image\_id*)`/json`
: put image for a given `image_id`
**Example Request**:
PUT /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/json HTTP/1.1
Host: registry-1.docker.io
Accept: application/json
Content-Type: application/json
Cookie: (Cookie provided by the Registry)
{
id: "088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c",
parent: "aeee6396d62273d180a49c96c62e45438d87c7da4a5cf5d2be6bee4e21bc226f",
created: "2013-04-30T17:46:10.843673+03:00",
container: "8305672a76cc5e3d168f97221106ced35a76ec7ddbb03209b0f0d96bf74f6ef7",
container_config: {
Hostname: "host-test",
User: "",
Memory: 0,
MemorySwap: 0,
AttachStdin: false,
AttachStdout: false,
AttachStderr: false,
PortSpecs: null,
Tty: false,
OpenStdin: false,
StdinOnce: false,
Env: null,
Cmd: [
"/bin/bash",
"-c",
"apt-get -q -yy -f install libevent-dev"
],
Dns: null,
Image: "imagename/blah",
Volumes: { },
VolumesFrom: ""
},
docker_version: "0.1.7"
}
Parameters:
- **image\_id** – the id for the layer you want to get
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
X-Docker-Registry-Version: 0.6.0
""
Status Codes:
- **200** – OK
- **401** – Requires authorization
`GET /v1/images/`(*image\_id*)`/json`
: get image for a given `image_id`
**Example Request**:
GET /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/json HTTP/1.1
Host: registry-1.docker.io
Accept: application/json
Content-Type: application/json
Cookie: (Cookie provided by the Registry)
Parameters:
- **image\_id** – the id for the layer you want to get
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
X-Docker-Registry-Version: 0.6.0
X-Docker-Size: 456789
X-Docker-Checksum: b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087
{
id: "088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c",
parent: "aeee6396d62273d180a49c96c62e45438d87c7da4a5cf5d2be6bee4e21bc226f",
created: "2013-04-30T17:46:10.843673+03:00",
container: "8305672a76cc5e3d168f97221106ced35a76ec7ddbb03209b0f0d96bf74f6ef7",
container_config: {
Hostname: "host-test",
User: "",
Memory: 0,
MemorySwap: 0,
AttachStdin: false,
AttachStdout: false,
AttachStderr: false,
PortSpecs: null,
Tty: false,
OpenStdin: false,
StdinOnce: false,
Env: null,
Cmd: [
"/bin/bash",
"-c",
"apt-get -q -yy -f install libevent-dev"
],
Dns: null,
Image: "imagename/blah",
Volumes: { },
VolumesFrom: ""
},
docker_version: "0.1.7"
}
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Image not found
### Ancestry
`GET /v1/images/`(*image\_id*)`/ancestry`
: get ancestry for an image given an `image_id`
**Example Request**:
GET /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/ancestry HTTP/1.1
Host: registry-1.docker.io
Accept: application/json
Content-Type: application/json
Cookie: (Cookie provided by the Registry)
Parameters:
- **image\_id** – the id for the layer you want to get
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
X-Docker-Registry-Version: 0.6.0
["088b4502f51920fbd9b7c503e87c7a2c05aa3adc3d35e79c031fa126b403200f",
"aeee63968d87c7da4a5cf5d2be6bee4e21bc226fd62273d180a49c96c62e4543",
"bfa4c5326bc764280b0863b46a4b20d940bc1897ef9c1dfec060604bdc383280",
"6ab5893c6927c15a15665191f2c6cf751f5056d8b95ceee32e43c5e8a3648544"]
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Image not found
### Tags
`GET /v1/repositories/`(*namespace*)`/`(*repository*)`/tags`
: get all of the tags for the given repo.
**Example Request**:
GET /v1/repositories/foo/bar/tags HTTP/1.1
Host: registry-1.docker.io
Accept: application/json
Content-Type: application/json
X-Docker-Registry-Version: 0.6.0
Cookie: (Cookie provided by the Registry)
Parameters:
- **namespace** – namespace for the repo
- **repository** – name for the repo
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
X-Docker-Registry-Version: 0.6.0
{
"latest": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
"0.1.1": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"
}
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Repository not found
`GET /v1/repositories/`(*namespace*)`/`(*repository*)`/tags/`(*tag*)
: get a tag for the given repo.
**Example Request**:
GET /v1/repositories/foo/bar/tags/latest HTTP/1.1
Host: registry-1.docker.io
Accept: application/json
Content-Type: application/json
X-Docker-Registry-Version: 0.6.0
Cookie: (Cookie provided by the Registry)
Parameters:
- **namespace** – namespace for the repo
- **repository** – name for the repo
- **tag** – name of tag you want to get
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
X-Docker-Registry-Version: 0.6.0
"9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Tag not found
`DELETE /v1/repositories/`(*namespace*)`/`(*repository*)`/tags/`(*tag*)
: delete the tag for the repo
**Example Request**:
DELETE /v1/repositories/foo/bar/tags/latest HTTP/1.1
Host: registry-1.docker.io
Accept: application/json
Content-Type: application/json
Cookie: (Cookie provided by the Registry)
Parameters:
- **namespace** – namespace for the repo
- **repository** – name for the repo
- **tag** – name of tag you want to delete
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
X-Docker-Registry-Version: 0.6.0
""
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Tag not found
`PUT /v1/repositories/`(*namespace*)`/`(*repository*)`/tags/`(*tag*)
: put a tag for the given repo.
**Example Request**:
PUT /v1/repositories/foo/bar/tags/latest HTTP/1.1
Host: registry-1.docker.io
Accept: application/json
Content-Type: application/json
Cookie: (Cookie provided by the Registry)
"9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"
Parameters:
- **namespace** – namespace for the repo
- **repository** – name for the repo
- **tag** – name of tag you want to add
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
X-Docker-Registry-Version: 0.6.0
""
Status Codes:
- **200** – OK
- **400** – Invalid data
- **401** – Requires authorization
- **404** – Image not found
### Repositories
`DELETE /v1/repositories/`(*namespace*)`/`(*repository*)`/`
: delete a repository
**Example Request**:
DELETE /v1/repositories/foo/bar/ HTTP/1.1
Host: registry-1.docker.io
Accept: application/json
Content-Type: application/json
Cookie: (Cookie provided by the Registry)
""
Parameters:
- **namespace** – namespace for the repo
- **repository** – name for the repo
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
X-Docker-Registry-Version: 0.6.0
""
Status Codes:
- **200** – OK
- **401** – Requires authorization
- **404** – Repository not found
### Status
`GET /v1/_ping`
: Check status of the registry. This endpoint is also used to
determine if the registry supports SSL.
**Example Request**:
GET /v1/_ping HTTP/1.1
Host: registry-1.docker.io
Accept: application/json
Content-Type: application/json
""
**Example Response**:
HTTP/1.1 200
Vary: Accept
Content-Type: application/json
X-Docker-Registry-Version: 0.6.0
""
Status Codes:
- **200** – OK
## Authorization
This is where we describe the authorization process, including the
tokens and cookies.
TODO: add more info.
docs/sources/reference/api/registry_index_spec.md
+691
View File
@@ -0,0 +1,691 @@
page_title: Registry Documentation
page_description: Documentation for docker Registry and Registry API
page_keywords: docker, registry, api, index
# Registry & Index Spec
## The 3 roles
### Index
The Index is responsible for centralizing information about:
- 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
The index is authoritative for those information.
We expect that there will be only one instance of the index, run and
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)
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.
> **Note:** The latter implies that while HTTP is the protocol
> of choice for a registry, multiple schemes are possible (and
> in some cases, trivial):
>
> - HTTP with GET (and PUT for read-write registries);
> - local mount point;
> - 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).
### Docker
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
## Workflow
### Pull
![](../../../_images/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
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
6. Get the payload for all layers
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
checksum checks.
Currently registry redirects to s3 urls for downloads, going forward all
downloads need to be streamed through the registry. The Registry will
then abstract the calls to S3 by a top-level class which implements
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
for pulling public repos, but if one is provided, it needs to be valid
and for an active account.
#### API (pulling repository foo/bar):
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**:
: (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,
never reuse tokens.
### Push
![](../../../_images/docker_push_chart.png)
1. Contact the index to allocate the repository name “samalba/busybox”
(authentication required with user credentials)
2. If authentication works and namespace available, “samalba/busybox”
is allocated and a temporary token is returned (namespace is marked
as initialized in index)
3. Push the image on the registry (along with the token)
4. Registry A contacts the Index to verify the token (token must
corresponds to the repository name)
5. Index validates the token. Registry A starts reading the stream
pushed by docker and store the repository (with its images)
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
> version of the Registry is deployed to store and serve images. Those
> images are not authenticated and the security is not guaranteed.
> **Note:**
> **Index can be replaced!** For a private Registry deployed, a custom
> Index can be used to serve and validate token according to different
> policies.
Docker computes the checksums and submit them to the Index at the end of
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):
1. (Docker -\> Index) PUT /v1/repositories/foo/bar/
: **Headers**:
: Authorization: Basic sdkjfskdjfhsdkjfh== X-Docker-Token:
true
**Action**::
: - in index, we allocated a new repository, and set to
initialized
**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)
**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)
[{“id”:
“9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f”,
“checksum”:
“b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087”}]
**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
> initialized. Should we allow it, or mark as name already used? One edge
> 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
new token.
### Delete
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
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
corresponds to the repository name)
5. Index validates the token. Registry A deletes the repository and
everything associated to it.
6. docker contacts the index to let it know it was removed from the
registry, the index removes all records from the database.
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
undone.
#### API (deleting repository foo/bar):
1. (Docker -\> Index) DELETE /v1/repositories/foo/bar/
: **Headers**:
: Authorization: Basic sdkjfskdjfhsdkjfh== X-Docker-Token:
true
**Action**::
: - in index, we make sure it is a valid repository, and set
to deleted (logically)
**Body**::
: Empty
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.
3. (Docker -\> Registry) DELETE /v1/repositories/foo/bar/
: **Headers**:
: Authorization: Token
signature=123abc,repository=”foo/bar”,access=delete
4. (Registry-\>Index) PUT /v1/repositories/foo/bar/auth
: **Headers**:
: Authorization: Token
signature=123abc,repository=”foo/bar”,access=delete
**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\>/
- Authenticate a user as a repos owner (for a central referenced
repository)
### Without an Index
Using the Registry without the Index can be useful to store the images
on a private network without having to rely on an external entity
controlled by Docker Inc.
In this case, the registry will be launched in a special mode
(–standalone? –no-index?). In this mode, the only thing which changes is
that Registry will never contact the Index to verify a token. It will be
the Registry owner responsibility to authenticate the user who pushes
(or even pulls) an image using any mechanism (HTTP auth, IP based,
etc...).
In this scenario, the Registry is responsible for the security in case
of data corruption since the checksums are not delivered by a trusted
entity.
As hinted previously, a standalone registry can also be implemented by
any HTTP server handling GET/PUT requests (or even only GET requests if
no write access is necessary).
### With an Index
The Index data needed by the Registry are simple:
- 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.
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
the organization who uses Docker in a private environment) to maintain
the Index and the Docker’s configuration among its consumers.
## The API
The first version of the api is available here:
[https://github.com/jpetazzo/docker/blob/acd51ecea8f5d3c02b00a08176171c59442df8b3/docs/images-repositories-push-pull.md](https://github.com/jpetazzo/docker/blob/acd51ecea8f5d3c02b00a08176171c59442df8b3/docs/images-repositories-push-pull.md)
### Images
The format returned in the images is not defined here (for layer and
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
parent on the next-to-last line, etc.; if the image has no parent, the
file is empty.
GET /v1/images/<image_id>/layer
PUT /v1/images/<image_id>/layer
GET /v1/images/<image_id>/json
PUT /v1/images/<image_id>/json
GET /v1/images/<image_id>/ancestry
PUT /v1/images/<image_id>/ancestry
### Users
### Create a user (Index)
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\_].
- **password**: min 5 characters
**Valid**: return HTTP 200
Errors: HTTP 400 (we should create error codes for possible errors) -
invalid json - missing field - wrong format (username, password, email,
etc) - forbidden name - name already exists
Note
A user account will be valid only if the email has been validated (a
validation link is sent to the email address).
### Update a user (Index)
PUT /v1/users/\<username\>
**Body**:
: {"password": "toto"}
Note
We can also update email address, if they do, they will need to reverify
their new email address.
### Login (Index)
Does nothing else but asking for a user authentication. Can be used to
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
### Tags (Registry)
The Registry does not know anything about users. Even though
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.
The following naming restrictions apply:
- Namespaces must match the same regular expression as usernames (See
4.2.1.)
- Repository names must match the regular expression [a-zA-Z0-9-\_.]
### Get all tags:
GET /v1/repositories/\<namespace\>/\<repository\_name\>/tags
**Return**: HTTP 200
: { "latest":
"9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
“0.1.1”:
“b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087” }
#### 4.3.2 Read the content of a tag (resolve the image id)
GET /v1/repositories/\<namespace\>/\<repo\_name\>/tags/\<tag\>
**Return**:
: "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"
#### 4.3.3 Delete a tag (registry)
DELETE /v1/repositories/\<namespace\>/\<repo\_name\>/tags/\<tag\>
### 4.4 Images (Index)
For the Index to “resolve” the repository name to a Registry location,
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
GET /v1/repositories/\<namespace\>/\<repo\_name\>/images
**Return**: HTTP 200
: [{“id”:
“9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f”,
“checksum”:
“[md5:b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087](md5:b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087)”}]
### Add/update the images:
You always add images, you never remove them.
PUT /v1/repositories/\<namespace\>/\<repo\_name\>/images
**Body**:
: [ {“id”:
“9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f”,
“checksum”:
“sha256:b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087”}
]
**Return** 204
### Repositories
### Remove a Repository (Registry)
DELETE /v1/repositories/\<namespace\>/\<repo\_name\>
Return 200 OK
### Remove a Repository (Index)
This starts the delete process. see 2.3 for more details.
DELETE /v1/repositories/\<namespace\>/\<repo\_name\>
Return 202 OK
## Chaining Registries
It’s possible to chain Registries server for several reasons:
- 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
download.
The Index and Registry use this mechanism to redirect on one or the
other.
Example with an image download:
On every request, a special header can be returned:
X-Docker-Endpoints: server1,server2
On the next request, the client will always pick a server from this
list.
## Authentication & Authorization
### On the Index
The Index supports both “Basic” and “Token” challenges. Usually when
there is a `401 Unauthorized`, the Index replies
this:
401 Unauthorized
WWW-Authenticate: Basic realm="auth required",Token
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
>
2. Provide user credentials only
> **Header**:
> : Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
>
3. Provide Token
> **Header**:
> : Authorization: Token
> signature=123abc,repository=”foo/bar”,access=read
>
### 6.2 On the Registry
The Registry only supports the Token challenge:
401 Unauthorized
WWW-Authenticate: Token
The only way is to provide a token on `401 Unauthorized`
responses:
Authorization: Token signature=123abc,repository="foo/bar",access=read
Usually, the Registry provides a Cookie when a Token verification
succeeded. Every time the Registry passes a Cookie, you have to pass it
back the same cookie.:
200 OK
Set-Cookie: session="wD/J7LqL5ctqw8haL10vgfhrb2Q=?foo=UydiYXInCnAxCi4=&timestamp=RjEzNjYzMTQ5NDcuNDc0NjQzCi4="; Path=/; HttpOnly
Next request:
GET /(...)
Cookie: session="wD/J7LqL5ctqw8haL10vgfhrb2Q=?foo=UydiYXInCnAxCi4=&timestamp=RjEzNjYzMTQ5NDcuNDc0NjQzCi4="
## Document Version
- 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
+89
View File
@@ -0,0 +1,89 @@
page_title: Remote API Client Libraries
page_description: Various client libraries available to use with the Docker remote API
page_keywords: API, Docker, index, registry, REST, documentation, clients, Python, Ruby, JavaScript, Erlang, Go
# Docker Remote API Client Libraries
These libraries have not been tested by the Docker Maintainers for
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)
-------------------------------------------------------------------------