diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 000000000..f4542f3a4
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,59 @@
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+on:
+ push:
+ branches:
+ - main
+ paths:
+ - docs/**
+ workflow_dispatch:
+
+jobs:
+ # Build job
+ build:
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ # Build the site and upload artifacts using actions/upload-pages-artifact
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@v2
+ - name: Build docs
+ uses: docker/bake-action@v3
+ with:
+ files: |
+ docker-bake.hcl
+ targets: docs-export
+ set: |
+ *.cache-from=type=gha,scope=docs
+ *.cache-to=type=gha,scope=docs,mode=max
+ - name: Upload Pages artifact
+ uses: actions/upload-pages-artifact@v2
+ with:
+ path: ./build/docs
+
+ # Deploy job
+ deploy:
+ # Add a dependency to the build job
+ needs: build
+
+ # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+ permissions:
+ pages: write # to deploy to Pages
+ id-token: write # to verify the deployment originates from an appropriate source
+
+ # Deploy to the github-pages environment
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+
+ # Specify runner + deployment step
+ runs-on: ubuntu-latest
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v2 # or the latest "vX.X.X" version tag for this action
diff --git a/.gitignore b/.gitignore
index dcda068a6..45fc33b19 100644
--- a/.gitignore
+++ b/.gitignore
@@ -38,3 +38,8 @@ bin/*
.idea/*
tests/miniodata
+
+# Docs
+**/.hugo_build.lock
+docs/resources
+docs/public
diff --git a/BUILDING.md b/BUILDING.md
index aa1bcff00..8e3cf3d40 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -7,7 +7,7 @@ This is useful if you intend to actively work on the registry.
### Alternatives
-Most people should use the [official Registry docker image](https://hub.docker.com/r/library/registry/).
+Most people should use prebuilt images, for example, the [Registry docker image](https://hub.docker.com/r/library/registry/) provided by Docker.
People looking for advanced operational use cases might consider rolling their own image with a custom Dockerfile inheriting `FROM registry:2`.
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
index bd40c44af..17067f7a8 100644
--- a/GOVERNANCE.md
+++ b/GOVERNANCE.md
@@ -94,7 +94,7 @@ performance must not be discussed on the pull request.
## How are decisions made?
-Docker distribution is an open-source project with an open design philosophy.
+CNCF distribution is an open-source project with an open design philosophy.
This means that the repository is the source of truth for EVERY aspect of the
project, including its philosophy, design, road map, and APIs. *If it's part of
the project, it's in the repo. If it's in the repo, it's part of the project.*
diff --git a/README.md b/README.md
index 01c3da29d..01563cde5 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
The toolset to pack, ship, store, and deliver content.
This repository's main product is the Open Source Registry implementation
-for storing and distributing container images using the
+for storing and distributing container images and other content using the
[OCI Distribution Specification](https://github.com/opencontainers/distribution-spec).
The goal of this project is to provide a simple, secure, and scalable base
for building a large scale registry solution or running a simple private registry.
diff --git a/doc.go b/doc.go
index bdd8cb708..d28c892df 100644
--- a/doc.go
+++ b/doc.go
@@ -1,6 +1,6 @@
// Package distribution will define the interfaces for the components of
// docker distribution. The goal is to allow users to reliably package, ship
-// and store content related to docker images.
+// and store content related to container images.
//
// This is currently a work in progress. More details are available in the
// README.md.
diff --git a/docker-bake.hcl b/docker-bake.hcl
index db9fa1f51..2b7f25d6c 100644
--- a/docker-bake.hcl
+++ b/docker-bake.hcl
@@ -94,3 +94,26 @@ target "image-all" {
"linux/s390x"
]
}
+
+target "_common_docs" {
+ dockerfile = "./dockerfiles/docs.Dockerfile"
+}
+
+target "docs-export" {
+ inherits = ["_common_docs"]
+ target = "out"
+ output = ["type=local,dest=build/docs"]
+}
+
+target "docs-image" {
+ inherits = ["_common_docs"]
+ target = "server"
+ output = ["type=docker"]
+ tags = ["registry-docs:local"]
+}
+
+target "docs-test" {
+ inherits = ["_common_docs"]
+ target = "test"
+ output = ["type=cacheonly"]
+}
diff --git a/dockerfiles/docs.Dockerfile b/dockerfiles/docs.Dockerfile
new file mode 100644
index 000000000..4d351b699
--- /dev/null
+++ b/dockerfiles/docs.Dockerfile
@@ -0,0 +1,35 @@
+# syntax=docker/dockerfile:1
+
+ARG GO_VERSION=1.20.8
+ARG ALPINE_VERSION=3.18
+
+FROM golang:${GO_VERSION}-alpine${ALPINE_VERSION} AS base
+RUN apk add --no-cache git
+
+FROM base AS hugo
+ARG HUGO_VERSION=0.119.0
+RUN --mount=type=cache,target=/go/mod/pkg \
+ go install github.com/gohugoio/hugo@v${HUGO_VERSION}
+
+FROM base AS build-base
+COPY --from=hugo $GOPATH/bin/hugo /bin/hugo
+WORKDIR /src
+
+FROM build-base AS build
+RUN --mount=type=bind,rw,source=docs,target=. \
+ hugo --gc --minify --destination /out
+
+FROM build-base AS server
+COPY docs .
+ENTRYPOINT [ "hugo", "server", "--bind", "0.0.0.0" ]
+EXPOSE 1313
+
+FROM scratch AS out
+COPY --from=build /out /
+
+FROM wjdp/htmltest:v0.17.0 AS test
+WORKDIR /test
+COPY --from=build /out ./public
+ADD docs/.htmltest.yml .htmltest.yml
+RUN --mount=type=cache,target=tmp/.htmltest \
+ htmltest
diff --git a/docs/.htmltest.yml b/docs/.htmltest.yml
new file mode 100644
index 000000000..d02699b4a
--- /dev/null
+++ b/docs/.htmltest.yml
@@ -0,0 +1,9 @@
+DirectoryPath: "public"
+EnforceHTTPS: true
+CheckDoctype: true
+CheckExternal: true
+IgnoreAltMissing: true
+IgnoreAltEmpty: true
+IgnoreEmptyHref: true
+IgnoreInternalEmptyHash: true
+IgnoreDirectoryMissingTrailingSlash: true
diff --git a/docs/content/_index.md b/docs/content/_index.md
new file mode 100644
index 000000000..3e86bc417
--- /dev/null
+++ b/docs/content/_index.md
@@ -0,0 +1,77 @@
+---
+description: High-level overview of the Registry
+keywords: registry, on-prem, images, tags, repository, distribution
+title: Distribution Registry
+---
+
+## What it is
+
+The Registry is a stateless, highly scalable server side application that stores
+and lets you distribute container images and other content. The Registry is open-source, under the
+permissive [Apache license](https://en.wikipedia.org/wiki/Apache_License).
+
+## Why use it
+
+You should use the Registry if you want to:
+
+ * tightly control where your images are being stored
+ * fully own your images distribution pipeline
+ * integrate image storage and distribution tightly into your in-house development workflow
+
+## Alternatives
+
+Users looking for a zero maintenance, ready-to-go solution are encouraged to
+use one of the existing registry services. Many of these provide support and security
+scanning, and are free for public repositories. For example:
+- [Docker Hub](https://hub.docker.com)
+- [Quay.io](https://quay.io/)
+- [GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)
+
+Cloud infrastructure providers such as [AWS](https://aws.amazon.com/ecr/), [Azure](https://azure.microsoft.com/products/container-registry/), [Google Cloud](https://cloud.google.com/artifact-registry) and [IBM Cloud](https://www.ibm.com/products/container-registry) also have container registry services available at a cost.
+
+## Compatibility
+
+The distribution registry implements the [OCI Distribution Spec](https://github.com/opencontainers/distribution-spec) version 1.0.1.
+
+## Basic commands
+
+Start your registry
+
+```sh
+docker run -d -p 5000:5000 --name registry registry:2
+```
+
+Pull (or build) some image from the hub
+
+```sh
+docker pull ubuntu
+```
+
+Tag the image so that it points to your registry
+
+```sh
+docker image tag ubuntu localhost:5000/myfirstimage
+```
+
+Push it
+
+```sh
+docker push localhost:5000/myfirstimage
+```
+
+Pull it back
+
+```sh
+docker pull localhost:5000/myfirstimage
+```
+
+Now stop your registry and remove all data
+
+```sh
+docker container stop registry && docker container rm -v registry
+```
+
+## Next
+
+You should now read the [detailed introduction about the registry](about),
+or jump directly to [deployment instructions](about/deploying).
diff --git a/docs/introduction.md b/docs/content/about/_index.md
similarity index 88%
rename from docs/introduction.md
rename to docs/content/about/_index.md
index 6fd5aa155..d556d9bba 100644
--- a/docs/introduction.md
+++ b/docs/content/about/_index.md
@@ -4,12 +4,12 @@ keywords: registry, on-prem, images, tags, repository, distribution, use cases,
title: About Registry
---
-A registry is a storage and content delivery system, holding named Docker
-images, available in different tagged versions.
+A registry is a storage and content delivery system, holding named container
+images and other content, available in different tagged versions.
> Example: the image `distribution/registry`, with tags `2.0` and `2.1`.
-Users interact with a registry by using docker push and pull commands.
+Users interact with a registry by pushing and pulling images.
> Example: `docker pull registry-1.docker.io/distribution/registry:2.1`.
@@ -27,7 +27,7 @@ The Registry GitHub repository includes additional information about advanced
authentication and authorization methods. Only very large or public deployments
are expected to extend the Registry in this way.
-Finally, the Registry ships with a robust [notification system](notifications.md),
+Finally, the Registry ships with a robust [notification system](notifications),
calling webhooks in response to activity, and both extensive logging and reporting,
mostly useful for large installations that want to collect metrics.
@@ -35,11 +35,11 @@ mostly useful for large installations that want to collect metrics.
Image names as used in typical docker commands reflect their origin:
- * `docker pull ubuntu` instructs docker to pull an image named `ubuntu` from the official Docker Hub. This is simply a shortcut for the longer `docker pull docker.io/library/ubuntu` command
+ * `docker pull ubuntu` instructs docker to pull an image named `ubuntu` from Docker Hub. This is simply a shortcut for the longer `docker pull docker.io/library/ubuntu` command
* `docker pull myregistrydomain:port/foo/bar` instructs docker to contact the registry located at `myregistrydomain:port` to find the image `foo/bar`
You can find out more about the various Docker commands dealing with images in
-the [official Docker engine documentation](../engine/reference/commandline/cli.md).
+the [Docker engine documentation](https://docs.docker.com/engine/reference/commandline/cli/).
## Use cases
@@ -70,4 +70,4 @@ golang are certainly useful as well for advanced operations or hacking.
## Next
-Dive into [deploying your registry](deploying.md)
+Dive into [deploying your registry](deploying)
diff --git a/docs/architecture.md b/docs/content/about/architecture.md
similarity index 99%
rename from docs/architecture.md
rename to docs/content/about/architecture.md
index c2aaa9f2d..91b704f8c 100644
--- a/docs/architecture.md
+++ b/docs/content/about/architecture.md
@@ -1,5 +1,5 @@
---
-published: false
+draft: true
---
# Architecture
diff --git a/docs/compatibility.md b/docs/content/about/compatibility.md
similarity index 97%
rename from docs/compatibility.md
rename to docs/content/about/compatibility.md
index 6462b5579..d12845b8d 100644
--- a/docs/compatibility.md
+++ b/docs/content/about/compatibility.md
@@ -5,13 +5,14 @@ title: Registry compatibility
---
## Synopsis
+
If a manifest is pulled by _digest_ from a registry 2.3 with Docker Engine 1.9
and older, and the manifest was pushed with Docker Engine 1.10, a security check
causes the Engine to receive a manifest it cannot use and the pull fails.
## Registry manifest support
-Historically, the registry has supported a [single manifest type](./spec/manifest-v2-1.md)
+Historically, the registry has supported a single manifest type
known as _Schema 1_.
With the move toward multiple architecture images, the distribution project
@@ -23,7 +24,6 @@ preserve compatibility with older versions of Docker Engine.
This conversion has some implications for pulling manifests by digest and this
document enumerates these implications.
-
## Content Addressable Storage (CAS)
Manifests are stored and retrieved in the registry by keying off a digest
@@ -42,7 +42,6 @@ attempts to send a _Schema 2_ manifest, falling back to sending a
Schema 1 type manifest when it detects that the registry does not
support the new version.
-
## Registry v2.3
### Manifest push with Docker 1.10
@@ -75,4 +74,3 @@ registry persists to disk.
When the manifest is pulled by digest or tag with any Docker version, a
_Schema 1_ manifest is returned.
-
diff --git a/docs/configuration.md b/docs/content/about/configuration.md
similarity index 96%
rename from docs/configuration.md
rename to docs/content/about/configuration.md
index 52edfa4a6..3f4cb18e3 100644
--- a/docs/configuration.md
+++ b/docs/content/about/configuration.md
@@ -10,7 +10,7 @@ before moving your systems to production.
## Override specific configuration options
-In a typical setup where you run your Registry from the official image, you can
+In a typical setup where you run your registry as a container, you can
specify a configuration variable from the environment by passing `-e` arguments
to your `docker run` stanza or from within a Dockerfile using the `ENV`
instruction.
@@ -20,7 +20,7 @@ To override a configuration option, create an environment variable named
and the `_` (underscore) represents indention levels. For example, you can
configure the `rootdirectory` of the `filesystem` storage backend:
-```none
+```yaml
storage:
filesystem:
rootdirectory: /var/lib/registry
@@ -28,7 +28,7 @@ storage:
To override this value, set an environment variable like this:
-```none
+```sh
REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere
```
@@ -64,7 +64,7 @@ These are all configuration options for the registry. Some options in the list
are mutually exclusive. Read the detailed reference information about each
option before finalizing your configuration.
-```none
+```yaml
version: 0.1
log:
accesslog:
@@ -293,7 +293,7 @@ the children marked **required**.
## `version`
-```none
+```yaml
version: 0.1
```
@@ -307,7 +307,7 @@ The `log` subsection configures the behavior of the logging system. The logging
system outputs everything to stderr. You can adjust the granularity and format
with this configuration section.
-```none
+```yaml
log:
accesslog:
disabled: true
@@ -326,7 +326,7 @@ log:
### `accesslog`
-```none
+```yaml
accesslog:
disabled: true
```
@@ -338,7 +338,7 @@ Access logging can be disabled by setting the boolean flag `disabled` to `true`.
## `hooks`
-```none
+```yaml
hooks:
- type: mail
levels:
@@ -362,7 +362,7 @@ Refer to `loglevel` to configure the level of messages printed.
> **DEPRECATED:** Please use [log](#log) instead.
-```none
+```yaml
loglevel: debug
```
@@ -371,7 +371,7 @@ Permitted values are `error`, `warn`, `info` and `debug`. The default is
## `storage`
-```none
+```yaml
storage:
filesystem:
rootdirectory: /var/lib/registry
@@ -436,15 +436,15 @@ returns an error. You can choose any of these backend storage drivers:
| Storage driver | Description |
|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `filesystem` | Uses the local disk to store registry files. It is ideal for development and may be appropriate for some small-scale production applications. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/filesystem.md). |
-| `azure` | Uses Microsoft Azure Blob Storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/azure.md). |
-| `gcs` | Uses Google Cloud Storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/gcs.md). |
-| `s3` | Uses Amazon Simple Storage Service (S3) and compatible Storage Services. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/s3.md). |
+| `filesystem` | Uses the local disk to store registry files. It is ideal for development and may be appropriate for some small-scale production applications. See the [driver's reference documentation](/storage-drivers/filesystem). |
+| `azure` | Uses Microsoft Azure Blob Storage. See the [driver's reference documentation](/storage-drivers/azure). |
+| `gcs` | Uses Google Cloud Storage. See the [driver's reference documentation](/storage-drivers/gcs). |
+| `s3` | Uses Amazon Simple Storage Service (S3) and compatible Storage Services. See the [driver's reference documentation](/storage-drivers/s3). |
For testing only, you can use the [`inmemory` storage
-driver](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/inmemory.md).
+driver](/storage-drivers/inmemory).
If you would like to run a registry from volatile memory, use the
-[`filesystem` driver](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/filesystem.md)
+[`filesystem` driver](/storage-drivers/filesystem)
on a ramdisk.
If you are deploying a registry on Windows, a Windows volume mounted from the
@@ -453,7 +453,7 @@ data-store. If you do use a Windows volume, the length of the `PATH` to
the mount point must be within the `MAX_PATH` limits (typically 255 characters),
or this error will occur:
-```none
+```text
mkdir /XXX protocol error and your registry will not function properly.
```
@@ -496,7 +496,7 @@ Use the `delete` structure to enable the deletion of image blobs and manifests
by digest. It defaults to false, but it can be enabled by writing the following
on the configuration file:
-```none
+```yaml
delete:
enabled: true
```
@@ -531,14 +531,14 @@ instance is aggressively caching.
To disable redirects, add a single flag `disable`, set to `true`
under the `redirect` section:
-```none
+```yaml
redirect:
disable: true
```
## `auth`
-```none
+```yaml
auth:
silly:
realm: silly-realm
@@ -593,7 +593,7 @@ security.
For more information about Token based authentication configuration, see the
-[specification](spec/auth/token.md).
+[specification](/spec/auth/token).
### `htpasswd`
@@ -601,7 +601,7 @@ The _htpasswd_ authentication backed allows you to configure basic
authentication using an
[Apache htpasswd file](https://httpd.apache.org/docs/2.4/programs/htpasswd.html).
The only supported password format is
-[`bcrypt`](http://en.wikipedia.org/wiki/Bcrypt). Entries with other hash types
+[`bcrypt`](https://en.wikipedia.org/wiki/Bcrypt). Entries with other hash types
are ignored. The `htpasswd` file is loaded once, at startup. If the file is
invalid, the registry will display an error and will not start.
@@ -629,7 +629,7 @@ object it is wrapping. For instance, a registry middleware must implement the
This is an example configuration of the `cloudfront` middleware, a storage
middleware:
-```none
+```yaml
middleware:
registry:
- name: ARegistryMiddleware
@@ -694,7 +694,7 @@ location of a proxy for the layer stored by the S3 storage driver.
## `http`
-```none
+```yaml
http:
addr: localhost:5000
net: tcp
@@ -834,7 +834,7 @@ to access proxy statistics. These statistics are exposed at `/debug/vars` in JSO
#### `prometheus`
-```none
+```yaml
prometheus:
enabled: true
path: /metrics
@@ -879,7 +879,7 @@ settings for the registry.
## `notifications`
-```none
+```yaml
notifications:
events:
includereferences: true
@@ -937,7 +937,7 @@ The `events` structure configures the information provided in event notification
## `redis`
-```none
+```yaml
redis:
addr: localhost:6379
password: asecret
@@ -974,7 +974,7 @@ registry does not set an expiration value on keys.
### `pool`
-```none
+```yaml
pool:
maxidle: 16
maxactive: 64
@@ -991,7 +991,7 @@ Use these settings to configure the behavior of the Redis connection pool.
### `tls`
-```none
+```yaml
tls:
enabled: false
```
@@ -1005,7 +1005,7 @@ Use these settings to configure Redis TLS.
## `health`
-```none
+```yaml
health:
storagedriver:
enabled: true
@@ -1090,7 +1090,7 @@ attempt fails, the health check will fail.
## `proxy`
-```
+```yaml
proxy:
remoteurl: https://registry-1.docker.io
username: [username]
@@ -1099,8 +1099,8 @@ proxy:
```
The `proxy` structure allows a registry to be configured as a pull-through cache
-to Docker Hub. See
-[mirror](https://github.com/docker/docker.github.io/tree/master/registry/recipes/mirror.md)
+to Docker Hub. See
+[mirror](/recipes/mirror)
for more information. Pushing to a registry configured as a pull-through cache
is unsupported.
@@ -1120,7 +1120,7 @@ username (such as `batman`) and the password for that username.
## `validation`
-```none
+```yaml
validation:
manifests:
urls:
@@ -1151,15 +1151,15 @@ If `allow` is unset, pushing a manifest containing URLs fails.
If `allow` is set, pushing a manifest succeeds only if all URLs match
one of the `allow` regular expressions **and** one of the following holds:
-1. `deny` is unset.
-2. `deny` is set but no URLs within the manifest match any of the `deny` regular
- expressions.
+1. `deny` is unset.
+2. `deny` is set but no URLs within the manifest match any of the `deny` regular
+ expressions.
## Example: Development configuration
You can use this simple example for local development:
-```none
+```yaml
version: 0.1
log:
level: debug
@@ -1183,10 +1183,9 @@ See
for another simple configuration. Both examples are generally useful for local
development.
-
## Example: Middleware configuration
-This example configures [Amazon Cloudfront](http://aws.amazon.com/cloudfront/)
+This example configures [Amazon Cloudfront](https://aws.amazon.com/cloudfront/)
as the storage middleware in a registry. Middleware allows the registry to serve
layers via a content delivery network (CDN). This reduces requests to the
storage layer.
@@ -1195,7 +1194,7 @@ Cloudfront requires the S3 storage driver.
This is the configuration expressed in YAML:
-```none
+```yaml
middleware:
storage:
- name: cloudfront
@@ -1210,6 +1209,8 @@ middleware:
See the configuration reference for [Cloudfront](#cloudfront) for more
information about configuration options.
-> **Note**: Cloudfront keys exist separately from other AWS keys. See
-> [the documentation on AWS credentials](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html)
-> for more information.
+{{< hint type=note >}}
+Cloudfront keys exist separately from other AWS keys. See
+[the documentation on AWS credentials](https://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html)
+for more information.
+{{< /hint >}}
diff --git a/docs/deploying.md b/docs/content/about/deploying.md
similarity index 69%
rename from docs/deploying.md
rename to docs/content/about/deploying.md
index 17ec308d9..1c022bc2e 100644
--- a/docs/deploying.md
+++ b/docs/content/about/deploying.md
@@ -9,7 +9,7 @@ A registry is an instance of the `registry` image, and runs within Docker.
This topic provides basic information about deploying and configuring a
registry. For an exhaustive list of configuration options, see the
-[configuration reference](configuration.md).
+[configuration reference](../configuration).
If you have an air-gapped datacenter, see
[Considerations for air-gapped registries](#considerations-for-air-gapped-registries).
@@ -27,7 +27,7 @@ The registry is now ready to use.
> **Warning**: These first few examples show registry configurations that are
> only appropriate for testing. A production-ready registry must be protected by
> TLS and should ideally use an access-control mechanism. Keep reading and then
-> continue to the [configuration guide](configuration.md) to deploy a
+> continue to the [configuration guide](../configuration) to deploy a
> production-ready registry.
## Copy an image from Docker Hub to your registry
@@ -38,40 +38,40 @@ as `my-ubuntu`, then pushes it to the local registry. Finally, the
`ubuntu:16.04` and `my-ubuntu` images are deleted locally and the
`my-ubuntu` image is pulled from the local registry.
-1. Pull the `ubuntu:16.04` image from Docker Hub.
+1. Pull the `ubuntu:16.04` image from Docker Hub.
- ```console
- $ docker pull ubuntu:16.04
- ```
+ ```console
+ $ docker pull ubuntu:16.04
+ ```
-2. Tag the image as `localhost:5000/my-ubuntu`. This creates an additional tag
- for the existing image. When the first part of the tag is a hostname and
- port, Docker interprets this as the location of a registry, when pushing.
+2. Tag the image as `localhost:5000/my-ubuntu`. This creates an additional tag
+ for the existing image. When the first part of the tag is a hostname and
+ port, Docker interprets this as the location of a registry, when pushing.
- ```console
- $ docker tag ubuntu:16.04 localhost:5000/my-ubuntu
- ```
+ ```console
+ $ docker tag ubuntu:16.04 localhost:5000/my-ubuntu
+ ```
-3. Push the image to the local registry running at `localhost:5000`:
+3. Push the image to the local registry running at `localhost:5000`:
- ```console
- $ docker push localhost:5000/my-ubuntu
- ```
+ ```console
+ $ docker push localhost:5000/my-ubuntu
+ ```
-4. Remove the locally-cached `ubuntu:16.04` and `localhost:5000/my-ubuntu`
- images, so that you can test pulling the image from your registry. This
- does not remove the `localhost:5000/my-ubuntu` image from your registry.
+4. Remove the locally-cached `ubuntu:16.04` and `localhost:5000/my-ubuntu`
+ images, so that you can test pulling the image from your registry. This
+ does not remove the `localhost:5000/my-ubuntu` image from your registry.
- ```console
- $ docker image remove ubuntu:16.04
- $ docker image remove localhost:5000/my-ubuntu
- ```
+ ```console
+ $ docker image remove ubuntu:16.04
+ $ docker image remove localhost:5000/my-ubuntu
+ ```
-5. Pull the `localhost:5000/my-ubuntu` image from your local registry.
+5. Pull the `localhost:5000/my-ubuntu` image from your local registry.
- ```console
- $ docker pull localhost:5000/my-ubuntu
- ```
+ ```console
+ $ docker pull localhost:5000/my-ubuntu
+ ```
## Stop a local registry
@@ -94,7 +94,7 @@ To configure the container, you can pass additional or modified options to the
`docker run` command.
The following sections provide basic guidelines for configuring your registry.
-For more details, see the [registry configuration reference](configuration.md).
+For more details, see the [registry configuration reference](../configuration).
### Start the registry automatically
@@ -144,7 +144,7 @@ $ docker run -d \
### Customize the storage location
-By default, your registry data is persisted as a [docker volume](../storage/volumes.md)
+By default, your registry data is persisted as a [docker volume](https://docs.docker.com/storage/volumes)
on the host filesystem. If you want to store your registry contents at a specific
location on your host filesystem, such as if you have an SSD or SAN mounted into
a particular directory, you might decide to use a bind mount instead. A bind mount
@@ -166,8 +166,8 @@ $ docker run -d \
By default, the registry stores its data on the local filesystem, whether you
use a bind mount or a volume. You can store the registry data in an Amazon S3
bucket, Google Cloud Platform, or on another storage back-end by using
-[storage drivers](./storage-drivers/index.md). For more information, see
-[storage configuration options](./configuration.md#storage).
+[storage drivers](/storage-drivers). For more information, see
+[storage configuration options](../configuration#storage).
## Run an externally-accessible registry
@@ -190,48 +190,48 @@ These examples assume the following:
If you have been issued an _intermediate_ certificate instead, see
[use an intermediate certificate](#use-an-intermediate-certificate).
-1. Create a `certs` directory.
+1. Create a `certs` directory.
- ```console
- $ mkdir -p certs
- ```
+ ```console
+ $ mkdir -p certs
+ ```
- Copy the `.crt` and `.key` files from the CA into the `certs` directory.
- The following steps assume that the files are named `domain.crt` and
- `domain.key`.
+ Copy the `.crt` and `.key` files from the CA into the `certs` directory.
+ The following steps assume that the files are named `domain.crt` and
+ `domain.key`.
-2. Stop the registry if it is currently running.
+2. Stop the registry if it is currently running.
- ```console
- $ docker container stop registry
- ```
+ ```console
+ $ docker container stop registry
+ ```
-3. Restart the registry, directing it to use the TLS certificate. This command
- bind-mounts the `certs/` directory into the container at `/certs/`, and sets
- environment variables that tell the container where to find the `domain.crt`
- and `domain.key` file. The registry runs on port 443, the default HTTPS port.
+3. Restart the registry, directing it to use the TLS certificate. This command
+ bind-mounts the `certs/` directory into the container at `/certs/`, and sets
+ environment variables that tell the container where to find the `domain.crt`
+ and `domain.key` file. The registry runs on port 443, the default HTTPS port.
- ```console
- $ docker run -d \
- --restart=always \
- --name registry \
- -v "$(pwd)"/certs:/certs \
- -e REGISTRY_HTTP_ADDR=0.0.0.0:443 \
- -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
- -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
- -p 443:443 \
- registry:2
- ```
+ ```console
+ $ docker run -d \
+ --restart=always \
+ --name registry \
+ -v "$(pwd)"/certs:/certs \
+ -e REGISTRY_HTTP_ADDR=0.0.0.0:443 \
+ -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
+ -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
+ -p 443:443 \
+ registry:2
+ ```
-4. Docker clients can now pull from and push to your registry using its
- external address. The following commands demonstrate this:
+4. Docker clients can now pull from and push to your registry using its
+ external address. The following commands demonstrate this:
- ```console
- $ docker pull ubuntu:16.04
- $ docker tag ubuntu:16.04 myregistry.domain.com/my-ubuntu
- $ docker push myregistry.domain.com/my-ubuntu
- $ docker pull myregistry.domain.com/my-ubuntu
- ```
+ ```console
+ $ docker pull ubuntu:16.04
+ $ docker tag ubuntu:16.04 myregistry.domain.com/my-ubuntu
+ $ docker push myregistry.domain.com/my-ubuntu
+ $ docker pull myregistry.domain.com/my-ubuntu
+ ```
#### Use an intermediate certificate
@@ -252,23 +252,23 @@ The registry supports using Let's Encrypt to automatically obtain a
browser-trusted certificate. For more information on Let's Encrypt, see
[https://letsencrypt.org/how-it-works/](https://letsencrypt.org/how-it-works/)
and the relevant section of the
-[registry configuration](configuration.md#letsencrypt).
+[registry configuration](../configuration#letsencrypt).
### Use an insecure registry (testing only)
It is possible to use a self-signed certificate, or to use our registry
insecurely. Unless you have set up verification for your self-signed
-certificate, this is for testing only. See [run an insecure registry](insecure.md).
+certificate, this is for testing only. See [run an insecure registry](../insecure).
## Run the registry as a service
-[Swarm services](../engine/swarm/services.md) provide several advantages over
+[Swarm services](https://docs.docker.com/engine/swarm/services) provide several advantages over
standalone containers. They use a declarative model, which means that you define
the desired state and Docker works to keep your service in that state. Services
provide automatic load balancing scaling, and the ability to control the
distribution of your service, among other advantages. Services also allow you to
store sensitive data such as TLS certificates in
-[secrets](../engine/swarm/secrets.md).
+[secrets](https://docs.docker.com/engine/swarm/secrets).
The storage back-end you use determines whether you use a fully scaled service
or a service with either only a single node or a node constraint.
@@ -342,9 +342,9 @@ The most important aspect is that a load balanced cluster of registries must
share the same resources. For the current version of the registry, this means
the following must be the same:
- - Storage Driver
- - HTTP Secret
- - Redis Cache (if configured)
+- Storage Driver
+- HTTP Secret
+- Redis Cache (if configured)
Differences in any of the above cause problems serving requests.
As an example, if you're using the filesystem driver, all registry instances
@@ -393,87 +393,89 @@ The simplest way to achieve access restriction is through basic authentication
This example uses native basic authentication using `htpasswd` to store the
secrets.
-> **Warning**:
-> You **cannot** use authentication with authentication schemes that send
-> credentials as clear text. You must
-> [configure TLS first](deploying.md#run-an-externally-accessible-registry) for
-> authentication to work.
-{:.warning}
+{{< hint type=warning >}}
+You **cannot** use authentication with authentication schemes that send
+credentials as clear text. You must
+[configure TLS first](#run-an-externally-accessible-registry) for
+authentication to work.
+{{< /hint >}}
-> **Warning**
-> The official registry image **only** supports htpasswd credentials in
-> bcrypt format, so if you omit the `-B` option when generating the credential
-> using htpasswd, all authentication attempts will fail.
-{:.warning}
+{{< hint type=warning >}}
+The distribution registry **only** supports htpasswd credentials in
+bcrypt format, so if you omit the `-B` option when generating the credential
+using htpasswd, all authentication attempts will fail.
+{{< /hint >}}
-1. Create a password file with one entry for the user `testuser`, with password
- `testpassword`:
+1. Create a password file with one entry for the user `testuser`, with password
+ `testpassword`:
- ```console
- $ mkdir auth
- $ docker run \
- --entrypoint htpasswd \
- httpd:2 -Bbn testuser testpassword > auth/htpasswd
- ```
-
- On Windows, make sure the output file is correctly encoded:
+ ```console
+ $ mkdir auth
+ $ docker run \
+ --entrypoint htpasswd \
+ httpd:2 -Bbn testuser testpassword > auth/htpasswd
+ ```
- ```powershell
- docker run --rm --entrypoint htpasswd httpd:2 -Bbn testuser testpassword | Set-Content -Encoding ASCII auth/htpasswd
- ```
+ On Windows, make sure the output file is correctly encoded:
-2. Stop the registry.
+ ```powershell
+ docker run --rm --entrypoint htpasswd httpd:2 -Bbn testuser testpassword | Set-Content -Encoding ASCII auth/htpasswd
+ ```
- ```console
- $ docker container stop registry
- ```
+2. Stop the registry.
-3. Start the registry with basic authentication.
+ ```console
+ $ docker container stop registry
+ ```
- ```console
- $ docker run -d \
- -p 5000:5000 \
- --restart=always \
- --name registry \
- -v "$(pwd)"/auth:/auth \
- -e "REGISTRY_AUTH=htpasswd" \
- -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
- -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
- -v "$(pwd)"/certs:/certs \
- -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
- -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
- registry:2
- ```
+3. Start the registry with basic authentication.
-4. Try to pull an image from the registry, or push an image to the registry.
- These commands fail.
+ ```console
+ $ docker run -d \
+ -p 5000:5000 \
+ --restart=always \
+ --name registry \
+ -v "$(pwd)"/auth:/auth \
+ -e "REGISTRY_AUTH=htpasswd" \
+ -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
+ -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
+ -v "$(pwd)"/certs:/certs \
+ -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
+ -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
+ registry:2
+ ```
-5. Log in to the registry.
+4. Try to pull an image from the registry, or push an image to the registry.
+ These commands fail.
- ```console
- $ docker login myregistrydomain.com:5000
- ```
+5. Log in to the registry.
- Provide the username and password from the first step.
+ ```console
+ $ docker login myregistrydomain.com:5000
+ ```
- Test that you can now pull an image from the registry or push an image to
- the registry.
+ Provide the username and password from the first step.
-> **X509 errors**: X509 errors usually indicate that you are attempting to use
-> a self-signed certificate without configuring the Docker daemon correctly.
-> See [run an insecure registry](insecure.md).
+ Test that you can now pull an image from the registry or push an image to
+ the registry.
+
+{{< hint type=note title="X509 errors" >}}
+X509 errors usually indicate that you are attempting to use
+a self-signed certificate without configuring the Docker daemon correctly.
+See [run an insecure registry](../insecure).
+{{< /hint >}}
### More advanced authentication
You may want to leverage more advanced basic auth implementations by using a
-proxy in front of the registry. See the [recipes list](recipes/index.md).
+proxy in front of the registry. See the [recipes list](/recipes/).
The registry also supports delegated authentication which redirects users to a
specific trusted token server. This approach is more complicated to set up, and
only makes sense if you need to fully configure ACLs and need more control over
the registry's integration into your global authorization and authentication
-systems. Refer to the following [background information](spec/auth/token.md) and
-[configuration information here](configuration.md#auth).
+systems. Refer to the following [background information](/spec/auth/token) and
+[configuration information here](../configuration#auth).
This approach requires you to implement your own authentication system or
leverage a third-party implementation.
@@ -537,41 +539,42 @@ following:
You are responsible for ensuring that you are in compliance with the terms of
use for non-distributable layers.
- 1. Edit the `daemon.json` file, which is located in `/etc/docker/` on Linux
- hosts and `C:\ProgramData\docker\config\daemon.json` on Windows Server.
- Assuming the file was previously empty, add the following contents:
+ 1. Edit the `daemon.json` file, which is located in `/etc/docker/` on Linux
+ hosts and `C:\ProgramData\docker\config\daemon.json` on Windows Server.
+ Assuming the file was previously empty, add the following contents:
- ```json
- {
- "allow-nondistributable-artifacts": ["myregistrydomain.com:5000"]
- }
- ```
+ ```json
+ {
+ "allow-nondistributable-artifacts": ["myregistrydomain.com:5000"]
+ }
+ ```
- The value is an array of registry addresses, separated by commas.
+ The value is an array of registry addresses, separated by commas.
- Save and exit the file.
+ Save and exit the file.
- 2. Restart Docker.
+ 2. Restart Docker.
- 3. Restart the registry if it does not start automatically.
+ 3. Restart the registry if it does not start automatically.
- 4. When you push images to the registries in the list, their
- non-distributable layers are pushed to the registry.
-
- > **Warning**: Non-distributable artifacts typically have restrictions on
- > how and where they can be distributed and shared. Only use this feature
- > to push artifacts to private registries and ensure that you are in
- > compliance with any terms that cover redistributing non-distributable
- > artifacts.
+ 4. When you push images to the registries in the list, their
+ non-distributable layers are pushed to the registry.
+{{< hint type=warning >}}
+Non-distributable artifacts typically have restrictions on
+how and where they can be distributed and shared. Only use this feature
+to push artifacts to private registries and ensure that you are in
+compliance with any terms that cover redistributing non-distributable
+artifacts.
+{{< /hint >}}
## Next steps
More specific and advanced information is available in the following sections:
- - [Configuration reference](configuration.md)
- - [Working with notifications](notifications.md)
- - [Advanced "recipes"](recipes/index.md)
- - [Registry API](spec/api.md)
- - [Storage driver model](storage-drivers/index.md)
- - [Token authentication](spec/auth/token.md)
+- [Configuration reference](../configuration)
+- [Working with notifications](../notifications)
+- [Advanced "recipes"](/recipes)
+- [Registry API](/spec/api)
+- [Storage driver model](/storage-drivers)
+- [Token authentication](/spec/auth/token)
diff --git a/docs/garbage-collection.md b/docs/content/about/garbage-collection.md
similarity index 94%
rename from docs/garbage-collection.md
rename to docs/content/about/garbage-collection.md
index 928fab9ae..dd1768d60 100644
--- a/docs/garbage-collection.md
+++ b/docs/content/about/garbage-collection.md
@@ -9,7 +9,7 @@ This document describes what this command does and how and why it should be used
## About garbage collection
-In the context of the Docker registry, garbage collection is the process of
+In the context of the registry, garbage collection is the process of
removing blobs from the filesystem when they are no longer referenced by a
manifest. Blobs can include both layers and manifests.
@@ -21,15 +21,15 @@ that certain layers no longer exist on the filesystem.
Filesystem layers are stored by their content address in the Registry. This
has many advantages, one of which is that data is stored once and referred to by manifests.
-See [here](compatibility.md#content-addressable-storage-cas) for more details.
+See [here](../compatibility#content-addressable-storage-cas) for more details.
Layers are therefore shared amongst manifests; each manifest maintains a reference
to the layer. As long as a layer is referenced by one manifest, it cannot be garbage
collected.
Manifests and layers can be `deleted` with the registry API (refer to the API
-documentation [here](spec/api.md#deleting-a-layer) and
-[here](spec/api.md#deleting-an-image) for details). This API removes references
+documentation [here](/spec/api#deleting-a-layer) and
+[here](/spec/api#deleting-an-image) for details). This API removes references
to the target and makes them eligible for garbage collection. It also makes them
unable to be read via the API.
diff --git a/docs/glossary.md b/docs/content/about/glossary.md
similarity index 94%
rename from docs/glossary.md
rename to docs/content/about/glossary.md
index b07cfc0c3..7d3ad18f0 100644
--- a/docs/glossary.md
+++ b/docs/content/about/glossary.md
@@ -1,5 +1,5 @@
---
-published: false
+draft: true
---
# Glossary
@@ -17,7 +17,7 @@ This page contains definitions for distribution related terms.
Image
- An image is a named set of immutable data from which a Docker container can be created.
+ An image is a named set of immutable data from which a container can be created.
An image is represented by a json file called a manifest, and is conceptually a set of layers.
@@ -45,7 +45,7 @@ This page contains definitions for distribution related terms.
Registry
- A registry is a service that let you store and deliver images.
+ A registry is a service that let you store and deliver images and other content.
Repository
diff --git a/docs/help.md b/docs/content/about/help.md
similarity index 83%
rename from docs/help.md
rename to docs/content/about/help.md
index 8c5f7e6dd..6e74aed14 100644
--- a/docs/help.md
+++ b/docs/content/about/help.md
@@ -10,5 +10,3 @@ If you want to report a bug:
- be sure to first read about [how to contribute](https://github.com/distribution/distribution/blob/master/CONTRIBUTING.md).
- you can then do so on the [GitHub project bugtracker](https://github.com/distribution/distribution/issues).
-
-You can also find out more about the Docker's project [Getting Help resources](../opensource/ways.md).
diff --git a/docs/insecure.md b/docs/content/about/insecure.md
similarity index 50%
rename from docs/insecure.md
rename to docs/content/about/insecure.md
index a012e8ab9..e9f55f15d 100644
--- a/docs/insecure.md
+++ b/docs/content/about/insecure.md
@@ -11,96 +11,96 @@ involves security trade-offs and additional configuration steps.
## Deploy a plain HTTP registry
-> **Warning**:
-> It's not possible to use an insecure registry with basic authentication.
-{:.warning}
+{{< hint type=warning >}}
+It's not possible to use an insecure registry with basic authentication.
+{{< /hint >}}
This procedure configures Docker to entirely disregard security for your
registry. This is **very** insecure and is not recommended. It exposes your
registry to trivial man-in-the-middle (MITM) attacks. Only use this solution for
isolated testing or in a tightly controlled, air-gapped environment.
-1. Edit the `daemon.json` file, whose default location is
- `/etc/docker/daemon.json` on Linux or
- `C:\ProgramData\docker\config\daemon.json` on Windows Server. If you use
- Docker Desktop for Mac or Docker Desktop for Windows, click the Docker icon, choose
- **Preferences** (Mac) or **Settings** (Windows), and choose **Docker Engine**.
+1. Edit the `daemon.json` file, whose default location is
+ `/etc/docker/daemon.json` on Linux or
+ `C:\ProgramData\docker\config\daemon.json` on Windows Server. If you use
+ Docker Desktop for Mac or Docker Desktop for Windows, click the Docker icon, choose
+ **Preferences** (Mac) or **Settings** (Windows), and choose **Docker Engine**.
- If the `daemon.json` file does not exist, create it. Assuming there are no
- other settings in the file, it should have the following contents:
+ If the `daemon.json` file does not exist, create it. Assuming there are no
+ other settings in the file, it should have the following contents:
- ```json
- {
- "insecure-registries" : ["myregistrydomain.com:5000"]
- }
- ```
+ ```json
+ {
+ "insecure-registries" : ["myregistrydomain.com:5000"]
+ }
+ ```
- Substitute the address of your insecure registry for the one in the example.
+ Substitute the address of your insecure registry for the one in the example.
- With insecure registries enabled, Docker goes through the following steps:
+ With insecure registries enabled, Docker goes through the following steps:
- - First, try using HTTPS.
- - If HTTPS is available but the certificate is invalid, ignore the error
- about the certificate.
- - If HTTPS is not available, fall back to HTTP.
+ - First, try using HTTPS.
+
+ - If HTTPS is available but the certificate is invalid, ignore the error
+ about the certificate.
+
+ - If HTTPS is not available, fall back to HTTP.
2. Restart Docker for the changes to take effect.
-
Repeat these steps on every Engine host that wants to access your registry.
-
## Use self-signed certificates
-> **Warning**:
-> Using this along with basic authentication requires to **also** trust the certificate into the OS cert store for some versions of docker (see below)
-{:.warning}
+{{< hint type=warning >}}
+Using this along with basic authentication requires to **also** trust the certificate into the OS cert store for some versions of docker (see below)
+{{< /hint >}}
This is more secure than the insecure registry solution.
-1. Generate your own certificate:
+1. Generate your own certificate:
- ```console
- $ mkdir -p certs
+ ```console
+ $ mkdir -p certs
- $ openssl req \
- -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \
- -addext "subjectAltName = DNS:myregistry.domain.com" \
- -x509 -days 365 -out certs/domain.crt
- ```
+ $ openssl req \
+ -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \
+ -addext "subjectAltName = DNS:myregistry.domain.com" \
+ -x509 -days 365 -out certs/domain.crt
+ ```
- Be sure to use the name `myregistry.domain.com` as a CN.
+ Be sure to use the name `myregistry.domain.com` as a CN.
-2. Use the result to [start your registry with TLS enabled](./deploying.md#get-a-certificate).
+2. Use the result to [start your registry with TLS enabled](../deploying#get-a-certificate).
-3. Instruct every Docker daemon to trust that certificate. The way to do this
- depends on your OS.
+3. Instruct every Docker daemon to trust that certificate. The way to do this
+ depends on your OS.
- - **Linux**: Copy the `domain.crt` file to
- `/etc/docker/certs.d/myregistrydomain.com:5000/ca.crt` on every Docker
- host. You do not need to restart Docker.
+ - **Linux**: Copy the `domain.crt` file to
+ `/etc/docker/certs.d/myregistrydomain.com:5000/ca.crt` on every Docker
+ host. You do not need to restart Docker.
- - **Windows Server**:
+ - **Windows Server**:
- 1. Open Windows Explorer, right-click the `domain.crt`
- file, and choose Install certificate. When prompted, select the following
- options:
+ 1. Open Windows Explorer, right-click the `domain.crt`
+ file, and choose Install certificate. When prompted, select the following
+ options:
- | Store location | local machine |
- | Place all certificates in the following store | selected |
+ | Store location | local machine |
+ | Place all certificates in the following store | selected |
- 2. Click **Browser** and select **Trusted Root Certificate Authorities**.
+ 2. Click **Browser** and select **Trusted Root Certificate Authorities**.
- 3. Click **Finish**. Restart Docker.
+ 3. Click **Finish**. Restart Docker.
- - **Docker Desktop for Mac**: Follow the instructions in
- [Adding custom CA certificates](../desktop/mac/index.md#add-tls-certificates){: target="_blank" rel="noopener" class="_"}.
- Restart Docker.
+ - **Docker Desktop for Mac**: Follow the instructions in
+ [Adding custom CA certificates](https://docs.docker.com/desktop/mac/#add-tls-certificates).
+ Restart Docker.
- - **Docker Desktop for Windows**: Follow the instructions in
- [Adding custom CA certificates](../desktop/windows/index.md#adding-tls-certificates){: target="_blank" rel="noopener" class="_"}.
- Restart Docker.
+ - **Docker Desktop for Windows**: Follow the instructions in
+ [Adding custom CA certificates](https://docs.docker.com/desktop/windows/#adding-tls-certificates).
+ Restart Docker.
## Troubleshoot insecure registry
diff --git a/docs/notifications.md b/docs/content/about/notifications.md
similarity index 98%
rename from docs/notifications.md
rename to docs/content/about/notifications.md
index 245d2faa0..81292bd9d 100644
--- a/docs/notifications.md
+++ b/docs/content/about/notifications.md
@@ -8,9 +8,9 @@ The Registry supports sending webhook notifications in response to events
happening within the registry. Notifications are sent in response to manifest
pushes and pulls and layer pushes and pulls. These actions are serialized into
events. The events are queued into a registry-internal broadcast system which
-queues and dispatches events to [_Endpoints_](notifications.md#endpoints).
+queues and dispatches events to [_Endpoints_](#endpoints).
-![Workflow of registry notifications](images/notifications.png)
+![Workflow of registry notifications](/images/notifications.png)
## Endpoints
@@ -45,7 +45,7 @@ The above would configure the registry with an endpoint to send events to
5 failures happen consecutively, the registry backs off for 1 second before
trying again.
-For details on the fields, see the [configuration documentation](configuration.md#notifications).
+For details on the fields, see the [configuration documentation](../configuration/#notifications).
A properly configured endpoint should lead to a log message from the registry
upon startup:
diff --git a/docs/recipes/index.md b/docs/content/recipes/_index.md
similarity index 78%
rename from docs/recipes/index.md
rename to docs/content/recipes/_index.md
index 3ffdba3b5..d6332b590 100644
--- a/docs/recipes/index.md
+++ b/docs/content/recipes/_index.md
@@ -9,7 +9,7 @@ These recipes are not useful for most standard set-ups.
## Requirements
-Before following these steps, work through the [deployment guide](../deploying.md).
+Before following these steps, work through the [deployment guide](../about/deploying).
At this point, it's assumed that:
@@ -21,8 +21,8 @@ At this point, it's assumed that:
## The List
- * [using Apache as an authenticating proxy](apache.md)
- * [using Nginx as an authenticating proxy](nginx.md)
- * [running a Registry on macOS](osx-setup-guide.md)
- * [mirror the Docker Hub](mirror.md)
- * [start registry via systemd](systemd.md)
+ * [using Apache as an authenticating proxy](apache)
+ * [using Nginx as an authenticating proxy](nginx)
+ * [running a Registry on macOS](osx-setup-guide)
+ * [mirror the Docker Hub](mirror)
+ * [start registry via systemd](systemd)
diff --git a/docs/recipes/apache.md b/docs/content/recipes/apache.md
similarity index 92%
rename from docs/recipes/apache.md
rename to docs/content/recipes/apache.md
index b559d2648..846392753 100644
--- a/docs/recipes/apache.md
+++ b/docs/content/recipes/apache.md
@@ -12,7 +12,7 @@ Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO
### Alternatives
-If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](../deploying.md#native-basic-auth).
+If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](/about/deploying#native-basic-auth).
### Solution
@@ -30,13 +30,13 @@ Furthermore, introducing an extra http layer in your communication pipeline adds
## Setting things up
-Read again [the requirements](index.md#requirements).
+Read again [the requirements](../#requirements).
Ready?
Run the following script:
-```
+```sh
mkdir -p auth
mkdir -p data
@@ -191,19 +191,27 @@ EOF
Now, start your stack:
- docker-compose up -d
+```console
+$ docker-compose up -d
+```
Log in with a "push" authorized user (using `testuserpush` and `testpasswordpush`), then tag and push your first image:
- docker login myregistrydomain.com:5043
- docker tag ubuntu myregistrydomain.com:5043/test
- docker push myregistrydomain.com:5043/test
+```console
+$ docker login myregistrydomain.com:5043
+$ docker tag ubuntu myregistrydomain.com:5043/test
+$ docker push myregistrydomain.com:5043/test
+```
Now, log in with a "pull-only" user (using `testuser` and `testpassword`), then pull back the image:
- docker login myregistrydomain.com:5043
- docker pull myregistrydomain.com:5043/test
+```console
+$ docker login myregistrydomain.com:5043
+$ docker pull myregistrydomain.com:5043/test
+```
Verify that the "pull-only" can NOT push:
- docker push myregistrydomain.com:5043/test
+```console
+$ docker push myregistrydomain.com:5043/test
+```
diff --git a/docs/recipes/mirror.md b/docs/content/recipes/mirror.md
similarity index 87%
rename from docs/recipes/mirror.md
rename to docs/content/recipes/mirror.md
index fe00b8b44..ca85487fc 100644
--- a/docs/recipes/mirror.md
+++ b/docs/content/recipes/mirror.md
@@ -2,22 +2,16 @@
description: Setting-up a local mirror for Docker Hub images
keywords: registry, on-prem, images, tags, repository, distribution, mirror, Hub, recipe, advanced
title: Registry as a pull through cache
-redirect_from:
-- /engine/admin/registry_mirror/
---
## Use-case
-If you have multiple instances of Docker running in your environment, such as
-multiple physical or virtual machines all running Docker, each daemon goes out
-to the internet and fetches an image it doesn't have locally, from the Docker
-repository. You can run a local registry mirror and point all your daemons
+If you have multiple consumers of containers running in your environment, such as
+multiple physical or virtual machines using containers, or a Kubernetes cluster,
+each cunsumer fetches an images it doesn't have locally, from the external registry.
+You can run a local registry mirror and point all your consumers
there, to avoid this extra internet traffic.
-> **Note**
->
-> Docker Official Images are an intellectual property of Docker.
-
### Alternatives
Alternatively, if the set of images you are using is well delimited, you can
@@ -88,7 +82,8 @@ but this property does not hold true for a registry cache cluster.
> **Note**
>
-> Service accounts included in the Team plan are limited to 5,000 pulls per day. See [Service Accounts](/docker-hub/service-accounts/) for more details.
+> Service accounts included in the Team plan are limited to 5,000 pulls per day.
+> See [Service Accounts](https://docs.docker.com/docker-hub/service-accounts/) for more details.
### Configure the cache
@@ -113,12 +108,12 @@ proxy:
> **Warning**: For the scheduler to clean up old entries, `delete` must
> be enabled in the registry configuration. See
-> [Registry Configuration](../configuration.md) for more details.
+> [Registry Configuration](/about/configuration) for more details.
### Configure the Docker daemon
Either pass the `--registry-mirror` option when starting `dockerd` manually,
-or edit [`/etc/docker/daemon.json`](../../engine/reference/commandline/dockerd.md#daemon-configuration-file)
+or edit [`/etc/docker/daemon.json`](https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file)
and add the `registry-mirrors` key and value, to make the change persistent.
```json
diff --git a/docs/content/recipes/nginx.md b/docs/content/recipes/nginx.md
new file mode 100644
index 000000000..127d900f6
--- /dev/null
+++ b/docs/content/recipes/nginx.md
@@ -0,0 +1,207 @@
+---
+description: Restricting access to your registry using a nginx proxy
+keywords: registry, on-prem, images, tags, repository, distribution, nginx, proxy, authentication, TLS, recipe, advanced
+title: Authenticate proxy with nginx
+---
+
+## Use-case
+
+People already relying on a nginx proxy to authenticate their users to other
+services might want to leverage it and have Registry communications tunneled
+through the same pipeline.
+
+Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO
+mechanism fronting their internal http portal.
+
+### Alternatives
+
+If you just want authentication for your registry, and are happy maintaining
+users access separately, you should really consider sticking with the native
+[basic auth registry feature](/about/deploying#native-basic-auth).
+
+### Solution
+
+With the method presented here, you implement basic authentication for docker
+engines in a reverse proxy that sits in front of your registry.
+
+While we use a simple htpasswd file as an example, any other nginx
+authentication backend should be fairly easy to implement once you are done with
+the example.
+
+We also implement push restriction (to a limited user group) for the sake of the
+example. Again, you should modify this to fit your mileage.
+
+### Gotchas
+
+While this model gives you the ability to use whatever authentication backend
+you want through the secondary authentication mechanism implemented inside your
+proxy, it also requires that you move TLS termination from the Registry to the
+proxy itself.
+
+> **Note**: It is not recommended to bind your registry to `localhost:5000` without
+> authentication. This creates a potential loophole in your registry security.
+> As a result, anyone who can log on to the server where your registry is running
+> can push images without authentication.
+
+Furthermore, introducing an extra http layer in your communication pipeline
+makes it more complex to deploy, maintain, and debug. Make sure the extra
+complexity is required.
+
+For instance, Amazon's Elastic Load Balancer (ELB) in HTTPS mode already sets
+the following client header:
+
+```none
+X-Real-IP
+X-Forwarded-For
+X-Forwarded-Proto
+```
+
+So if you have an Nginx instance sitting behind it, remove these lines from the
+example config below:
+
+```none
+proxy_set_header Host $http_host; # required for docker client's sake
+proxy_set_header X-Real-IP $remote_addr; # pass on real client's IP
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Forwarded-Proto $scheme;
+```
+
+Otherwise Nginx resets the ELB's values, and the requests are not routed
+properly. For more information, see
+[#970](https://github.com/distribution/distribution/issues/970).
+
+## Setting things up
+
+Review the [requirements](../#requirements), then follow these steps.
+
+1. Create the required directories
+
+ ```console
+ $ mkdir -p auth data
+ ```
+
+2. Create the main nginx configuration. Paste this code block into a new file called `auth/nginx.conf`:
+
+ ```conf
+ events {
+ worker_connections 1024;
+ }
+
+ http {
+
+ upstream docker-registry {
+ server registry:5000;
+ }
+
+ ## Set a variable to help us decide if we need to add the
+ ## 'Docker-Distribution-Api-Version' header.
+ ## The registry always sets this header.
+ ## In the case of nginx performing auth, the header is unset
+ ## since nginx is auth-ing before proxying.
+ map $upstream_http_docker_distribution_api_version $docker_distribution_api_version {
+ '' 'registry/2.0';
+ }
+
+ server {
+ listen 443 ssl;
+ server_name myregistrydomain.com;
+
+ # SSL
+ ssl_certificate /etc/nginx/conf.d/domain.crt;
+ ssl_certificate_key /etc/nginx/conf.d/domain.key;
+
+ # Recommendations from https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html
+ ssl_protocols TLSv1.1 TLSv1.2;
+ ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';
+ ssl_prefer_server_ciphers on;
+ ssl_session_cache shared:SSL:10m;
+
+ # disable any limits to avoid HTTP 413 for large image uploads
+ client_max_body_size 0;
+
+ # required to avoid HTTP 411: see Issue #1486 (https://github.com/moby/moby/issues/1486)
+ chunked_transfer_encoding on;
+
+ location /v2/ {
+ # Do not allow connections from docker 1.5 and earlier
+ # docker pre-1.6.0 did not properly set the user agent on ping, catch "Go *" user agents
+ if ($http_user_agent ~ "^(docker\/1\.(3|4|5(?!\.[0-9]-dev))|Go ).*$" ) {
+ return 404;
+ }
+
+ # To add basic authentication to v2 use auth_basic setting.
+ auth_basic "Registry realm";
+ auth_basic_user_file /etc/nginx/conf.d/nginx.htpasswd;
+
+ ## If $docker_distribution_api_version is empty, the header is not added.
+ ## See the map directive above where this variable is defined.
+ add_header 'Docker-Distribution-Api-Version' $docker_distribution_api_version always;
+
+ proxy_pass http://docker-registry;
+ proxy_set_header Host $http_host; # required for docker client's sake
+ proxy_set_header X-Real-IP $remote_addr; # pass on real client's IP
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_read_timeout 900;
+ }
+ }
+ }
+ ```
+
+3. Create a password file `auth/nginx.htpasswd` for "testuser" and "testpassword".
+
+ ```console
+ $ docker run --rm --entrypoint htpasswd registry:2 -Bbn testuser testpassword > auth/nginx.htpasswd
+ ```
+
+ > **Note**: If you do not want to use `bcrypt`, you can omit the `-B` parameter.
+
+4. Copy your certificate files to the `auth/` directory.
+
+ ```console
+ $ cp domain.crt auth
+ $ cp domain.key auth
+ ```
+
+5. Create the compose file. Paste the following YAML into a new file called `docker-compose.yml`.
+
+ ```yaml
+ version: "3"
+
+ services:
+ nginx:
+ # Note : Only nginx:alpine supports bcrypt.
+ # If you don't need to use bcrypt, you can use a different tag.
+ # Ref. https://github.com/nginxinc/docker-nginx/issues/29
+ image: "nginx:alpine"
+ ports:
+ - 5043:443
+ depends_on:
+ - registry
+ volumes:
+ - ./auth:/etc/nginx/conf.d
+ - ./auth/nginx.conf:/etc/nginx/nginx.conf:ro
+
+ registry:
+ image: registry:2
+ volumes:
+ - ./data:/var/lib/registry
+ ```
+
+## Starting and stopping
+
+Now, start your stack:
+
+```consonle
+$ docker-compose up -d
+```
+
+Login with a "push" authorized user (using `testuser` and `testpassword`), then
+tag and push your first image:
+
+```console
+$ docker login -u=testuser -p=testpassword -e=root@example.ch myregistrydomain.com:5043
+$ docker tag ubuntu myregistrydomain.com:5043/test
+$ docker push myregistrydomain.com:5043/test
+$ docker pull myregistrydomain.com:5043/test
+```
diff --git a/docs/recipes/osx-setup-guide.md b/docs/content/recipes/osx-setup-guide.md
similarity index 51%
rename from docs/recipes/osx-setup-guide.md
rename to docs/content/recipes/osx-setup-guide.md
index 40bc1a296..e33782a65 100644
--- a/docs/recipes/osx-setup-guide.md
+++ b/docs/content/recipes/osx-setup-guide.md
@@ -26,49 +26,65 @@ If you know, safely skip to the next section.
If you don't, the TLDR is:
- bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)
- source ~/.gvm/scripts/gvm
- gvm install go1.4.2
- gvm use go1.4.2
+```console
+$ bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)
+$ source ~/.gvm/scripts/gvm
+$ gvm install go1.4.2
+$ gvm use go1.4.2
+```
If you want to understand, you should read [How to Write Go Code](https://golang.org/doc/code.html).
## Checkout the source tree
- mkdir -p $GOPATH/src/github.com/distribution
- git clone https://github.com/distribution/distribution.git $GOPATH/src/github.com/distribution/distribution
- cd $GOPATH/src/github.com/distribution/distribution
+```console
+$ mkdir -p $GOPATH/src/github.com/distribution
+$ git clone https://github.com/distribution/distribution.git $GOPATH/src/github.com/distribution/distribution
+$ cd $GOPATH/src/github.com/distribution/distribution
+```
## Build the binary
- GOPATH=$(PWD)/Godeps/_workspace:$GOPATH make binaries
- sudo mkdir -p /usr/local/libexec
- sudo cp bin/registry /usr/local/libexec/registry
+```console
+$ GOPATH=$(PWD)/Godeps/_workspace:$GOPATH make binaries
+$ sudo mkdir -p /usr/local/libexec
+$ sudo cp bin/registry /usr/local/libexec/registry
+```
## Setup
Copy the registry configuration file in place:
- mkdir /Users/Shared/Registry
- cp docs/osx/config.yml /Users/Shared/Registry/config.yml
+```console
+$ mkdir /Users/Shared/Registry
+$ cp docs/osx/config.yml /Users/Shared/Registry/config.yml
+```
## Run the registry under launchd
Copy the registry plist into place:
- plutil -lint docs/recipes/osx/com.docker.registry.plist
- cp docs/recipes/osx/com.docker.registry.plist ~/Library/LaunchAgents/
- chmod 644 ~/Library/LaunchAgents/com.docker.registry.plist
+```console
+$ plutil -lint docs/recipes/osx/com.docker.registry.plist
+$ cp docs/recipes/osx/com.docker.registry.plist ~/Library/LaunchAgents/
+$ chmod 644 ~/Library/LaunchAgents/com.docker.registry.plist
+```
Start the registry:
- launchctl load ~/Library/LaunchAgents/com.docker.registry.plist
+```console
+$ launchctl load ~/Library/LaunchAgents/com.docker.registry.plist
+```
### Restart the registry service
- launchctl stop com.docker.registry
- launchctl start com.docker.registry
+```console
+$ launchctl stop com.docker.registry
+$ launchctl start com.docker.registry
+```
### Unload the registry service
- launchctl unload ~/Library/LaunchAgents/com.docker.registry.plist
+```console
+$ launchctl unload ~/Library/LaunchAgents/com.docker.registry.plist
+```
diff --git a/docs/recipes/osx/com.docker.registry.plist b/docs/content/recipes/osx/com.docker.registry.plist
similarity index 100%
rename from docs/recipes/osx/com.docker.registry.plist
rename to docs/content/recipes/osx/com.docker.registry.plist
diff --git a/docs/recipes/osx/config.yml b/docs/content/recipes/osx/config.yml
similarity index 100%
rename from docs/recipes/osx/config.yml
rename to docs/content/recipes/osx/config.yml
diff --git a/docs/recipes/systemd.md b/docs/content/recipes/systemd.md
similarity index 89%
rename from docs/recipes/systemd.md
rename to docs/content/recipes/systemd.md
index 99a0823d0..43c52215b 100644
--- a/docs/recipes/systemd.md
+++ b/docs/content/recipes/systemd.md
@@ -7,8 +7,9 @@ title: Start registry via systemd
## Use-case
Using systemd to manage containers can make service discovery and maintenance easier
-by managining all services in the same way. Additionally, when using Podman, systemd
+by managing all services in the same way. Additionally, when using Podman, systemd
can start the registry with socket-activation, providing additional security options:
+
* Run as non-root and expose on a low-numbered socket (< 1024)
* Run with `--network=none`
@@ -18,9 +19,10 @@ When deploying the registry via Docker, a simple service file can be used to man
the registry:
registry.service
-```
+
+```ini
[Unit]
-Description=Docker registry
+Description=Distribution registry
After=docker.service
Requires=docker.service
@@ -40,7 +42,7 @@ WantedBy=multi-user.target
In this case, the registry will store images in the named-volume `registry`.
Note that the container is destroyed on restart instead of using `--rm` or
-destroy on stop. This is done to make accessing `docker logs ...` easier in
+destroy on stop. This is done to make accessing `docker logs ...` easier in
the case of issues.
### Podman
@@ -50,7 +52,7 @@ socket-activation of containers.
#### Create service file
-```
+```sh
podman create --name registry --network=none -v registry:/var/lib/registry registry:2
podman generate systemd --name --new registry > registry.service
```
@@ -58,9 +60,10 @@ podman generate systemd --name --new registry > registry.service
#### Create socket file
registry.socket
-```
+
+```ini
[Unit]
-Description=container registry
+Description=Distribution registry
[Socket]
ListenStream=5000
@@ -71,7 +74,7 @@ WantedBy=sockets.target
### Installation
-Installation can be either rootful or rootless. For Docker, rootless configurations
+Installation can be either rootful or rootless. For Docker, rootless configurations
often include additional setup steps that are beyond the scope of this recipe, whereas
for Podman, rootless containers generally work out of the box.
diff --git a/docs/content/spec/_index.md b/docs/content/spec/_index.md
new file mode 100644
index 000000000..5e9729b8d
--- /dev/null
+++ b/docs/content/spec/_index.md
@@ -0,0 +1,12 @@
+---
+title: "Reference Overview"
+description: "Explains registry JSON objects"
+keywords: registry, service, images, repository, json
+---
+
+# Docker Registry Reference
+
+* [HTTP API V2](api)
+* [Storage Driver](/storage-drivers/)
+* [Token Authentication Specification](auth/token)
+* [Token Authentication Implementation](auth/jwt)
diff --git a/docs/spec/api.md b/docs/content/spec/api.md
similarity index 97%
rename from docs/spec/api.md
rename to docs/content/spec/api.md
index 9b34163c5..45d6c0d06 100644
--- a/docs/spec/api.md
+++ b/docs/content/spec/api.md
@@ -2,12 +2,10 @@
title: "HTTP API V2"
description: "Specification for the Registry API."
keywords: registry, on-prem, images, tags, repository, distribution, api, advanced
-redirect_from:
+aliases:
- /reference/api/registry_api/
---
-# Docker Registry HTTP API V2
-
## Introduction
The _Docker Registry HTTP API_ is the protocol to facilitate distribution of
@@ -212,7 +210,9 @@ layout of the new API is structured to support a rich authentication and
authorization model by leveraging namespaces. All endpoints will be prefixed
by the API version and the repository name:
- /v2//
+```none
+/v2//
+```
For example, an API endpoint that will work with the `library/ubuntu`
repository, the URI prefix will be:
@@ -252,6 +252,7 @@ Actionable failure conditions, covered in detail in their relevant sections,
are reported as part of 4xx responses, in a json response body. One or more
errors will be returned in the following format:
+```none
{
"errors": [
{
@@ -262,6 +263,7 @@ errors will be returned in the following format:
...
]
}
+```
The `code` field will be a unique identifier, all caps with underscores by
convention. The `message` field will be a human readable string. The optional
@@ -282,7 +284,9 @@ section.
A minimal endpoint, mounted at `/v2/` will provide version support information
based on its response statuses. The request format is as follows:
- GET /v2/
+```none
+GET /v2/
+```
If a `200 OK` response is returned, the registry implements the V2(.1)
registry API and the client may proceed safely with other V2 operations.
@@ -305,7 +309,7 @@ API. When this header is omitted, clients may fallback to an older API version.
### Content Digests
-This API design is driven heavily by [content addressability](http://en.wikipedia.org/wiki/Content-addressable_storage).
+This API design is driven heavily by [content addressability](https://en.wikipedia.org/wiki/Content-addressable_storage).
The core of this design is the concept of a content addressable identifier. It
uniquely identifies content by taking a collision-resistant hash of the bytes.
Such an identifier can be independently calculated and verified by selection
@@ -403,7 +407,7 @@ the V2 registry API, keyed by their digest.
The image manifest can be fetched with the following url:
-```
+```none
GET /v2//manifests/
```
@@ -411,28 +415,29 @@ The `name` and `reference` parameter identify the image and are required. The
reference may include a tag or digest.
The client should include an Accept header indicating which manifest content
-types it supports. For more details on the manifest formats and their content
-types, see [manifest-v2-1.md](manifest-v2-1.md) and
-[manifest-v2-2.md](manifest-v2-2.md). In a successful response, the Content-Type
-header will indicate which manifest type is being returned.
+types it supports. For more details on the manifest format and content types,
+see [Image Manifest Version 2, Schema 2](../manifest-v2-2).
+In a successful response, the Content-Type header will indicate which manifest type is being returned.
A `404 Not Found` response will be returned if the image is unknown to the
registry. If the image exists and the response is successful, the image
manifest will be returned, with the following format (see
[docker/docker#8093](https://github.com/docker/docker/issues/8093) for details):
- {
- "name": ,
- "tag": ,
- "fsLayers": [
- {
- "blobSum":
- },
- ...
- ],
- "history": ,
- "signature":
- }
+```none
+{
+ "name": ,
+ "tag": ,
+ "fsLayers": [
+ {
+ "blobSum":
+ },
+ ...
+ ],
+ "history": ,
+ "signature":
+}
+```
The client should verify the returned manifest signature for authenticity
before fetching layers.
@@ -441,7 +446,7 @@ before fetching layers.
The image manifest can be checked for existence with the following url:
-```
+```none
HEAD /v2//manifests/
```
@@ -452,13 +457,12 @@ A `404 Not Found` response will be returned if the image is unknown to the
registry. If the image exists and the response is successful the response will
be as follows:
-```
+```none
200 OK
Content-Length:
Docker-Content-Digest:
```
-
#### Pulling a Layer
Layers are stored in the blob portion of the registry, keyed by digest.
@@ -503,7 +507,7 @@ use the most recent value returned by the API.
To begin the process, a POST request should be issued in the following format:
-```
+```none
POST /v2//blobs/uploads/
```
@@ -515,7 +519,7 @@ will be linked. Responses to this request are covered below.
The existence of a layer can be checked via a `HEAD` request to the blob store
API. The request should be formatted as follows:
-```
+```none
HEAD /v2//blobs/
```
@@ -523,7 +527,7 @@ If the layer with the digest specified in `digest` is available, a 200 OK
response will be received, with no actual body content (this is according to
http specification). The response will look as follows:
-```
+```none
200 OK
Content-Length:
Docker-Content-Digest:
@@ -539,7 +543,7 @@ for the existing registry layer, but the digests will be guaranteed to match.
If the POST request is successful, a `202 Accepted` response will be returned
with the upload URL in the `Location` header:
-```
+```none
202 Accepted
Location: /v2//blobs/uploads/
Range: bytes=0-
@@ -568,20 +572,20 @@ header, there are examples of [similar approaches](https://developers.google.com
For an upload that just started, for an example with a 1000 byte layer file,
the `Range` header would be as follows:
-```
+```none
Range: bytes=0-0
```
To get the status of an upload, issue a GET request to the upload URL:
-```
+```none
GET /v2//blobs/uploads/
Host:
```
The response will be similar to the above, except will return 204 status:
-```
+```none
204 No Content
Location: /v2//blobs/uploads/
Range: bytes=0-
@@ -598,7 +602,7 @@ favored by clients that would like to avoided the complexity of chunking. To
carry out a "monolithic" upload, one can simply put the entire content blob to
the provided URL:
-```
+```none
PUT /v2//blobs/uploads/?digest=
Content-Length:
Content-Type: application/octet-stream
@@ -615,7 +619,7 @@ and expected responses.
To carry out an upload of a chunk, the client can specify a range header and
only include that part of the layer file:
-```
+```none
PATCH /v2//blobs/uploads/
Content-Length:
Content-Range: -
@@ -630,7 +634,7 @@ server cannot accept the chunk, a `416 Requested Range Not Satisfiable`
response will be returned and will include a `Range` header indicating the
current status:
-```
+```none
416 Requested Range Not Satisfiable
Location: /v2//blobs/uploads/
Range: 0-
@@ -649,7 +653,7 @@ following conditions:
When a chunk is accepted as part of the upload, a `202 Accepted` response will
be returned, including a `Range` header with the current upload status:
-```
+```none
202 Accepted
Location: /v2//blobs/uploads/
Range: bytes=0-
@@ -664,7 +668,7 @@ request on the upload endpoint with a digest parameter. If it is not provided,
the upload will not be considered complete. The format for the final chunk
will be as follows:
-```
+```none
PUT /v2//blobs/uploads/?digest=
Content-Length:
Content-Range: -
@@ -682,7 +686,7 @@ client if the content is rejected.
When the last chunk is received and the layer has been validated, the client
will receive a `201 Created` response:
-```
+```none
201 Created
Location: /v2//blobs/
Content-Length: 0
@@ -701,7 +705,7 @@ The "digest" parameter is designed as an opaque parameter to support
verification of a successful transfer. For example, an HTTP URI parameter
might be as follows:
-```
+```none
sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b
```
@@ -713,7 +717,7 @@ match this digest.
An upload can be cancelled by issuing a DELETE request to the upload endpoint.
The format will be as follows:
-```
+```none
DELETE /v2//blobs/uploads/
```
@@ -729,7 +733,7 @@ to, removing the need to upload a blob already known to the registry. To issue
a blob mount instead of an upload, a POST request should be issued in the
following format:
-```
+```none
POST /v2//blobs/uploads/?mount=&from=
Content-Length: 0
```
@@ -737,7 +741,7 @@ Content-Length: 0
If the blob is successfully mounted, the client will receive a `201 Created`
response:
-```
+```none
201 Created
Location: /v2//blobs/
Content-Length: 0
@@ -754,7 +758,7 @@ If a mount fails due to invalid repository or digest arguments, the registry
will fall back to the standard upload behavior and return a `202 Accepted` with
the upload URL in the `Location` header:
-```
+```none
202 Accepted
Location: /v2//blobs/uploads/
Range: bytes=0-
@@ -765,9 +769,11 @@ Docker-Upload-UUID:
This behavior is consistent with older versions of the registry, which do not
recognize the repository mount query parameters.
-Note: a client may issue a HEAD request to check existence of a blob in a source
+{{< hint type=note >}}
+A client may issue a HEAD request to check existence of a blob in a source
repository to distinguish between the registry not supporting blob mounts and
the blob not existing in the expected repository.
+{{< /hint >}}
##### Errors
@@ -789,13 +795,17 @@ client must restart the upload process.
A layer may be deleted from the registry via its `name` and `digest`. A
delete may be issued with the following request format:
- DELETE /v2//blobs/
+```none
+DELETE /v2//blobs/
+```
If the blob exists and has been successfully deleted, the following response
will be issued:
- 202 Accepted
- Content-Length: None
+```none
+202 Accepted
+Content-Length: None
+```
If the blob had already been deleted or did not exist, a `404 Not Found`
response will be issued instead.
@@ -808,27 +818,29 @@ then the complete images will not be resolvable.
Once all of the layers for an image are uploaded, the client can upload the
image manifest. An image can be pushed using the following request format:
- PUT /v2//manifests/
- Content-Type:
+```none
+PUT /v2//manifests/
+Content-Type:
- {
- "name": ,
- "tag": ,
- "fsLayers": [
- {
- "blobSum":
- },
- ...
- ],
- "history": ,
- "signature": ,
+{
+ "name": ,
+ "tag": ,
+ "fsLayers": [
+ {
+ "blobSum":
+ },
...
- }
+ ],
+ "history": ,
+ "signature": ,
+ ...
+}
+```
The `name` and `reference` fields of the response body must match those
specified in the URL. The `reference` field may be a "tag" or a "digest". The
content type should match the type of the manifest being uploaded, as specified
-in [manifest-v2-1.md](manifest-v2-1.md) and [manifest-v2-2.md](manifest-v2-2.md).
+in [Image Manifest Version 2, Schema 2](../manifest-v2-2).
If there is a problem with pushing the manifest, a relevant 4xx response will
be returned with a JSON error message. Please see the
@@ -840,18 +852,20 @@ returned. The `detail` field of the error response will have a `digest` field
identifying the missing blob. An error is returned for each unknown blob. The
response format is as follows:
- {
- "errors": [
- {
- "code": "BLOB_UNKNOWN",
- "message": "blob unknown to registry",
- "detail": {
- "digest":
- }
- },
- ...
- ]
- }
+```none
+{
+ "errors": [
+ {
+ "code": "BLOB_UNKNOWN",
+ "message": "blob unknown to registry",
+ "detail": {
+ "digest":
+ }
+ },
+ ...
+ ]
+}
+```
### Listing Repositories
@@ -862,13 +876,13 @@ available through the _catalog_.
The catalog for a given registry can be retrieved with the following request:
-```
+```none
GET /v2/_catalog
```
The response will be in the following format:
-```
+```none
200 OK
Content-Type: application/json
@@ -906,7 +920,7 @@ Paginated catalog results can be retrieved by adding an `n` parameter to the
request URL, declaring that the response should be limited to `n` results.
Starting a paginated flow begins as follows:
-```
+```none
GET /v2/_catalog?n=
```
@@ -914,7 +928,7 @@ The above specifies that a catalog response should be returned, from the start o
the result set, ordered lexically, limiting the number of results to `n`. The
response to such a request would look as follows:
-```
+```none
200 OK
Content-Type: application/json
Link: <?n=&last=>; rel="next"
@@ -950,7 +964,7 @@ to skip forward in the catalog.
To get the next result set, a client would issue the request as follows, using
the URL encoded in the described `Link` header:
-```
+```none
GET /v2/_catalog?n=&last=
```
@@ -965,7 +979,7 @@ entries.
The behavior of `last` is quite simple when demonstrated with an example. Let
us say the registry has the following repositories:
-```
+```none
a
b
c
@@ -976,7 +990,7 @@ If the value of `n` is 2, _a_ and _b_ will be returned on the first response.
The `Link` header returned on the response will have `n` set to 2 and last set
to _b_:
-```
+```none
Link: <?n=2&last=b>; rel="next"
```
@@ -1016,7 +1030,7 @@ any differences.
Starting a paginated flow may begin as follows:
-```
+```none
GET /v2//tags/list?n=
```
@@ -1024,7 +1038,7 @@ The above specifies that a tags response should be returned, from the start of
the result set, ordered lexically, limiting the number of results to `n`. The
response to such a request would look as follows:
-```
+```none
200 OK
Content-Type: application/json
Link: <?n=&last=>; rel="next"
@@ -1042,7 +1056,7 @@ To get the next result set, a client would issue the request as follows, using
the value encoded in the [RFC5988](https://tools.ietf.org/html/rfc5988) `Link`
header:
-```
+```none
GET /v2//tags/list?n=&last=
```
@@ -1074,23 +1088,27 @@ response will be issued instead.
Accept: application/vnd.docker.distribution.manifest.v2+json
-> for more details, see: [compatibility.md](../compatibility.md#content-addressable-storage-cas)
+> for more details, see: [compatibility](/about/compatibility#content-addressable-storage-cas)
## Detail
-> **Note**: This section is still under construction. For the purposes of
-> implementation, if any details below differ from the described request flows
-> above, the section below should be corrected. When they match, this note
-> should be removed.
+{{< hint type=note >}}
+This section is still under construction. For the purposes of
+implementation, if any details below differ from the described request flows
+above, the section below should be corrected. When they match, this note
+should be removed.
+{{< /hint >}}
The behavior of the endpoints are covered in detail in this section, organized
by route and entity. All aspects of the request and responses are covered,
including headers, parameters and body formats. Examples of requests and their
corresponding responses, with success and failure, are enumerated.
-> **Note**: The sections on endpoint detail are arranged with an example
-> request, a description of the request, followed by information about that
-> request.
+{{< hint type=note >}}
+The sections on endpoint detail are arranged with an example
+request, a description of the request, followed by information about that
+request.
+{{< /hint >}}
A list of methods and URIs are covered in the table below:
@@ -1110,7 +1128,6 @@ A list of methods and URIs are covered in the table below:
| DELETE | `/v2//blobs/uploads/` | Blob Upload | Cancel outstanding upload processes, releasing associated resources. If this is not called, the unfinished uploads will eventually timeout. |
| GET | `/v2/_catalog` | Catalog | Retrieve a sorted, json list of repositories available in the registry. |
-
The detail for each endpoint is covered in the following sections.
### Errors
@@ -1137,29 +1154,20 @@ The error codes encountered via the API are enumerated in the following table:
`DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource.
`UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters.
-
-
### Base
Base V2 API route. Typically, this can be used for lightweight version checks and to validate registry authentication.
-
-
#### GET Base
Check that the endpoint implements Docker Registry API V2.
-
-
-```
+```none
GET /v2/
Host:
Authorization:
```
-
-
-
The following parameters should be specified on the request:
|Name|Kind|Description|
@@ -1167,33 +1175,25 @@ The following parameters should be specified on the request:
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
|`Authorization`|header|An RFC7235 compliant authorization header.|
-
-
-
###### On Success: OK
-```
+```none
200 OK
```
The API implements V2 protocol and is accessible.
-
-
-
###### On Failure: Not Found
-```
+```none
404 Not Found
```
The registry does not implement the V2 API.
-
-
###### On Failure: Authentication Required
-```
+```none
401 Unauthorized
WWW-Authenticate: realm="", ..."
Content-Length:
@@ -1220,19 +1220,15 @@ The following headers will be returned on the response:
|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
-
-
###### On Failure: Too Many Requests
-```
+```none
429 Too Many Requests
Content-Length:
Content-Type: application/json
@@ -1257,32 +1253,23 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
-
-
-
-
### Tags
Retrieve information about tags.
-
-
#### GET Tags
Fetch the tags under the repository identified by `name`.
-
##### Tags
-```
+```none
GET /v2//tags/list
Host:
Authorization:
@@ -1290,7 +1277,6 @@ Authorization:
Return all tags for the repository
-
The following parameters should be specified on the request:
|Name|Kind|Description|
@@ -1299,12 +1285,9 @@ The following parameters should be specified on the request:
|`Authorization`|header|An RFC7235 compliant authorization header.|
|`name`|path|Name of the target repository.|
-
-
-
###### On Success: OK
-```
+```none
200 OK
Content-Length:
Content-Type: application/json
@@ -1326,12 +1309,9 @@ The following headers will be returned with the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
-
###### On Failure: Authentication Required
-```
+```none
401 Unauthorized
WWW-Authenticate: realm="", ..."
Content-Length:
@@ -1358,19 +1338,15 @@ The following headers will be returned on the response:
|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
-
-
###### On Failure: No Such Repository Error
-```
+```none
404 Not Found
Content-Length:
Content-Type: application/json
@@ -1395,19 +1371,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
-
-
###### On Failure: Access Denied
-```
+```none
403 Forbidden
Content-Length:
Content-Type: application/json
@@ -1432,19 +1404,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
-
-
###### On Failure: Too Many Requests
-```
+```none
429 Too Many Requests
Content-Length:
Content-Type: application/json
@@ -1469,25 +1437,20 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
-
-
##### Tags Paginated
-```
+```none
GET /v2//tags/list?n=&last=
```
Return a portion of the tags for the specified repository.
-
The following parameters should be specified on the request:
|Name|Kind|Description|
@@ -1496,12 +1459,9 @@ The following parameters should be specified on the request:
|`n`|query|Limit the number of entries in each response. If not present, all entries will be returned.|
|`last`|query|Result set will include values lexically after last.|
-
-
-
###### On Success: OK
-```
+```none
200 OK
Content-Length:
Link: <?n=&last=>; rel="next"
@@ -1525,12 +1485,9 @@ The following headers will be returned with the response:
|`Content-Length`|Length of the JSON response body.|
|`Link`|RFC5988 compliant rel='next' with URL to next result set, if available|
-
-
-
###### On Failure: Invalid pagination number
-```
+```none
400 Bad Request
Content-Type: application/json
@@ -1548,19 +1505,15 @@ Content-Type: application/json
The received parameter n was invalid in some way, as described by the error code. The client should resolve the issue and retry the request.
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `PAGINATION_NUMBER_INVALID` | invalid number of results requested | Returned when the "n" parameter (number of results to return) is not an integer, or "n" is negative. |
-
-
###### On Failure: Authentication Required
-```
+```none
401 Unauthorized
WWW-Authenticate: realm="", ..."
Content-Length:
@@ -1587,19 +1540,15 @@ The following headers will be returned on the response:
|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
-
-
###### On Failure: No Such Repository Error
-```
+```none
404 Not Found
Content-Length:
Content-Type: application/json
@@ -1624,19 +1573,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
-
-
###### On Failure: Access Denied
-```
+```none
403 Forbidden
Content-Length:
Content-Type: application/json
@@ -1661,19 +1606,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
-
-
###### On Failure: Too Many Requests
-```
+```none
429 Too Many Requests
Content-Length:
Content-Type: application/json
@@ -1698,39 +1639,26 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
-
-
-
-
### Manifest
Create, update, delete and retrieve manifests.
-
-
#### GET Manifest
Fetch the manifest identified by `name` and `reference` where `reference` can be a tag or digest. A `HEAD` request can also be issued to this endpoint to obtain resource information without receiving all data.
-
-
-```
+```none
GET /v2//manifests/
Host:
Authorization:
```
-
-
-
The following parameters should be specified on the request:
|Name|Kind|Description|
@@ -1740,12 +1668,9 @@ The following parameters should be specified on the request:
|`name`|path|Name of the target repository.|
|`reference`|path|Tag or digest of the target manifest.|
-
-
-
###### On Success: OK
-```
+```none
200 OK
Docker-Content-Digest:
Content-Type:
@@ -1772,12 +1697,9 @@ The following headers will be returned with the response:
|----|-----------|
|`Docker-Content-Digest`|Digest of the targeted content for the request.|
-
-
-
###### On Failure: Bad Request
-```
+```none
400 Bad Request
Content-Type: application/json
@@ -1795,8 +1717,6 @@ Content-Type: application/json
The name or reference was invalid.
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
@@ -1804,11 +1724,9 @@ The error codes that may be included in the response body are enumerated below:
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
| `TAG_INVALID` | manifest tag did not match URI | During a manifest upload, if the tag in the manifest does not match the uri tag, this error will be returned. |
-
-
###### On Failure: Authentication Required
-```
+```none
401 Unauthorized
WWW-Authenticate: realm="", ..."
Content-Length:
@@ -1835,19 +1753,15 @@ The following headers will be returned on the response:
|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
-
-
###### On Failure: No Such Repository Error
-```
+```none
404 Not Found
Content-Length:
Content-Type: application/json
@@ -1872,19 +1786,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
-
-
###### On Failure: Access Denied
-```
+```none
403 Forbidden
Content-Length:
Content-Type: application/json
@@ -1909,19 +1819,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
-
-
###### On Failure: Too Many Requests
-```
+```none
429 Too Many Requests
Content-Length:
Content-Type: application/json
@@ -1946,24 +1852,17 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
-
-
-
#### PUT Manifest
Put the manifest identified by `name` and `reference` where `reference` can be a tag or digest.
-
-
-```
+```none
PUT /v2//manifests/
Host:
Authorization:
@@ -1983,9 +1882,6 @@ Content-Type:
}
```
-
-
-
The following parameters should be specified on the request:
|Name|Kind|Description|
@@ -1995,12 +1891,9 @@ The following parameters should be specified on the request:
|`name`|path|Name of the target repository.|
|`reference`|path|Tag or digest of the target manifest.|
-
-
-
###### On Success: Created
-```
+```none
201 Created
Location:
Content-Length: 0
@@ -2017,12 +1910,9 @@ The following headers will be returned with the response:
|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
|`Docker-Content-Digest`|Digest of the targeted content for the request.|
-
-
-
###### On Failure: Invalid Manifest
-```
+```none
400 Bad Request
Content-Type: application/json
@@ -2040,8 +1930,6 @@ Content-Type: application/json
The received manifest was invalid in some way, as described by the error codes. The client should resolve the issue and retry the request.
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
@@ -2052,11 +1940,9 @@ The error codes that may be included in the response body are enumerated below:
| `MANIFEST_UNVERIFIED` | manifest failed signature verification | During manifest upload, if the manifest fails signature verification, this error will be returned. |
| `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. |
-
-
###### On Failure: Authentication Required
-```
+```none
401 Unauthorized
WWW-Authenticate: realm="", ..."
Content-Length:
@@ -2083,19 +1969,15 @@ The following headers will be returned on the response:
|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
-
-
###### On Failure: No Such Repository Error
-```
+```none
404 Not Found
Content-Length:
Content-Type: application/json
@@ -2120,19 +2002,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
-
-
###### On Failure: Access Denied
-```
+```none
403 Forbidden
Content-Length:
Content-Type: application/json
@@ -2157,19 +2035,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
-
-
###### On Failure: Too Many Requests
-```
+```none
429 Too Many Requests
Content-Length:
Content-Type: application/json
@@ -2194,19 +2068,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
-
-
###### On Failure: Missing Layer(s)
-```
+```none
400 Bad Request
Content-Type: application/json
@@ -2226,50 +2096,36 @@ Content-Type: application/json
One or more layers may be missing during a manifest upload. If so, the missing layers will be enumerated in the error response.
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. |
-
-
###### On Failure: Not allowed
-```
+```none
405 Method Not Allowed
```
Manifest put is not allowed because the registry is configured as a pull-through cache or for some other reason
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
-
-
-
#### DELETE Manifest
Delete the manifest or tag identified by `name` and `reference` where `reference` can be a tag or digest. Note that a manifest can _only_ be deleted by digest.
-
-
-```
+```none
DELETE /v2//manifests/
Host:
Authorization:
```
-
-
-
The following parameters should be specified on the request:
|Name|Kind|Description|
@@ -2279,23 +2135,15 @@ The following parameters should be specified on the request:
|`name`|path|Name of the target repository.|
|`reference`|path|Tag or digest of the target manifest.|
-
-
-
###### On Success: Accepted
-```
+```none
202 Accepted
```
-
-
-
-
-
###### On Failure: Invalid Name or Reference
-```
+```none
400 Bad Request
Content-Type: application/json
@@ -2313,8 +2161,6 @@ Content-Type: application/json
The specified `name` or `reference` were invalid and the delete was unable to proceed.
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
@@ -2322,11 +2168,9 @@ The error codes that may be included in the response body are enumerated below:
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
| `TAG_INVALID` | manifest tag did not match URI | During a manifest upload, if the tag in the manifest does not match the uri tag, this error will be returned. |
-
-
###### On Failure: Authentication Required
-```
+```none
401 Unauthorized
WWW-Authenticate: realm="", ..."
Content-Length:
@@ -2353,19 +2197,15 @@ The following headers will be returned on the response:
|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
-
-
###### On Failure: No Such Repository Error
-```
+```none
404 Not Found
Content-Length:
Content-Type: application/json
@@ -2390,19 +2230,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
-
-
###### On Failure: Access Denied
-```
+```none
403 Forbidden
Content-Length:
Content-Type: application/json
@@ -2427,19 +2263,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
-
-
###### On Failure: Too Many Requests
-```
+```none
429 Too Many Requests
Content-Length:
Content-Type: application/json
@@ -2464,19 +2296,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
-
-
###### On Failure: Unknown Manifest
-```
+```none
404 Not Found
Content-Type: application/json
@@ -2494,8 +2322,6 @@ Content-Type: application/json
The specified `name` or `reference` are unknown to the registry and the delete was unable to proceed. Clients can assume the manifest or tag was already deleted if this response is returned.
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
@@ -2503,50 +2329,36 @@ The error codes that may be included in the response body are enumerated below:
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
| `MANIFEST_UNKNOWN` | manifest unknown | This error is returned when the manifest, identified by name and tag is unknown to the repository. |
-
-
###### On Failure: Not allowed
-```
+```none
405 Method Not Allowed
```
Manifest or tag delete is not allowed because the registry is configured as a pull-through cache or `delete` has been disabled.
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
-
-
-
-
### Blob
Operations on blobs identified by `name` and `digest`. Used to fetch or delete layers by digest.
-
-
#### GET Blob
Retrieve the blob from the registry identified by `digest`. A `HEAD` request can also be issued to this endpoint to obtain resource information without receiving all data.
-
##### Fetch Blob
-```
+```none
GET /v2//blobs/
Host:
Authorization:
```
-
-
-
The following parameters should be specified on the request:
|Name|Kind|Description|
@@ -2556,12 +2368,9 @@ The following parameters should be specified on the request:
|`name`|path|Name of the target repository.|
|`digest`|path|Digest of desired blob.|
-
-
-
###### On Success: OK
-```
+```none
200 OK
Content-Length:
Docker-Content-Digest:
@@ -2581,7 +2390,7 @@ The following headers will be returned with the response:
###### On Success: Temporary Redirect
-```
+```none
307 Temporary Redirect
Location:
Docker-Content-Digest:
@@ -2596,12 +2405,9 @@ The following headers will be returned with the response:
|`Location`|The location where the layer should be accessible.|
|`Docker-Content-Digest`|Digest of the targeted content for the request.|
-
-
-
###### On Failure: Bad Request
-```
+```none
400 Bad Request
Content-Type: application/json
@@ -2619,8 +2425,6 @@ Content-Type: application/json
There was a problem with the request that needs to be addressed by the client, such as an invalid `name` or `tag`.
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
@@ -2628,11 +2432,9 @@ The error codes that may be included in the response body are enumerated below:
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
-
-
###### On Failure: Not Found
-```
+```none
404 Not Found
Content-Type: application/json
@@ -2650,8 +2452,6 @@ Content-Type: application/json
The blob, identified by `name` and `digest`, is unknown to the registry.
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
@@ -2659,11 +2459,9 @@ The error codes that may be included in the response body are enumerated below:
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
| `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. |
-
-
###### On Failure: Authentication Required
-```
+```none
401 Unauthorized
WWW-Authenticate: realm="", ..."
Content-Length:
@@ -2690,19 +2488,15 @@ The following headers will be returned on the response:
|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
-
-
###### On Failure: No Such Repository Error
-```
+```none
404 Not Found
Content-Length:
Content-Type: application/json
@@ -2727,19 +2521,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
-
-
###### On Failure: Access Denied
-```
+```none
403 Forbidden
Content-Length:
Content-Type: application/json
@@ -2764,19 +2554,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
-
-
###### On Failure: Too Many Requests
-```
+```none
429 Too Many Requests
Content-Length:
Content-Type: application/json
@@ -2801,19 +2587,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
-
-
##### Fetch Blob Part
-```
+```none
GET /v2//blobs/
Host:
Authorization:
@@ -2822,7 +2604,6 @@ Range: bytes=-
This endpoint may also support RFC7233 compliant range requests. Support can be detected by issuing a HEAD request. If the header `Accept-Range: bytes` is returned, range requests can be used to fetch partial content.
-
The following parameters should be specified on the request:
|Name|Kind|Description|
@@ -2833,12 +2614,9 @@ The following parameters should be specified on the request:
|`name`|path|Name of the target repository.|
|`digest`|path|Digest of desired blob.|
-
-
-
###### On Success: Partial Content
-```
+```none
206 Partial Content
Content-Length:
Content-Range: bytes -/
@@ -2856,12 +2634,9 @@ The following headers will be returned with the response:
|`Content-Length`|The length of the requested blob chunk.|
|`Content-Range`|Content range of blob chunk.|
-
-
-
###### On Failure: Bad Request
-```
+```none
400 Bad Request
Content-Type: application/json
@@ -2879,8 +2654,6 @@ Content-Type: application/json
There was a problem with the request that needs to be addressed by the client, such as an invalid `name` or `tag`.
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
@@ -2888,11 +2661,9 @@ The error codes that may be included in the response body are enumerated below:
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
-
-
###### On Failure: Not Found
-```
+```none
404 Not Found
Content-Type: application/json
@@ -2908,10 +2679,6 @@ Content-Type: application/json
}
```
-
-
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
@@ -2919,21 +2686,17 @@ The error codes that may be included in the response body are enumerated below:
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
| `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. |
-
-
###### On Failure: Requested Range Not Satisfiable
-```
+```none
416 Requested Range Not Satisfiable
```
The range specification cannot be satisfied for the requested content. This can happen when the range is not formatted correctly or if the range is outside of the valid size of the content.
-
-
###### On Failure: Authentication Required
-```
+```none
401 Unauthorized
WWW-Authenticate: realm="", ..."
Content-Length:
@@ -2960,19 +2723,15 @@ The following headers will be returned on the response:
|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
-
-
###### On Failure: No Such Repository Error
-```
+```none
404 Not Found
Content-Length:
Content-Type: application/json
@@ -2997,19 +2756,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
-
-
###### On Failure: Access Denied
-```
+```none
403 Forbidden
Content-Length:
Content-Type: application/json
@@ -3034,19 +2789,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
-
-
###### On Failure: Too Many Requests
-```
+```none
429 Too Many Requests
Content-Length:
Content-Type: application/json
@@ -3071,32 +2822,22 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
-
-
-
#### DELETE Blob
Delete the blob identified by `name` and `digest`
-
-
-```
+```none
DELETE /v2//blobs/
Host:
Authorization:
```
-
-
-
The following parameters should be specified on the request:
|Name|Kind|Description|
@@ -3106,19 +2847,14 @@ The following parameters should be specified on the request:
|`name`|path|Name of the target repository.|
|`digest`|path|Digest of desired blob.|
-
-
-
###### On Success: Accepted
-```
+```none
202 Accepted
Content-Length: 0
Docker-Content-Digest:
```
-
-
The following headers will be returned with the response:
|Name|Description|
@@ -3126,19 +2862,12 @@ The following headers will be returned with the response:
|`Content-Length`|0|
|`Docker-Content-Digest`|Digest of the targeted content for the request.|
-
-
-
###### On Failure: Invalid Name or Digest
-```
+```none
400 Bad Request
```
-
-
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
@@ -3146,11 +2875,9 @@ The error codes that may be included in the response body are enumerated below:
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
-
-
###### On Failure: Not Found
-```
+```none
404 Not Found
Content-Type: application/json
@@ -3168,8 +2895,6 @@ Content-Type: application/json
The blob, identified by `name` and `digest`, is unknown to the registry.
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
@@ -3177,11 +2902,9 @@ The error codes that may be included in the response body are enumerated below:
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
| `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. |
-
-
###### On Failure: Method Not Allowed
-```
+```none
405 Method Not Allowed
Content-Type: application/json
@@ -3199,19 +2922,15 @@ Content-Type: application/json
Blob delete is not allowed because the registry is configured as a pull-through cache or `delete` has been disabled
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
-
-
###### On Failure: Authentication Required
-```
+```none
401 Unauthorized
WWW-Authenticate: realm="", ..."
Content-Length:
@@ -3238,19 +2957,15 @@ The following headers will be returned on the response:
|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
-
-
###### On Failure: No Such Repository Error
-```
+```none
404 Not Found
Content-Length:
Content-Type: application/json
@@ -3275,19 +2990,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
-
-
###### On Failure: Access Denied
-```
+```none
403 Forbidden
Content-Length:
Content-Type: application/json
@@ -3312,19 +3023,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
-
-
###### On Failure: Too Many Requests
-```
+```none
429 Too Many Requests
Content-Length:
Content-Type: application/json
@@ -3349,32 +3056,23 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
-
-
-
-
### Initiate Blob Upload
Initiate a blob upload. This endpoint can be used to create resumable uploads or monolithic uploads.
-
-
#### POST Initiate Blob Upload
Initiate a resumable blob upload. If successful, an upload location will be provided to complete the upload. Optionally, if the `digest` parameter is present, the request body will be used to complete the upload in a single request.
-
##### Initiate Monolithic Blob Upload
-```
+```none
POST /v2//blobs/uploads/?digest=
Host:
Authorization:
@@ -3386,7 +3084,6 @@ Content-Type: application/octet-stream
Upload a blob identified by the `digest` parameter in single request. This upload will not be resumable unless a recoverable error is returned.
-
The following parameters should be specified on the request:
|Name|Kind|Description|
@@ -3397,12 +3094,9 @@ The following parameters should be specified on the request:
|`name`|path|Name of the target repository.|
|`digest`|query|Digest of uploaded blob. If present, the upload will be completed, in a single request, with contents of the request body as the resulting blob.|
-
-
-
###### On Success: Created
-```
+```none
201 Created
Location:
Content-Length: 0
@@ -3419,19 +3113,12 @@ The following headers will be returned with the response:
|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
-
-
-
###### On Failure: Invalid Name or Digest
-```
+```none
400 Bad Request
```
-
-
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
@@ -3439,29 +3126,23 @@ The error codes that may be included in the response body are enumerated below:
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
-
-
###### On Failure: Not allowed
-```
+```none
405 Method Not Allowed
```
Blob upload is not allowed because the registry is configured as a pull-through cache or for some other reason
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
-
-
###### On Failure: Authentication Required
-```
+```none
401 Unauthorized
WWW-Authenticate: realm="", ..."
Content-Length:
@@ -3488,19 +3169,15 @@ The following headers will be returned on the response:
|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
-
-
###### On Failure: No Such Repository Error
-```
+```none
404 Not Found
Content-Length:
Content-Type: application/json
@@ -3525,19 +3202,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
-
-
###### On Failure: Access Denied
-```
+```none
403 Forbidden
Content-Length:
Content-Type: application/json
@@ -3562,19 +3235,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
-
-
###### On Failure: Too Many Requests
-```
+```none
429 Too Many Requests
Content-Length:
Content-Type: application/json
@@ -3599,19 +3268,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
-
-
##### Initiate Resumable Blob Upload
-```
+```none
POST /v2//blobs/uploads/
Host:
Authorization:
@@ -3620,7 +3285,6 @@ Content-Length: 0
Initiate a resumable blob upload with an empty request body.
-
The following parameters should be specified on the request:
|Name|Kind|Description|
@@ -3630,12 +3294,9 @@ The following parameters should be specified on the request:
|`Content-Length`|header|The `Content-Length` header must be zero and the body must be empty.|
|`name`|path|Name of the target repository.|
-
-
-
###### On Success: Accepted
-```
+```none
202 Accepted
Location: /v2//blobs/uploads/
Range: 0-
@@ -3654,19 +3315,12 @@ The following headers will be returned with the response:
|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
-
-
-
###### On Failure: Invalid Name or Digest
-```
+```none
400 Bad Request
```
-
-
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
@@ -3674,11 +3328,9 @@ The error codes that may be included in the response body are enumerated below:
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
-
-
###### On Failure: Authentication Required
-```
+```none
401 Unauthorized
WWW-Authenticate: realm="", ..."
Content-Length:
@@ -3705,19 +3357,15 @@ The following headers will be returned on the response:
|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
-
-
###### On Failure: No Such Repository Error
-```
+```none
404 Not Found
Content-Length:
Content-Type: application/json
@@ -3742,19 +3390,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
-
-
###### On Failure: Access Denied
-```
+```none
403 Forbidden
Content-Length:
Content-Type: application/json
@@ -3779,19 +3423,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
-
-
###### On Failure: Too Many Requests
-```
+```none
429 Too Many Requests
Content-Length:
Content-Type: application/json
@@ -3816,19 +3456,15 @@ The following headers will be returned on the response:
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
-
-
##### Mount Blob
-```
+```none
POST /v2//blobs/uploads/?mount=&from=
Host:
Authorization:
@@ -3837,7 +3473,6 @@ Content-Length: 0
Mount a blob identified by the `mount` parameter from another repository.
-
The following parameters should be specified on the request:
|Name|Kind|Description|
@@ -3849,12 +3484,9 @@ The following parameters should be specified on the request:
|`mount`|query|Digest of blob to mount from the source repository.|
|`from`|query|Name of the source repository.|
-
-
-
###### On Success: Created
-```
+```none
201 Created
Location:
Content-Length: 0
@@ -3871,19 +3503,12 @@ The following headers will be returned with the response:
|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
-
-
-
###### On Failure: Invalid Name or Digest
-```
+```none
400 Bad Request
```
-
-
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
@@ -3891,29 +3516,23 @@ The error codes that may be included in the response body are enumerated below:
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
-
-
###### On Failure: Not allowed
-```
+```none
405 Method Not Allowed
```
Blob mount is not allowed because the registry is configured as a pull-through cache or for some other reason
-
-
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
-
-
###### On Failure: Authentication Required
-```
+```none
401 Unauthorized
WWW-Authenticate: realm="", ..."
Content-Length: