0ct0pu5/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Removing Hub v1 documentation, Hub v2 documentation will come from that repository

Browse source 
Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au>
This commit is contained in:
Sven Dowideit 2015-08-06 23:00:49 +00:00
parent 8534090476
commit 70092b3ee0
32 changed files with 2 additions and 1059 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

86
docs/docker-hub/accounts.md
View file

@ -1,86 +0,0 @@
<!--[metadata]>
+++
title = "Accounts on Docker Hub"
description = "Docker Hub accounts"
keywords = ["Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, docs, documentation"]
[menu.main]
parent = "smn_pubhub"
weight = 1
+++
<![end-metadata]-->
# Accounts on Docker Hub
## Docker Hub accounts
You can `search` for Docker images and `pull` them from [Docker
Hub](https://hub.docker.com) without signing in or even having an
account. However, in order to `push` images, leave comments or to *star*
a repository, you are going to need a [Docker
Hub](https://hub.docker.com) account.
### Registration for a Docker Hub account
You can get a [Docker Hub](https://hub.docker.com) account by
[signing up for one here](https://hub.docker.com/account/signup/). A valid
email address is required to register, which you will need to verify for
account activation.
### Email activation process
You need to have at least one verified email address to be able to use your
[Docker Hub](https://hub.docker.com) account. If you can't find the validation email,
you can request another by visiting the [Resend Email Confirmation](
https://hub.docker.com/account/resend-email-confirmation/) page.
### Password reset process
If you can't access your account for some reason, you can reset your password
from the [*Password Reset*](https://hub.docker.com/account/forgot-password/)
page.
## Organizations and groups
A Docker Hub organization contains public and private repositories just like
a user account. Access to push, pull or create these organisation owned repositories
is allocated by defining groups of users and then assigning group rights to
specific repositories. This allows you to distribute limited access
Docker images, and to select which Docker Hub users can publish new images.
### Creating and viewing organizations
You can see what organizations [you belong to and add new organizations](
https://hub.docker.com/account/organizations/) from the Account Settings
tab. They are also listed below your user name on your repositories page
and in your account profile.
![organizations](/docker-hub/hub-images/orgs.png)
### Organization groups
Users in the `Owners` group of an organization can create and modify the
membership of groups.
Unless they are the organization's `Owner`, users can only see groups of which they
are members.
![groups](/docker-hub/hub-images/groups.png)
### Repository group permissions
Use organization groups to manage the users that can interact with your repositories.
You must be in an organization's `Owners` group to create a new group, Hub
repository, or automated build. As an `Owner`, you then delegate the following
repository access rights to groups:
| Access Right | Description |
|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Read` | Users with this right can view, search, and pull a private repository. |
| `Write` | Users with this right can push to non-automated repositories on the Docker Hub. |
| `Admin` | Users with this right can modify a repository's "Description", "Collaborators" rights. They can also mark a repository as unlisted, change its "Public/Private" status and "Delete" the repository. Finally, `Admin` rights are required to read the build log on a repo. |
| | |
Regardless of their actual access rights, users with unverified email addresses
have `Read` access to the repository. Once they have verified their address,
they have their full access rights as granted on the organization.

465
docs/docker-hub/builds.md
View file

@ -1,465 +0,0 @@
<!--[metadata]>
+++
title = "Automated Builds on Docker Hub"
description = "Docker Hub Automated Builds"
keywords = ["Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, docs, documentation, trusted, builds, trusted builds, automated builds"]
[menu.main]
parent = "smn_pubhub"
weight = 3
+++
<![end-metadata]-->
# Automated Builds on Docker Hub
## About Automated Builds
*Automated Builds* are a special feature of Docker Hub which allow you to
use [Docker Hub's](https://hub.docker.com) build clusters to automatically
create images from a GitHub or Bitbucket repository containing a `Dockerfile`
The system will clone your repository and build the image described by the
`Dockerfile` using the directory the `Dockerfile` is in (and subdirectories)
as the build context. The resulting automated image will then be uploaded
to the Docker Hub registry and marked as an *Automated Build*.
Automated Builds have several advantages:
* Users of *your* Automated Build can trust that the resulting
image was built exactly as specified.
* The `Dockerfile` will be available to anyone with access to
your repository on the Docker Hub registry.
* Because the process is automated, Automated Builds help to
make sure that your repository is always up to date.
* Not having to push local Docker images to Docker Hub saves
you both network bandwidth and time.
Automated Builds are supported for both public and private repositories
on both [GitHub](http://github.com) and [Bitbucket](https://bitbucket.org/).
To use Automated Builds, you must have an [account on Docker Hub](
https://docs.docker.com/userguide/dockerhub/#creating-a-docker-hub-account)
and on GitHub and/or Bitbucket. In either case, the account needs
to be properly validated and activated before you can link to it.
The first time you to set up an Automated Build, your
[Docker Hub](https://hub.docker.com) account will need to be linked to
a GitHub or Bitbucket account.
This will allow the registry to see your repositories.
If you have previously linked your Docker Hub account, and want to view or modify
that link, click on the "Manage - Settings" link in the sidebar, and then
"Linked Accounts" in your Settings sidebar.
## Automated Builds from GitHub
If you've previously linked your Docker Hub account to your GitHub account,
you'll be able to skip to the [Creating an Automated Build](#creating-an-automated-build).
### Linking your Docker Hub account to a GitHub account
> *Note:*
> Automated Builds currently require *read* and *write* access since
> [Docker Hub](https://hub.docker.com) needs to setup a GitHub service
> hook. We have no choice here, this is how GitHub manages permissions, sorry!
> We do guarantee nothing else will be touched in your account.
To get started, log into your Docker Hub account and click the
"+ Add Repository" button at the upper right of the screen. Then select
[Automated Build](https://registry.hub.docker.com/builds/add/).
Select the [GitHub service](https://registry.hub.docker.com/associate/github/).
When linking to GitHub, you'll need to select either "Public and Private",
or "Limited" linking.
The "Public and Private" option is the easiest to use,
as it grants the Docker Hub full access to all of your repositories. GitHub
also allows you to grant access to repositories belonging to your GitHub
organizations.
By choosing the "Limited" linking, your Docker Hub account only gets permission
to access your public data and public repositories.
Follow the onscreen instructions to authorize and link your
GitHub account to Docker Hub. Once it is linked, you'll be able to
choose a source repository from which to create the Automatic Build.
You will be able to review and revoke Docker Hub's access by visiting the
[GitHub User's Applications settings](https://github.com/settings/applications).
> **Note**: If you delete the GitHub account linkage that is used for one of your
> automated build repositories, the previously built images will still be available.
> If you re-link to that GitHub account later, the automated build can be started
> using the "Start Build" button on the Hub, or if the webhook on the GitHub repository
> still exists, will be triggered by any subsequent commits.
### Auto builds and limited linked GitHub accounts.
If you selected to link your GitHub account with only a "Limited" link, then
after creating your automated build, you will need to either manually trigger a
Docker Hub build using the "Start a Build" button, or add the GitHub webhook
manually, as described in [GitHub Service Hooks](#github-service-hooks).
### Changing the GitHub user link
If you want to remove, or change the level of linking between your GitHub account
and the Docker Hub, you need to do this in two places.
First, remove the "Linked Account" from your Docker Hub "Settings".
Then go to your GitHub account's Personal settings, and in the "Applications"
section, "Revoke access".
You can now re-link your account at any time.
### GitHub organizations
GitHub organizations and private repositories forked from organizations will be
made available to auto build using the "Docker Hub Registry" application, which
needs to be added to the organization - and then will apply to all users.
To check, or request access, go to your GitHub user's "Setting" page, select the
"Applications" section from the left side bar, then click the "View" button for
"Docker Hub Registry".
![Check User access to GitHub](/docker-hub/hub-images/gh-check-user-org-dh-app-access.png)
The organization's administrators may need to go to the Organization's "Third
party access" screen in "Settings" to Grant or Deny access to the Docker Hub
Registry application. This change will apply to all organization members.
![Check Docker Hub application access to Organization](/docker-hub/hub-images/gh-check-admin-org-dh-app-access.png)
More detailed access controls to specific users and GitHub repositories would be
managed using the GitHub People and Teams interfaces.
### Creating an Automated Build
You can [create an Automated Build](
https://registry.hub.docker.com/builds/github/select/) from any of your
public or private GitHub repositories that have a `Dockerfile`.
Once you've selected the source repository, you can then configure:
- The Hub user/org the repository is built to - either your Hub account name,
or the name of any Hub organizations your account is in
- The Docker repository name the image is built to
- If the Docker repository should be "Public" or "Private"
You can change the accessibility options after the repository has been created.
If you add a Private repository to a Hub user, then you can only add other users
as collaborators, and those users will be able to view and pull all images in that
repository. To configure more granular access permissions, such as using groups of
users or allow different users access to different image tags, then you need
to add the Private repository to a Hub organization that your user has Administrator
privilege on.
- If you want the GitHub to notify the Docker Hub when a commit is made, and thus trigger
a rebuild of all the images in this automated build.
You can also select one or more
- The git branch/tag, which repository sub-directory to use as the context
- The Docker image tag name
You can set a description for the repository by clicking "Description" link in the righthand side bar after the automated build - note that the "Full Description" will be over-written next build from the README.md file.
has been created.
### GitHub private submodules
If your GitHub repository contains links to private submodules, you'll get an
error message in your build.
Normally, the Docker Hub sets up a deploy key in your GitHub repository.
Unfortunately, GitHub only allows a repository deploy key to access a single repository.
To work around this, you need to create a dedicated user account in GitHub and attach
the automated build's deploy key that account. This dedicated build account
can be limited to read-only access to just the repositories required to build.
<table class="table table-bordered">
<thead>
<tr>
<th>Step</th>
<th>Screenshot</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>1.</td>
<td><img src="/docker-hub/hub-images/gh_org_members.png"></td>
<td>First, create the new account in GitHub. It should be given read-only
access to the main repository and all submodules that are needed.</td>
</tr>
<tr>
<td>2.</td>
<td><img src="/docker-hub/hub-images/gh_team_members.png"></td>
<td>This can be accomplished by adding the account to a read-only team in
the organization(s) where the main GitHub repository and all submodule
repositories are kept.</td>
</tr>
<tr>
<td>3.</td>
<td><img src="/docker-hub/hub-images/gh_repo_deploy_key.png"></td>
<td>Next, remove the deploy key from the main GitHub repository. This can be done in the GitHub repository's "Deploy keys" Settings section.</td>
</tr>
<tr>
<td>4.</td>
<td><img src="/docker-hub/hub-images/deploy_key.png"></td>
<td>Your automated build's deploy key is in the "Build Details" menu
under "Deploy keys".</td>
</tr>
<tr>
<td>5.</td>
<td><img src="/docker-hub/hub-images/gh_add_ssh_user_key.png"></td>
<td>In your dedicated GitHub User account, add the deploy key from your
Docker Hub Automated Build.</td>
</tr>
</tbody>
</table>
### GitHub service hooks
The GitHub Service hook allows GitHub to notify the Docker Hub when something has
been committed to that git repository. You will need to add the Service Hook manually
if your GitHub account is "Limited" linked to the Docker Hub.
Follow the steps below to configure the GitHub Service hooks for your Automated Build:
<table class="table table-bordered">
<thead>
<tr>
<th>Step</th>
<th>Screenshot</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>1.</td>
<td><img src="/docker-hub/hub-images/gh_settings.png"></td>
<td>Log in to GitHub.com, and go to your Repository page. Click on "Settings" on
the right side of the page. You must have admin privileges to the repository in order to do this.</td>
</tr>
<tr>
<td>2.</td>
<td><img src="/docker-hub/hub-images/gh_menu.png" alt="Webhooks & Services"></td>
<td>Click on "Webhooks & Services" on the left side of the page.</td></tr>
<tr><td>3.</td>
<td><img src="/docker-hub/hub-images/gh_service_hook.png" alt="Find the service labeled Docker"></td>
<td>Find the service labeled "Docker" (or click on "Add service") and click on it.</td></tr>
<tr><td>4.</td>
<td><img src="/docker-hub/hub-images/gh_docker-service.png" alt="Activate Service Hooks"></td>
<td>Make sure the "Active" checkbox is selected and click the "Update service" button to save your changes.</td>
</tr>
</tbody>
</table>
## Automated Builds with Bitbucket
In order to setup an Automated Build, you need to first link your
[Docker Hub](https://hub.docker.com) account with a Bitbucket account.
This will allow the registry to see your repositories.
To get started, log into your Docker Hub account and click the
"+ Add Repository" button at the upper right of the screen. Then
select [Automated Build](https://registry.hub.docker.com/builds/add/).
Select the [Bitbucket source](
https://registry.hub.docker.com/associate/bitbucket/).
Then follow the onscreen instructions to authorize and link your
Bitbucket account to Docker Hub. Once it is linked, you'll be able
to choose a repository from which to create the Automatic Build.
### Creating an Automated Build
You can [create an Automated Build](
https://registry.hub.docker.com/builds/bitbucket/select/) from any of your
public or private Bitbucket repositories with a `Dockerfile`.
### Adding a Hook
When you link your Docker Hub account, a `POST` hook should get automatically
added to your Bitbucket repository. Follow the steps below to confirm or modify the
Bitbucket hooks for your Automated Build:
<table class="table table-bordered">
<thead>
<tr>
<th>Step</th>
<th>Screenshot</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>1.</td>
<td><img src="/docker-hub/hub-images/bb_menu.png" alt="Settings" width="180"></td>
<td>Log in to Bitbucket.org and go to your Repository page. Click on "Settings" on
the far left side of the page, under "Navigation". You must have admin privileges
to the repository in order to do this.</td>
</tr>
<tr>
<td>2.</td>
<td><img src="/docker-hub/hub-images/bb_hooks.png" alt="Hooks" width="180"></td>
<td>Click on "Hooks" on the near left side of the page, under "Settings".</td></tr>
<tr>
<td>3.</td>
<td><img src="/docker-hub/hub-images/bb_post-hook.png" alt="Docker Post Hook"></td><td>You should now see a list of hooks associated with the repo, including a <code>POST</code> hook that points at
registry.hub.docker.com/hooks/bitbucket.</td>
</tr>
</tbody>
</table>
## The Dockerfile and Automated Builds
During the build process, Docker will copy the contents of your `Dockerfile`.
It will also add it to the [Docker Hub](https://hub.docker.com) for the Docker
community (for public repositories) or approved team members/orgs (for private
repositories) to see on the repository page.
### README.md
If you have a `README.md` file in your repository, it will be used as the
repository's full description.The build process will look for a
`README.md` in the same directory as your `Dockerfile`.
> **Warning:**
> If you change the full description after a build, it will be
> rewritten the next time the Automated Build has been built. To make changes,
> modify the `README.md` from the Git repository.
## Remote Build triggers
If you need a way to trigger Automated Builds outside of GitHub or Bitbucket,
you can set up a build trigger. When you turn on the build trigger for an
Automated Build, it will give you a URL to which you can send POST requests.
This will trigger the Automated Build, much as with a GitHub webhook.
Build triggers are available under the Settings menu of each Automated Build
repository on the Docker Hub.
![Build trigger screen](/docker-hub/hub-images/build-trigger.png)
You can use `curl` to trigger a build:
```
$ curl --data "build=true" -X POST https://registry.hub.docker.com/u/svendowideit/testhook/trigger/be579c
82-7c0e-11e4-81c4-0242ac110020/
OK
```
> **Note:**
> You can only trigger one build at a time and no more than one
> every five minutes. If you already have a build pending, or if you
> recently submitted a build request, those requests *will be ignored*.
> To verify everything is working correctly, check the logs of last
> ten triggers on the settings page .
## Webhooks
Automated Builds also include a Webhooks feature. Webhooks can be called
after a successful repository push is made. This includes when a new tag is added
to an existing image.
The webhook call will generate a HTTP POST with the following JSON
payload:
```
{
"callback_url": "https://registry.hub.docker.com/u/svendowideit/testhook/hook/2141b5bi5i5b02bec211i4eeih0242eg11000a/",
"push_data": {
"images": [
"27d47432a69bca5f2700e4dff7de0388ed65f9d3fb1ec645e2bc24c223dc1cc3",
"51a9c7c1f8bb2fa19bcd09789a34e63f35abb80044bc10196e304f6634cc582c",
...
],
"pushed_at": 1.417566161e+09,
"pusher": "trustedbuilder"
},
"repository": {
"comment_count": 0,
"date_created": 1.417494799e+09,
"description": "",
"dockerfile": "#\n# BUILD\u0009\u0009docker build -t svendowideit/apt-cacher .\n# RUN\u0009\u0009docker run -d -p 3142:3142 -name apt-cacher-run apt-cacher\n#\n# and then you can run containers with:\n# \u0009\u0009docker run -t -i -rm -e http_proxy http://192.168.1.2:3142/ debian bash\n#\nFROM\u0009\u0009ubuntu\nMAINTAINER\u0009SvenDowideit@home.org.au\n\n\nVOLUME\u0009\u0009[\"/var/cache/apt-cacher-ng\"]\nRUN\u0009\u0009apt-get update ; apt-get install -yq apt-cacher-ng\n\nEXPOSE \u0009\u00093142\nCMD\u0009\u0009chmod 777 /var/cache/apt-cacher-ng ; /etc/init.d/apt-cacher-ng start ; tail -f /var/log/apt-cacher-ng/*\n",
"full_description": "Docker Hub based automated build from a GitHub repo",
"is_official": false,
"is_private": true,
"is_trusted": true,
"name": "testhook",
"namespace": "svendowideit",
"owner": "svendowideit",
"repo_name": "svendowideit/testhook",
"repo_url": "https://registry.hub.docker.com/u/svendowideit/testhook/",
"star_count": 0,
"status": "Active"
}
}
```
Webhooks are available under the Settings menu of each Repository.
Use a tool like [requestb.in](http://requestb.in/) to test your webhook.
> **Note**: The Docker Hub servers use an elastic IP range, so you can't
> filter requests by IP.
### Webhook chains
Webhook chains allow you to chain calls to multiple services. For example,
you can use this to trigger a deployment of your container only after
it has been successfully tested, then update a separate Changelog once the
deployment is complete.
After clicking the "Add webhook" button, simply add as many URLs as necessary
in your chain.
The first webhook in a chain will be called after a successful push. Subsequent
URLs will be contacted after the callback has been validated.
### Validating a callback
In order 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 will only be 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 will be interrupted.
* `description`: A string containing miscellaneous information that will be
available on the 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"
}
## Repository links
Repository links are a way to associate one Automated Build with
another. If one gets updated, the linking system triggers a rebuild
for the other Automated Build. This makes it easy to keep all your
Automated Builds up to date.
To add a link, go to the repository for the Automated Build you want to
link to and click on *Repository Links* under the Settings menu at
right. Then, enter the name of the repository that you want have linked.
> **Warning:**
> You can add more than one repository link, however, you should
> do so very carefully. Creating a two way relationship between Automated Builds will
> cause an endless build loop.

20
docs/docker-hub/home.md
View file

@ -1,20 +0,0 @@
<!--[metadata]>
+++
draft = true
title = "The Docker Hub Registry help"
description = "The Docker Registry help documentation home"
keywords = ["Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, docs, documentation"]
[menu.main]
parent = "smn_pubhub"
+++
<![end-metadata]-->
# The Docker Hub Registry help
## Introduction
For your questions about the [Docker Hub](https://hub.docker.com) registry you
can use [this documentation](docs.md).
If you can not find something you are looking for, please feel free to
[contact us](https://docker.com/resources/support/).

BIN
docs/docker-hub/hub-images/bb_hooks.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 18 KiB

BIN
docs/docker-hub/hub-images/bb_menu.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 16 KiB

BIN
docs/docker-hub/hub-images/bb_post-hook.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 16 KiB

BIN
docs/docker-hub/hub-images/build-trigger.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 18 KiB

BIN
docs/docker-hub/hub-images/dashboard.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 52 KiB

BIN
docs/docker-hub/hub-images/deploy_key.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 47 KiB

BIN
docs/docker-hub/hub-images/gh-check-admin-org-dh-app-access.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 31 KiB

BIN
docs/docker-hub/hub-images/gh-check-user-org-dh-app-access.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 19 KiB

BIN
docs/docker-hub/hub-images/gh_add_ssh_user_key.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 21 KiB

BIN
docs/docker-hub/hub-images/gh_docker-service.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 40 KiB

BIN
docs/docker-hub/hub-images/gh_menu.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 5.5 KiB

BIN
docs/docker-hub/hub-images/gh_org_members.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 26 KiB

BIN
docs/docker-hub/hub-images/gh_repo_deploy_key.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 32 KiB

BIN
docs/docker-hub/hub-images/gh_service_hook.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 19 KiB

BIN
docs/docker-hub/hub-images/gh_settings.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 4.7 KiB

BIN
docs/docker-hub/hub-images/gh_team_members.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 35 KiB

BIN
docs/docker-hub/hub-images/groups.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 28 KiB

BIN
docs/docker-hub/hub-images/hub.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 30 KiB

BIN
docs/docker-hub/hub-images/invite.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 18 KiB

BIN
docs/docker-hub/hub-images/org-repo-collaborators.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 13 KiB

BIN
docs/docker-hub/hub-images/orgs.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 20 KiB

BIN
docs/docker-hub/hub-images/repos.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 28 KiB

38
docs/docker-hub/index.md
View file

@ -1,38 +0,0 @@
<!--[metadata]>
+++
title = "The Docker Hub"
description = "The Docker Help documentation home"
keywords = ["Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, docs, documentation, accounts, organizations, repositories, groups"]
[menu.main]
parent = "smn_pubhub"
+++
<![end-metadata]-->
# Docker Hub
The [Docker Hub](https://hub.docker.com) provides a cloud-based platform service
for distributed applications, including container image distribution and change
management, user and team collaboration, and lifecycle workflow automation.
![DockerHub](/docker-hub/hub-images/hub.png)
## [Finding and pulling images](./userguide.md)
Find out how to [use the Docker Hub](./userguide.md) to find and pull Docker
images to run or build upon.
## [Accounts](./accounts.md)
[Learn how to create](./accounts.md) a Docker Hub
account and manage your organizations and groups.
## [Your Repositories](./repos.md)
Find out how to share your Docker images in [Docker Hub
repositories](./repos.md) and how to store and manage private images.
## [Automated builds](./builds.md)
Learn how to automate your build and deploy pipeline with [Automated
Builds](./builds.md)

113
docs/docker-hub/official_repos.md
View file

@ -1,113 +0,0 @@
<!--[metadata]>
+++
title = "Official Repositories on Docker Hub"
description = "Guidelines for Official Repositories on Docker Hub"
keywords = ["Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, docs, official, image, documentation"]
[menu.main]
parent = "smn_pubhub"
weight = 4
+++
<![end-metadata]-->
# Official Repositories on Docker Hub
The Docker [Official Repositories](http://registry.hub.docker.com/official) are
a curated set of Docker repositories that are promoted on Docker Hub. They are
designed to:
* Provide essential base OS repositories (for example,
[`ubuntu`](https://registry.hub.docker.com/_/ubuntu/),
[`centos`](https://registry.hub.docker.com/_/centos/)) that serve as the
starting point for the majority of users.
* Provide drop-in solutions for popular programming language runtimes, data
stores, and other services, similar to what a Platform-as-a-Service (PAAS)
would offer.
* Exemplify [`Dockerfile` best practices](/articles/dockerfile_best-practices)
and provide clear documentation to serve as a reference for other `Dockerfile`
authors.
* Ensure that security updates are applied in a timely manner. This is
particularly important as many Official Repositories are some of the most
popular on Docker Hub.
* Provide a channel for software vendors to redistribute up-to-date and
supported versions of their products. Organization accounts on Docker Hub can
also serve this purpose, without the careful review or restrictions on what
can be published.
Docker, Inc. sponsors a dedicated team that is responsible for reviewing and
publishing all Official Repositories content. This team works in collaboration
with upstream software maintainers, security experts, and the broader Docker
community.
While it is preferable to have upstream software authors maintaining their
corresponding Official Repositories, this is not a strict requirement. Creating
and maintaining images for Official Repositories is a public process. It takes
place openly on GitHub where participation is encouraged. Anyone can provide
feedback, contribute code, suggest process changes, or even propose a new
Official Repository.
## Should I use Official Repositories?
New Docker users are encouraged to use the Official Repositories in their
projects. These repositories have clear documentation, promote best practices,
and are designed for the most common use cases. Advanced users are encouraged to
review the Official Repositories as part of their `Dockerfile` learning process.
A common rationale for diverging from Official Repositories is to optimize for
image size. For instance, many of the programming language stack images contain
a complete build toolchain to support installation of modules that depend on
optimized code. An advanced user could build a custom image with just the
necessary pre-compiled libraries to save space.
A number of language stacks such as
[`python`](https://registry.hub.docker.com/_/python/) and
[`ruby`](https://registry.hub.docker.com/_/ruby/) have `-slim` tag variants
designed to fill the need for optimization. Even when these "slim" variants are
insufficient, it is still recommended to inherit from an Official Repository
base OS image to leverage the ongoing maintenance work, rather than duplicating
these efforts.
## How can I get involved?
All Official Repositories contain a **User Feedback** section in their
documentation which covers the details for that specific repository. In most
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 Repository?
From a high level, an Official Repository starts out as a proposal in the form
of a set of GitHub pull requests. You'll find detailed and objective proposal
requirements in the following GitHub repositories:
* [docker-library/official-images](https://github.com/docker-library/official-images)
* [docker-library/docs](https://github.com/docker-library/docs)
The Official Repositories team, with help from community contributors, formally
review each proposal and provide feedback to the author. This initial review
process may require a bit of back and forth before the proposal is accepted.
There are also subjective considerations during the review process. These
subjective concerns boil down to the basic question: "is this image generally
useful?" For example, the [`python`](https://registry.hub.docker.com/_/python/)
Official Repository is "generally useful" to the large Python developer
community, whereas an obscure text adventure game written in Python last week is
not.
When a new proposal is accepted, the author becomes responsible for keeping
their images up-to-date and responding to user feedback. The Official
Repositories team becomes responsible for publishing the images and
documentation on Docker Hub. Updates to the Official Repository follow the same
pull request process, though with less review. The Official Repositories team
ultimately acts as a gatekeeper for all changes, which helps mitigate the risk
of quality and security issues from being introduced.
> **Note**: If you are interested in proposing an Official Repository, but would
> like to discuss it with Docker, Inc. privately first, please send your
> inquiries to partners@docker.com. There is no fast-track or pay-for-status
> option.

193
docs/docker-hub/repos.md
View file

@ -1,193 +0,0 @@
<!--[metadata]>
+++
title = "Your Repositories on Docker Hub"
description = "Your Repositories on Docker Hub"
keywords = ["Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, webhooks, docs, documentation"]
[menu.main]
parent = "smn_pubhub"
weight = 2
+++
<![end-metadata]-->
# Your Hub repositories
Docker Hub repositories make it possible for you to share images with co-workers,
customers or the Docker community at large. If you're building your images internally,
either on your own Docker daemon, or using your own Continuous integration services,
you can push them to a Docker Hub repository that you add to your Docker Hub user or
organization account.
Alternatively, if the source code for your Docker image is on GitHub or Bitbucket,
you can use an "Automated build" repository, which is built by the Docker Hub
services. See the [automated builds documentation](./builds.md) to read about
the extra functionality provided by those services.
![repositories](/docker-hub/hub-images/repos.png)
Your Docker Hub repositories have a number of useful features.
## Stars
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 will not be 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 groups. For more information
see the [accounts documentation](accounts/).
## 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 group.
To work with a private repository on [Docker
Hub](https://hub.docker.com), you will need to add one via the [Add
Repository](https://registry.hub.docker.com/account/repositories/add/)
link. You get one private repository for free with your Docker Hub
account. If you need more accounts you can upgrade your [Docker
Hub](https://registry.hub.docker.com/plans/) plan.
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.
It is possible to give access to a private repository to those whom you
designate (i.e., collaborators) from its Settings page. From there, you
can also switch repository status (*public* to *private*, or
vice-versa). You will need to have an available private repository slot
open before you can do such a switch. If you don't have any available,
you can always upgrade your [Docker
Hub](https://registry.hub.docker.com/plans/) plan.
## Webhooks
A webhook is an HTTP call-back triggered by a specific event.
You can use a Hub repository webhook to notify people, services, and other
applications after a new image is pushed to your repository (this also happens
for Automated builds). For example, you can trigger an automated test or
deployment to happen as soon as the image is available.
To get started adding webhooks, go to the desired repository in the Hub,
and click "Webhooks" under the "Settings" box.
A webhook is called only after a successful `push` is
made. The webhook calls are HTTP POST requests with a JSON payload
similar to the example shown below.
*Example webhook JSON payload:*
```
{
"callback_url": "https://registry.hub.docker.com/u/svendowideit/busybox/hook/2141bc0cdec4hebec411i4c1g40242eg110020/",
"push_data": {
"images": [
"27d47432a69bca5f2700e4dff7de0388ed65f9d3fb1ec645e2bc24c223dc1cc3",
"51a9c7c1f8bb2fa19bcd09789a34e63f35abb80044bc10196e304f6634cc582c",
...
],
"pushed_at": 1.417566822e+09,
"pusher": "svendowideit"
},
"repository": {
"comment_count": 0,
"date_created": 1.417566665e+09,
"description": "",
"full_description": "webhook triggered from a 'docker push'",
"is_official": false,
"is_private": false,
"is_trusted": false,
"name": "busybox",
"namespace": "svendowideit",
"owner": "svendowideit",
"repo_name": "svendowideit/busybox",
"repo_url": "https://registry.hub.docker.com/u/svendowideit/busybox/",
"star_count": 0,
"status": "Active"
}
```
<TODO: does it tell you what tag was updated?>
For testing, you can try an HTTP request tool like [requestb.in](http://requestb.in/).
> **Note**: The Docker Hub servers use an elastic IP range, so you can't
> filter requests by IP.
### Webhook chains
Webhook chains allow you to chain calls to multiple services. For example,
you can use this to trigger a deployment of your container only after
it has been successfully tested, then update a separate Changelog once the
deployment is complete.
After clicking the "Add webhook" button, simply add as many URLs as necessary
in your chain.
The first webhook in a chain will be called after a successful push. Subsequent
URLs will be contacted after the callback has been validated.
### Validating a callback
In order 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 will only be 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 will be interrupted.
* `description`: A string containing miscellaneous information that will be
available on the 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"
}
## Mark as unlisted
By marking a repository as unlisted, you can create a publicly pullable repository
which will not be in the Hub or commandline search. This allows you to have a limited
release, but does not restrict access to anyone that is told, or guesses the repository
name.

63
docs/docker-hub/userguide.md
View file

@ -1,63 +0,0 @@
<!--[metadata]>
+++
title = "Docker Hub user guide"
description = "Docker Hub user guide"
keywords = ["Docker, docker, registry, Docker Hub, docs, documentation"]
[menu.main]
parent = "smn_pubhub"
+++
<![end-metadata]-->
# Using the Docker Hub
Docker Hub is used to find and pull Docker images to run or build upon, and to
distribute and build images for other users to use.
![your profile](/docker-hub/hub-images/dashboard.png)
## Finding repositories and images
There are two ways you can search for public repositories and images available
on the Docker Hub. You can use the "Search" tool on the Docker Hub website, or
you can `search` for all the repositories and images using the Docker commandline
tool:
$ docker search ubuntu
Both will show you a list of the currently available public repositories on the
Docker Hub which match the provided keyword.
If a repository is private or marked as unlisted, it won't be in the repository
search results. To see all the repositories you have access to and their statuses,
you can look at your profile page on [Docker Hub](https://hub.docker.com).
## Pulling, running and building images
You can find more information on [working with Docker images](../userguide/dockerimages.md).
## Official Repositories
The Docker Hub contains a number of [Official
Repositories](http://registry.hub.docker.com/official). These are
certified repositories from vendors and contributors to Docker. They
contain Docker images from vendors like Canonical, Oracle, and Red Hat
that you can use to build applications and services.
If you use Official Repositories you know you're using an optimized and
up-to-date image to power your applications.
> **Note:**
> If you would like to contribute an Official Repository for your
> organization, see [Official Repositories on Docker
> Hub](/docker-hub/official_repos) for more information.
## Building and shipping your own repositories and images
The Docker Hub provides you and your team with a place to build and ship Docker images.
Collections of Docker images are managed using repositories -
You can configure two types of repositories to manage on the Docker Hub:
[Repositories](./repos.md), which allow you to push images to the Hub from your local Docker daemon,
and [Automated Builds](./builds.md), which allow you to configure GitHub or Bitbucket to
trigger the Hub to rebuild repositories when changes are made to the repository.

78
docs/userguide/dockerhub.md
View file

@ -1,78 +0,0 @@
<!--[metadata]>
+++
title = "Getting started with Docker Hub"
description = "Introductory guide to getting an account on Docker Hub"
keywords = ["documentation, docs, the docker guide, docker guide, docker, docker platform, virtualization framework, docker.io, central service, services, how to, container, containers, automation, collaboration, collaborators, registry, repo, repository, technology, github webhooks, trusted builds"]
[menu.main]
parent = "smn_pubhub"
weight = 1
+++
<![end-metadata]-->
# Getting started with Docker Hub
This section provides a quick introduction to the [Docker Hub](https://hub.docker.com),
including how to create an account.
The [Docker Hub](https://hub.docker.com) is a centralized resource for working with
Docker and its components. Docker Hub helps you collaborate with colleagues and get the
most out of Docker. To do this, it provides services such as:
* Docker image hosting.
* User authentication.
* Automated image builds and work-flow tools such as build triggers and web
hooks.
* Integration with GitHub and Bitbucket.
In order to use Docker Hub, you will first need to register and create an account. Don't
worry, creating an account is simple and free.
## Creating a Docker Hub account
There are two ways for you to register and create an account:
1. Via the web, or
2. Via the command line.
### Register via the web
Fill in the [sign-up form](https://hub.docker.com/account/signup/) by
choosing your user name and password and entering a valid email address. You can also
sign up for the Docker Weekly mailing list, which has lots of information about what's
going on in the world of Docker.
![Register using the sign-up page](/userguide/register-web.png)
### Register via the command line
You can also create a Docker Hub account via the command line with the
`docker login` command.
$ docker login
### Confirm your email
Once you've filled in the form, check your email for a welcome message asking for
confirmation so we can activate your account.
### Login
After you complete the confirmation process, you can login using the web console:
![Login using the web console](/userguide/login-web.png)
Or via the command line with the `docker login` command:
$ docker login
Your Docker Hub account is now active and ready to use.
## Next steps
Next, let's start learning how to Dockerize applications with our "Hello world"
exercise.
Go to [Dockerizing Applications](/userguide/dockerizing).

3
docs/userguide/dockerrepos.md
View file

@ -82,8 +82,7 @@ You now have an image from which you can run containers.
Anyone can pull public images from the [Docker Hub](https://hub.docker.com)
registry, but if you would like to share your own images, then you must
register first, as we saw in the [first section of the Docker User
Guide](/userguide/dockerhub/).
[register first](/docker-hub/accounts).
## Pushing a repository to Docker Hub

2
docs/userguide/index.md
View file

@ -33,7 +33,7 @@ Docker Hub is the central hub for Docker. It hosts public Docker images
and provides services to help you build and manage your Docker
environment. To learn more:
Go to [Using Docker Hub](/userguide/dockerhub).
Go to [Using Docker Hub](/docker-hub).
## Dockerizing applications: A "Hello world"