diff options
Diffstat (limited to 'docs/sources/reference')
18 files changed, 172 insertions, 398 deletions
diff --git a/docs/sources/reference/api/docker_io_oauth_api.md b/docs/sources/reference/api/docker_io_oauth_api.md deleted file mode 100644 index c5d07720b8..0000000000 --- a/docs/sources/reference/api/docker_io_oauth_api.md +++ /dev/null @@ -1,254 +0,0 @@ -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`, `profile_write`, - `email_read`, and `email_write`. 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. - -  - - 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` - - **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` - - **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 diff --git a/docs/sources/reference/api/docker_remote_api_v1.0.md b/docs/sources/reference/api/docker_remote_api_v1.0.md index b906298b85..ce45e63994 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.0.md +++ b/docs/sources/reference/api/docker_remote_api_v1.0.md @@ -566,6 +566,13 @@ Insert a file from `url` in the image `name` at `path` {{ STREAM }} + Query Parameters: + + + + - **url** – The url from where the file is taken + - **path** – The path where the file is stored + Status Codes: - **200** – no error @@ -670,12 +677,6 @@ Push the image `name` on the registry {{ STREAM }} - Query Parameters: - - - - - **registry** – the registry you wan to push, optional - Status Codes: - **200** – no error diff --git a/docs/sources/reference/api/docker_remote_api_v1.1.md b/docs/sources/reference/api/docker_remote_api_v1.1.md index 4e449bccec..776ba3e505 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.1.md +++ b/docs/sources/reference/api/docker_remote_api_v1.1.md @@ -573,6 +573,13 @@ Insert a file from `url` in the image `name` at `path` {"error":"Invalid..."} ... + Query Parameters: + + + + - **url** – The url from where the file is taken + - **path** – The path where the file is stored + Status Codes: - **200** – no error @@ -680,12 +687,6 @@ Push the image `name` on the registry {"error":"Invalid..."} ... - Query Parameters: - - - - - **registry** – the registry you wan to push, optional - Status Codes: - **200** – no error diff --git a/docs/sources/reference/api/docker_remote_api_v1.10.md b/docs/sources/reference/api/docker_remote_api_v1.10.md index 264cdefc20..876d0fc370 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.10.md +++ b/docs/sources/reference/api/docker_remote_api_v1.10.md @@ -366,7 +366,7 @@ Start the container `id` { "Binds":["/tmp:/tmp"], - "LxcConf":{"lxc.utsname":"docker"}, + "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, "PublishAllPorts":false, "Privileged":false @@ -739,6 +739,13 @@ Insert a file from `url` in the image {"error":"Invalid..."} ... + Query Parameters: + + + + - **url** – The url from where the file is taken + - **path** – The path where the file is stored + Status Codes: - **200** – no error @@ -846,11 +853,20 @@ Push the image `name` on the registry {"error":"Invalid..."} ... + If you wish to push an image on to a private registry, that image must already have been tagged + into a repository which references that registry host name and port. This repository name should + then be used in the URL. This mirrors the flow of the CLI. + + **Example request**: + + POST /images/registry.acme.com:5000/test/push HTTP/1.1 + + Query Parameters: - - **registry** – the registry you wan to push, optional + - **tag** – the tag to associate with the image on the registry, optional Request Headers: diff --git a/docs/sources/reference/api/docker_remote_api_v1.11.md b/docs/sources/reference/api/docker_remote_api_v1.11.md index ae2daae407..09d478678a 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.11.md +++ b/docs/sources/reference/api/docker_remote_api_v1.11.md @@ -406,7 +406,7 @@ Start the container `id` { "Binds":["/tmp:/tmp"], - "LxcConf":{"lxc.utsname":"docker"}, + "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, "PublishAllPorts":false, "Privileged":false, @@ -861,11 +861,20 @@ Push the image `name` on the registry {"error":"Invalid..."} ... + If you wish to push an image on to a private registry, that image must already have been tagged + into a repository which references that registry host name and port. This repository name should + then be used in the URL. This mirrors the flow of the CLI. + + **Example request**: + + POST /images/registry.acme.com:5000/test/push HTTP/1.1 + + Query Parameters: - - **registry** – the registry you wan to push, optional + - **tag** – the tag to associate with the image on the registry, optional Request Headers: diff --git a/docs/sources/reference/api/docker_remote_api_v1.12.md b/docs/sources/reference/api/docker_remote_api_v1.12.md index 19fb24fe48..3102345c52 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.12.md +++ b/docs/sources/reference/api/docker_remote_api_v1.12.md @@ -407,7 +407,7 @@ Start the container `id` { "Binds":["/tmp:/tmp"], "Links":["redis3:redis"], - "LxcConf":{"lxc.utsname":"docker"}, + "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, "PublishAllPorts":false, "Privileged":false, @@ -808,30 +808,7 @@ Create an image, either by pull it from the registry or by importing it - **200** – no error - **500** – server error -### Insert a file in an image -`POST /images/(name)/insert` - -Insert a file from `url` in the image `name` at `path` - - **Example request**: - - POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 - - **Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Inserting..."} - {"status":"Inserting", "progress":"1/? (n/a)", "progressDetail":{"current":1}} - {"error":"Invalid..."} - ... - - Status Codes: - - - **200** – no error - - **500** – server error ### Inspect an image @@ -937,11 +914,20 @@ Push the image `name` on the registry {"error":"Invalid..."} ... + If you wish to push an image on to a private registry, that image must already have been tagged + into a repository which references that registry host name and port. This repository name should + then be used in the URL. This mirrors the flow of the CLI. + + **Example request**: + + POST /images/registry.acme.com:5000/test/push HTTP/1.1 + + Query Parameters: - - **registry** – the registry you wan to push, optional + - **tag** – the tag to associate with the image on the registry, optional Request Headers: diff --git a/docs/sources/reference/api/docker_remote_api_v1.13.md b/docs/sources/reference/api/docker_remote_api_v1.13.md index e0ad957941..cb62a62c0d 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.13.md +++ b/docs/sources/reference/api/docker_remote_api_v1.13.md @@ -405,7 +405,7 @@ Start the container `id` { "Binds":["/tmp:/tmp"], "Links":["redis3:redis"], - "LxcConf":{"lxc.utsname":"docker"}, + "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, "PublishAllPorts":false, "Privileged":false, @@ -808,30 +808,7 @@ Create an image, either by pull it from the registry or by importing it - **200** – no error - **500** – server error -### Insert a file in an image -`POST /images/(name)/insert` - -Insert a file from `url` in the image `name` at `path` - - **Example request**: - - POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 - - **Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status":"Inserting..."} - {"status":"Inserting", "progress":"1/? (n/a)", "progressDetail":{"current":1}} - {"error":"Invalid..."} - ... - - Status Codes: - - - **200** – no error - - **500** – server error ### Inspect an image @@ -937,11 +914,20 @@ Push the image `name` on the registry {"error":"Invalid..."} ... + If you wish to push an image on to a private registry, that image must already have been tagged + into a repository which references that registry host name and port. This repository name should + then be used in the URL. This mirrors the flow of the CLI. + + **Example request**: + + POST /images/registry.acme.com:5000/test/push HTTP/1.1 + + Query Parameters: - - **registry** – the registry you wan to push, optional + - **tag** – the tag to associate with the image on the registry, optional Request Headers: diff --git a/docs/sources/reference/api/docker_remote_api_v1.2.md b/docs/sources/reference/api/docker_remote_api_v1.2.md index 37a8e1c012..bf68213864 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.2.md +++ b/docs/sources/reference/api/docker_remote_api_v1.2.md @@ -589,6 +589,13 @@ Insert a file from `url` in the image `name` at `path` {"error":"Invalid..."} ... + Query Parameters: + + + + - **url** – The url from where the file is taken + - **path** – The path where the file is stored + Status Codes: - **200** – no error @@ -699,12 +706,6 @@ Push the image `name` on the registry {"error":"Invalid..."} ... - Query Parameters: - - - - - **registry** – the registry you wan to push, optional - Status Codes: - **200** – no error diff --git a/docs/sources/reference/api/docker_remote_api_v1.3.md b/docs/sources/reference/api/docker_remote_api_v1.3.md index b510f660fd..e9d643cf77 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.3.md +++ b/docs/sources/reference/api/docker_remote_api_v1.3.md @@ -639,6 +639,13 @@ Insert a file from `url` in the image `name` at `path` {"error":"Invalid..."} ... + Query Parameters: + + + + - **url** – The url from where the file is taken + - **path** – The path where the file is stored + Status Codes: - **200** – no error @@ -748,12 +755,6 @@ Push the image `name` on the registry {"error":"Invalid..."} ... - Query Parameters: - - - - - **registry** – the registry you wan to push, optional - Status Codes: - **200** – no error diff --git a/docs/sources/reference/api/docker_remote_api_v1.4.md b/docs/sources/reference/api/docker_remote_api_v1.4.md index 0e49402621..1045f74203 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.4.md +++ b/docs/sources/reference/api/docker_remote_api_v1.4.md @@ -685,6 +685,13 @@ Insert a file from `url` in the image `name` at `path` {"error":"Invalid..."} ... + Query Parameters: + + + + - **url** – The url from where the file is taken + - **path** – The path where the file is stored + Status Codes: - **200** – no error @@ -794,12 +801,6 @@ Push the image `name` on the registry {"status":"Pushing..."} {"status":"Pushing", "progress":"1/? (n/a)"} {"error":"Invalid..."} ... - Query Parameters: - - - - - **registry** – the registry you wan to push, optional - Status Codes: - **200** – no error :statuscode 404: no such image :statuscode diff --git a/docs/sources/reference/api/docker_remote_api_v1.5.md b/docs/sources/reference/api/docker_remote_api_v1.5.md index 33c1aeca1e..5b04957894 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.5.md +++ b/docs/sources/reference/api/docker_remote_api_v1.5.md @@ -686,6 +686,13 @@ Insert a file from `url` in the image `name` at `path` {"error":"Invalid..."} ... + Query Parameters: + + + + - **url** – The url from where the file is taken + - **path** – The path where the file is stored + Status Codes: - **200** – no error @@ -798,12 +805,6 @@ Push the image `name` on the registry The `X-Registry-Auth` header can be used to include a base64-encoded AuthConfig object. - Query Parameters: - - - - - **registry** – the registry you wan to push, optional - Status Codes: - **200** – no error diff --git a/docs/sources/reference/api/docker_remote_api_v1.6.md b/docs/sources/reference/api/docker_remote_api_v1.6.md index 4500c1554c..105a21a53a 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.6.md +++ b/docs/sources/reference/api/docker_remote_api_v1.6.md @@ -391,7 +391,7 @@ Start the container `id` { "Binds":["/tmp:/tmp"], - "LxcConf":{"lxc.utsname":"docker"}, + "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], "ContainerIDFile": "", "Privileged": false, "PortBindings": {"22/tcp": [{HostIp:"", HostPort:""}]}, @@ -793,6 +793,13 @@ Insert a file from `url` in the image `name` at `path` {"error":"Invalid..."} ... + Query Parameters: + + + + - **url** – The url from where the file is taken + - **path** – The path where the file is stored + Status Codes: - **200** – no error @@ -903,12 +910,6 @@ Push the image `name` on the registry > The `X-Registry-Auth` header can be used to > include a base64-encoded AuthConfig object. - Query Parameters: - - - - - **registry** – the registry you wan to push, optional - Status Codes: - **200** – no error :statuscode 404: no such image :statuscode diff --git a/docs/sources/reference/api/docker_remote_api_v1.7.md b/docs/sources/reference/api/docker_remote_api_v1.7.md index 402efa4262..a79ca863b6 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.7.md +++ b/docs/sources/reference/api/docker_remote_api_v1.7.md @@ -347,7 +347,7 @@ Start the container `id` { "Binds":["/tmp:/tmp"], - "LxcConf":{"lxc.utsname":"docker"}, + "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, "Privileged":false, "PublishAllPorts":false @@ -712,6 +712,13 @@ Insert a file from `url` in the image `name` at `path` {"error":"Invalid..."} ... + Query Parameters: + + + + - **url** – The url from where the file is taken + - **path** – The path where the file is stored + Status Codes: - **200** – no error @@ -821,12 +828,6 @@ Push the image `name` on the registry {"error":"Invalid..."} ... - Query Parameters: - - - - - **registry** – the registry you wan to push, optional - Request Headers: diff --git a/docs/sources/reference/api/docker_remote_api_v1.8.md b/docs/sources/reference/api/docker_remote_api_v1.8.md index 78fccaf281..b0bc377fed 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.8.md +++ b/docs/sources/reference/api/docker_remote_api_v1.8.md @@ -383,7 +383,7 @@ Start the container `id` { "Binds":["/tmp:/tmp"], - "LxcConf":{"lxc.utsname":"docker"}, + "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, "PublishAllPorts":false, "Privileged":false @@ -754,6 +754,13 @@ Insert a file from `url` in the image `name` at `path` {"error":"Invalid..."} ... + Query Parameters: + + + + - **url** – The url from where the file is taken + - **path** – The path where the file is stored + Status Codes: - **200** – no error @@ -863,12 +870,6 @@ Push the image `name` on the registry {"error":"Invalid..."} ... - Query Parameters: - - - - - **registry** – the registry you wan to push, optional - Request Headers: diff --git a/docs/sources/reference/api/docker_remote_api_v1.9.md b/docs/sources/reference/api/docker_remote_api_v1.9.md index 741a9ac955..56eb025b08 100644 --- a/docs/sources/reference/api/docker_remote_api_v1.9.md +++ b/docs/sources/reference/api/docker_remote_api_v1.9.md @@ -383,7 +383,7 @@ Start the container `id` { "Binds":["/tmp:/tmp"], - "LxcConf":{"lxc.utsname":"docker"}, + "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, "PublishAllPorts":false, "Privileged":false @@ -758,6 +758,13 @@ Insert a file from `url` in the image `name` at `path` {"error":"Invalid..."} ... + Query Parameters: + + + + - **url** – The url from where the file is taken + - **path** – The path where the file is stored + Status Codes: - **200** – no error @@ -867,12 +874,6 @@ Push the image `name` on the registry {"error":"Invalid..."} ... - Query Parameters: - - - - - **registry** – the registry you wan to push, optional - Request Headers: diff --git a/docs/sources/reference/api/registry_api.md b/docs/sources/reference/api/registry_api.md index a3d4f23d66..49776b9b18 100644 --- a/docs/sources/reference/api/registry_api.md +++ b/docs/sources/reference/api/registry_api.md @@ -67,6 +67,8 @@ The latter would only require two new commands in docker, e.g., (and optionally doing consistency checks). Authentication and authorization are then delegated to SSH (e.g., with public keys). +The default namespace for a private repository is `library`. + # Endpoints ## Images @@ -305,7 +307,7 @@ Get all of the tags for the given repo. **Example Request**: - GET /v1/repositories/foo/bar/tags HTTP/1.1 + GET /v1/repositories/reynholm/help-system-server/tags HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json @@ -341,7 +343,7 @@ Get a tag for the given repo. **Example Request**: - GET /v1/repositories/foo/bar/tags/latest HTTP/1.1 + GET /v1/repositories/reynholm/help-system-server/tags/latest HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json @@ -375,7 +377,7 @@ Delete the tag for the repo **Example Request**: - DELETE /v1/repositories/foo/bar/tags/latest HTTP/1.1 + DELETE /v1/repositories/reynholm/help-system-server/tags/latest HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json @@ -408,7 +410,7 @@ Put a tag for the given repo. **Example Request**: - PUT /v1/repositories/foo/bar/tags/latest HTTP/1.1 + PUT /v1/repositories/reynholm/help-system-server/tags/latest HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json @@ -446,7 +448,7 @@ Delete a repository **Example Request**: - DELETE /v1/repositories/foo/bar/ HTTP/1.1 + DELETE /v1/repositories/reynholm/help-system-server/ HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json diff --git a/docs/sources/reference/builder.md b/docs/sources/reference/builder.md index 57ddb52984..cbda7cef95 100644 --- a/docs/sources/reference/builder.md +++ b/docs/sources/reference/builder.md @@ -27,6 +27,19 @@ the build. The build is run by the Docker daemon, not by the CLI, so the whole context must be transferred to the daemon. The Docker CLI reports "Sending build context to Docker daemon" when the context is sent to the daemon. +> **Warning** +> Avoid using your root directory, `/`, as the root of the source repository. The +> `docker build` command will use whatever directory contains the Dockerfile as the build +> context (including all of its subdirectories). The build context will be sent to the +> Docker daemon before building the image, which means if you use `/` as the source +> repository, the entire contents of your hard drive will get sent to the daemon (and +> thus to the machine running the daemon). You probably don't want that. + +In most cases, it's best to put each Dockerfile in an empty directory, and then add only +the files needed for building that Dockerfile to that directory. To further speed up the +build, you can exclude files and directories by adding a `.dockerignore` file to the same +directory. + You can specify a repository and tag at which to save the new image if the build succeeds: @@ -164,6 +177,11 @@ any point in an image's history, much like source control. The *exec* form makes it possible to avoid shell string munging, and to `RUN` commands using a base image that does not contain `/bin/sh`. +> **Note**: +> To use a different shell, other than '/bin/sh', use the *exec* form +> passing in the desired shell. For example, +> `RUN ["/bin/bash", "-c", "echo hello"]` + The cache for `RUN` instructions isn't invalidated automatically during the next build. The cache for an instruction like `RUN apt-get dist-upgrade -y` will be reused during the next build. The cache for @@ -196,6 +214,11 @@ container.** These defaults can include an executable, or they can omit the executable, in which case you must specify an `ENTRYPOINT` instruction as well. +> **Note**: +> If `CMD` is used to provide default arguments for the `ENTRYPOINT` +> instruction, both the `CMD` and `ENTRYPOINT` instructions should be specified +> with the JSON array format. + When used in the shell or exec formats, the `CMD` instruction sets the command to be executed when running the image. @@ -409,7 +432,7 @@ optional but default, you could use a `CMD` instruction: FROM ubuntu CMD ["-l"] - ENTRYPOINT ["/usr/bin/ls"] + ENTRYPOINT ["ls"] > **Note**: > It is preferable to use the JSON array format for specifying @@ -444,7 +467,10 @@ It can be used multiple times in the one `Dockerfile`. If a relative path is provided, it will be relative to the path of the previous `WORKDIR` instruction. For example: - WORKDIR /a WORKDIR b WORKDIR c RUN pwd + WORKDIR /a + WORKDIR b + WORKDIR c + RUN pwd The output of the final `pwd` command in this Dockerfile would be `/a/b/c`. @@ -516,23 +542,16 @@ For example you might add something like this: FROM ubuntu MAINTAINER Victor Vieux <victor@docker.com> - # make sure the package repository is up to date - RUN echo "deb http://archive.ubuntu.com/ubuntu precise main universe" > /etc/apt/sources.list - RUN apt-get update - - RUN apt-get install -y inotify-tools nginx apache2 openssh-server + RUN apt-get update && apt-get install -y inotify-tools nginx apache2 openssh-server # Firefox over VNC # # VERSION 0.3 FROM ubuntu - # make sure the package repository is up to date - RUN echo "deb http://archive.ubuntu.com/ubuntu precise main universe" > /etc/apt/sources.list - RUN apt-get update # Install vnc, xvfb in order to create a 'fake' display and firefox - RUN apt-get install -y x11vnc xvfb firefox + RUN apt-get update && apt-get install -y x11vnc xvfb firefox RUN mkdir /.vnc # Setup a password RUN x11vnc -storepasswd 1234 ~/.vnc/passwd diff --git a/docs/sources/reference/commandline/cli.md b/docs/sources/reference/commandline/cli.md index e82a5b1127..8166bf190d 100644 --- a/docs/sources/reference/commandline/cli.md +++ b/docs/sources/reference/commandline/cli.md @@ -324,7 +324,7 @@ schema. > **Note:** `docker build` will return a `no such file or directory` error > if the file or directory does not exist in the uploaded context. This may -> happen if there is no context, or if you specify a file that is elsewhere +> happen if there is no context, or if you specify a file that is elsewhere > on the Host system. The context is limited to the current directory (and its > children) for security reasons, and to ensure repeatable builds on remote > Docker hosts. This is also the reason why `ADD ../file` will not work. @@ -500,7 +500,7 @@ by default. <none> <none> 77af4d6b9913 19 hours ago 1.089 GB committest latest b6fa739cedf5 19 hours ago 1.089 GB <none> <none> 78a85c484f71 19 hours ago 1.089 GB - $ docker latest 30557a29d5ab 20 hours ago 1.089 GB + docker latest 30557a29d5ab 20 hours ago 1.089 GB <none> <none> 0124422dd9f9 20 hours ago 1.089 GB <none> <none> 18ad6fad3402 22 hours ago 1.082 GB <none> <none> f9f1e26352f0 23 hours ago 1.089 GB @@ -514,7 +514,7 @@ by default. <none> <none> 77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 19 hours ago 1.089 GB committest latest b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f 19 hours ago 1.089 GB <none> <none> 78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921 19 hours ago 1.089 GB - $ docker latest 30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB + docker latest 30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB <none> <none> 0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5 20 hours ago 1.089 GB <none> <none> 18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b 22 hours ago 1.082 GB <none> <none> f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a 23 hours ago 1.089 GB @@ -1103,14 +1103,14 @@ network and environment of the `redis` container via environment variables. The `--name` flag will assign the name `console` to the newly created container. - $ sudo docker run --volumes-from 777f7dc92da7,ba8c0c54f0f2:ro -i -t ubuntu pwd + $ sudo docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd The `--volumes-from` flag mounts all the defined volumes from the referenced -containers. Containers can be specified by a comma separated list or by -repetitions of the `--volumes-from` argument. The container ID may be -optionally suffixed with `:ro` or `:rw` to mount the volumes in read-only -or read-write mode, respectively. By default, the volumes are mounted in -the same mode (read write or read only) as the reference container. +containers. Containers can be specified by repetitions of the `--volumes-from` +argument. The container ID may be optionally suffixed with `:ro` or `:rw` to +mount the volumes in read-only or read-write mode, respectively. By default, +the volumes are mounted in the same mode (read write or read only) as +the reference container. The `-a` flag tells `docker run` to bind to the container's `STDIN`, `STDOUT` or `STDERR`. This makes it possible to manipulate the output and input as needed. @@ -1213,7 +1213,7 @@ more details on finding shared images from the command line. -a, --attach=false Attach container's STDOUT and STDERR and forward all signals to the process -i, --interactive=false Attach container's STDIN -When run on a container that has already been started, +When run on a container that has already been started, takes no action and succeeds unconditionally. ## stop |