diff --git a/_data/toc.yaml b/_data/toc.yaml index a9200aaa0d..891c6410b4 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -3635,12 +3635,12 @@ manuals: title: Official Images - path: /docker-hub/orgs/ title: Teams & Organizations - - path: /docker-hub/upgrade/ - title: Upgrading your plan - path: /docker-hub/webhooks/ title: Webhooks - path: /docker-hub/slack_integration/ title: Slack Integration + - path: /docker-hub/upgrade/ + title: Upgrading your plan - sectiontitle: Builds section: - path: /docker-hub/builds/ diff --git a/docker-hub/images/official_images-tags.png b/docker-hub/images/official_images-tags.png new file mode 100644 index 0000000000..79bd8fd8c3 Binary files /dev/null and b/docker-hub/images/official_images-tags.png differ diff --git a/docker-hub/index.md b/docker-hub/index.md index b6b2f90869..f887f71417 100644 --- a/docker-hub/index.md +++ b/docker-hub/index.md @@ -115,7 +115,7 @@ We'll need to download Docker Desktop to build and push a container image to Doc 1. Download and install [Docker Desktop](https://docker.com/get-started). If on Linux, download [Docker Engine - Community](https://hub.docker.com/search?type=edition&offering=community) 2. Open the terminal and sign in to Docker Hub on your computer by running `docker login` -### Step 4: Build and push an image to Docker Hub from your computer +### Step 4: Build and push a container image to Docker Hub from your computer 1. Create a Dockerfile to specify your application by running: diff --git a/docker-hub/official_images.md b/docker-hub/official_images.md index 010968aff4..0becb45054 100644 --- a/docker-hub/official_images.md +++ b/docker-hub/official_images.md @@ -39,7 +39,7 @@ place openly on GitHub where participation is encouraged. Anyone can provide feedback, contribute code, suggest process changes, or even propose a new Official Image. -## Should I use Official Images? +## When to use Official Images New Docker users are encouraged to use the Official Images in their projects. These repositories have clear documentation, promote best practices, @@ -60,7 +60,7 @@ insufficient, it is still recommended to inherit from an Official Image base OS image to leverage the ongoing maintenance work, rather than duplicating these efforts. -## How do I know the Official Images are secure? +## Official Image Vulnerability Scanning Each of the images in the Official Images is scanned for vulnerabilities. The results of these security scans provide valuable information about which images contain @@ -73,14 +73,15 @@ To view the Docker Security Scanning results: You can view Official Images even while logged out, however the scan results are only available once you log in. 2. Navigate to the repository of the Official Image whose security scan you want to view. 3. Click the `Tags` tab to see a list of tags and their security scan summaries. - ![Viewing CVEs from Docker images](images/scan-drilldown.gif) + +![Official Image Tags](official_images-tags.png) You can click into a tag's detail page to see more information about which layers in the image and which components within the layer are vulnerable. Details including a link to the official CVE report for the vulnerability appear when you click an individual vulnerable component. -## How can I get involved? +## Submitting Feedback for Official Images All Official Images contain a **User Feedback** section in their documentation which covers the details for that specific repository. In most @@ -88,7 +89,7 @@ cases, the GitHub repository which contains the Dockerfiles for an Official Repository also has an active issue tracker. General feedback and support questions should be directed to `#docker-library` on Freenode IRC. -## How do I create a new Official Image? +## Creating an Official Image From a high level, an Official Image starts out as a proposal in the form of a set of GitHub pull requests. Detailed and objective proposal diff --git a/docker-hub/repos.md b/docker-hub/repos.md index 848d44d1b4..23811e6c9b 100644 --- a/docker-hub/repos.md +++ b/docker-hub/repos.md @@ -4,43 +4,86 @@ keywords: Docker, docker, trusted, registry, accounts, plans, Dockerfile, Docker title: Repositories --- -Docker Hub repositories let you share images with co-workers, customers, or the -Docker community at large. +Docker Hub repositories let you share container images with your team, +customers, or the Docker community at large. -![repositories](/docker-hub/images/repos.png) +- Repositories hold Docker container images: +- One Docker Hub repository can hold many Docker images +- Docker images are pushed to Docker Hub via the [`docker push`](https://docs.docker.com/engine/reference/commandline/push/) command. +- Each image pushed to Docker Hub must have a **tag** +- Tags are named when images are pushed to Docker Hub (e.g. `latest`, `v1.0.0`, `1.0.0`) -## Searching for images +## Creating Repositories -You can search the [Docker Hub](https://hub.docker.com) registry via its search -interface or by using the command line interface. Searching can find images by -image name, user name, or description: - $ docker search centos - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - centos The official build of CentOS. 1034 [OK] - ansible/centos7-ansible Ansible on Centos7 43 [OK] - tutum/centos Centos image with SSH access. For the root... 13 [OK] - ... +## Pushing a Docker container image to Docker Hub -There you can see two example results: `centos` and `ansible/centos7-ansible`. -The second result shows that it comes from the public repository of a user, -named `ansible/`, while the first result, `centos`, doesn't explicitly list a -repository which means that it comes from the top-level namespace for [Official -Images](/docker-hub/official_images.md). The `/` character separates a user's -repository from the image name. +To push a repository to the Docker Hub, you need to +name your local image using your Docker Hub username, and the +repository name that you created in the previous step. +You can add multiple images to a repository, by adding a specific `:` to +it (for example `docs/base:testing`). If it's not specified, the tag defaults to +`latest`. +You can name your local images either when you build it, using +`docker build -t /[:]`, +by re-tagging an existing local image `docker tag /[:]`, +or by using `docker commit /[:]` to commit +changes. -Once you've found the image you want, you can download it with `docker pull `: +Now you can push this repository to the registry designated by its name or tag. - $ docker pull centos - latest: Pulling from centos - 6941bfcbbfca: Pull complete - 41459f052977: Pull complete - fd44297e2ddb: Already exists - centos:latest: The image you are pulling has been verified. Important: image verification is a tech preview feature and should not be relied on to provide security. - Digest: sha256:d601d3b928eb2954653c59e65862aabb31edefa868bd5148a41fa45004c12288 - Status: Downloaded newer image for centos:latest + $ docker push /: + +The image is then uploaded and available for use by your teammates and/or +the community. + +## Private Repositories + +Private repositories allow you to have repositories that contain images that you +want to keep private, either to your own account or within an organization or +team. + +To work with a private repository on [Docker Hub](https://hub.docker.com), you +need to add one using the [Add Repository](https://hub.docker.com/add/repository/) button. You get one private +repository for free with your Docker Hub user account (not usable for +organizations you're a member of). If you need more private repositories for your user account, upgrade +your Docker Hub plan from your [Billing Information](https://hub.docker.com/account/billing-plans/) page. + +Once the private repository is created, you can `push` and `pull` images to and +from it using Docker. + +> **Note**: You need to be signed in and have access to work with a +> private repository. + +Private repositories are just like public ones. However, it isn't possible to +browse them or search their content on the public registry. They do not get +cached the same way as a public repository either. + +You can designate collaborators and manage their access to a private +repository from that repository's *Settings* page. You can also toggle the +repository's status between public and private, if you have an available +repository slot open. Otherwise, you can upgrade your +[Docker Hub](https://hub.docker.com/account/billing-plans/) plan. + +## Public Repositories + +## Editing Repository information + +## Collaborators and their role + +A collaborator is someone you want to give access to a private repository. Once +designated, they can `push` and `pull` to your repositories. They are not +allowed to perform any administrative tasks such as deleting the repository or +changing its status from private to public. + +> **Note**: +> A collaborator cannot add other collaborators. Only the owner of +> the repository has administrative access. + +You can also assign more granular collaborator rights ("Read", "Write", or +"Admin") on Docker Hub by using organizations and teams. For more information +see the [organizations documentation](/docker-hub/orgs.md). -You now have an image from which you can run containers. ## Viewing repository tags @@ -74,115 +117,42 @@ Hub based repository. -## Pushing a repository image to Docker Hub +## Searching for Repositories -To push a repository to the Docker Hub, you need to -name your local image using your Docker Hub username, and the -repository name that you created in the previous step. -You can add multiple images to a repository, by adding a specific `:` to -it (for example `docs/base:testing`). If it's not specified, the tag defaults to -`latest`. -You can name your local images either when you build it, using -`docker build -t /[:]`, -by re-tagging an existing local image `docker tag /[:]`, -or by using `docker commit /[:]` to commit -changes. +You can search the [Docker Hub](https://hub.docker.com) registry via its search +interface or by using the command line interface. Searching can find images by +image name, user name, or description: -Now you can push this repository to the registry designated by its name or tag. + $ docker search centos + NAME DESCRIPTION STARS OFFICIAL AUTOMATED + centos The official build of CentOS. 1034 [OK] + ansible/centos7-ansible Ansible on Centos7 43 [OK] + tutum/centos Centos image with SSH access. For the root... 13 [OK] + ... - $ docker push /: +There you can see two example results: `centos` and `ansible/centos7-ansible`. +The second result shows that it comes from the public repository of a user, +named `ansible/`, while the first result, `centos`, doesn't explicitly list a +repository which means that it comes from the top-level namespace for [Official +Images](/docker-hub/official_images.md). The `/` character separates a user's +repository from the image name. -The image is then uploaded and available for use by your teammates and/or -the community. +Once you've found the image you want, you can download it with `docker pull `: -## Stars + $ docker pull centos + latest: Pulling from centos + 6941bfcbbfca: Pull complete + 41459f052977: Pull complete + fd44297e2ddb: Already exists + centos:latest: The image you are pulling has been verified. Important: image verification is a tech preview feature and should not be relied on to provide security. + Digest: sha256:d601d3b928eb2954653c59e65862aabb31edefa868bd5148a41fa45004c12288 + Status: Downloaded newer image for centos:latest + +You now have an image from which you can run containers. + + +## Starring Repositories Your repositories can be starred and you can star repositories in return. Stars are a way to show that you like a repository. They are also an easy way of bookmarking your favorites. - -## Comments - -You can interact with other members of the Docker community and maintainers by -leaving comments on repositories. If you find any comments that are not -appropriate, you can flag them for review. - -## Collaborators and their role - -A collaborator is someone you want to give access to a private repository. Once -designated, they can `push` and `pull` to your repositories. They are not -allowed to perform any administrative tasks such as deleting the repository or -changing its status from private to public. - -> **Note**: -> A collaborator cannot add other collaborators. Only the owner of -> the repository has administrative access. - -You can also assign more granular collaborator rights ("Read", "Write", or -"Admin") on Docker Hub by using organizations and teams. For more information -see the [organizations documentation](/docker-hub/orgs.md). - -## Private repositories - -Private repositories allow you to have repositories that contain images that you -want to keep private, either to your own account or within an organization or -team. - -To work with a private repository on [Docker Hub](https://hub.docker.com), you -need to add one using the [Add Repository](https://hub.docker.com/add/repository/) button. You get one private -repository for free with your Docker Hub user account (not usable for -organizations you're a member of). If you need more private repositories for your user account, upgrade -your Docker Hub plan from your [Billing Information](https://hub.docker.com/account/billing-plans/) page. - -User and organization accounts maintain separate billing profiles. For more information on managing billing for your account, you may refer to the [Where can I change my billing details?](https://success.docker.com/article/where-can-i-change-my-billing-details) kbase article. - -Once the private repository is created, you can `push` and `pull` images to and -from it using Docker. - -> **Note**: You need to be signed in and have access to work with a -> private repository. - -Private repositories are just like public ones. However, it isn't possible to -browse them or search their content on the public registry. They do not get -cached the same way as a public repository either. - -You can designate collaborators and manage their access to a private -repository from that repository's *Settings* page. You can also toggle the -repository's status between public and private, if you have an available -repository slot open. Otherwise, you can upgrade your -[Docker Hub](https://hub.docker.com/account/billing-plans/) plan. - -### Validating a callback - -To validate a callback in a webhook chain, you need to - -1. Retrieve the `callback_url` value in the request's JSON payload. -1. Send a POST request to this URL containing a valid JSON body. - -> **Note**: A chain request is only considered complete once the last -> callback has been validated. - -To help you debug or simply view the results of your webhook(s), view the -"History" of the webhook available on its settings page. - -#### Callback JSON data - -The following parameters are recognized in callback data: - -* `state` (required): Accepted values are `success`, `failure`, and `error`. - If the state isn't `success`, the webhook chain is interrupted. -* `description`: A string containing miscellaneous information that is - available on Docker Hub. Maximum 255 characters. -* `context`: A string containing the context of the operation. Can be retrieved - from the Docker Hub. Maximum 100 characters. -* `target_url`: The URL where the results of the operation can be found. Can be - retrieved on the Docker Hub. - -*Example callback payload:* - - { - "state": "success", - "description": "387 tests PASSED", - "context": "Continuous integration by Acme CI", - "target_url": "http://ci.acme.com/results/afd339c1c3d27" - } diff --git a/docker-hub/slack_integration.md b/docker-hub/slack_integration.md index 8afc939454..719790af2e 100644 --- a/docker-hub/slack_integration.md +++ b/docker-hub/slack_integration.md @@ -29,9 +29,6 @@ Before you begin, make sure that you are signed into the Slack team that you wan Once you click **Authorize**, you should see a message in the Slack channel notifying you of the new integration. - ![](images/slack-oauth-authorize.png) - - Once configured, choose a notification level: * **Off** Do not receive any notifications. diff --git a/docker-hub/upgrade.md b/docker-hub/upgrade.md index 66806694b7..54a133e39e 100644 --- a/docker-hub/upgrade.md +++ b/docker-hub/upgrade.md @@ -4,6 +4,8 @@ keywords: Docker, docker, trusted, registry, accounts, plans, Dockerfile, Docker title: Upgrading your Plan --- +User and organization accounts maintain separate Docker Hub billing profiles. + ### Upgrading your personal plan Docker Hub includes one private Docker Hub repository for free. If you need diff --git a/docker-hub/webhooks.md b/docker-hub/webhooks.md index bba47db7cb..590e1c94c2 100644 --- a/docker-hub/webhooks.md +++ b/docker-hub/webhooks.md @@ -64,3 +64,36 @@ Docker Hub Webhook payloads have the following payload JSON format: } } ``` + +### Validating a Webhook callback + +To validate a callback in a webhook chain, you need to + +1. Retrieve the `callback_url` value in the request's JSON payload. +1. Send a POST request to this URL containing a valid JSON body. + +> **Note**: A chain request is only considered complete once the last +> callback has been validated. + + +#### Callback JSON data + +The following parameters are recognized in callback data: + +* `state` (required): Accepted values are `success`, `failure`, and `error`. + If the state isn't `success`, the Webhook chain is interrupted. +* `description`: A string containing miscellaneous information that is + available on Docker Hub. Maximum 255 characters. +* `context`: A string containing the context of the operation. Can be retrieved + from the Docker Hub. Maximum 100 characters. +* `target_url`: The URL where the results of the operation can be found. Can be + retrieved on the Docker Hub. + +*Example callback payload:* + + { + "state": "success", + "description": "387 tests PASSED", + "context": "Continuous integration by Acme CI", + "target_url": "http://ci.acme.com/results/afd339c1c3d27" + }