alexvanin/distribution
1
0
Fork 0
forked from TrueCloudLab/distribution
Code Pull requests Activity

docs: fix markup and broken links

Browse source 
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson 2023-10-12 09:32:37 +02:00
parent e2ae76f1f2
commit b911020c1f
38 changed files with 783 additions and 1337 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
docs/content/_index.md
View file

@ -1,8 +1,6 @@
--- ---
description: High-level overview of the Registry description: High-level overview of the Registry
keywords: registry, on-prem, images, tags, repository, distribution keywords: registry, on-prem, images, tags, repository, distribution
redirect_from:
- /registry/overview/
title: Docker Registry title: Docker Registry
--- ---
@ -35,29 +33,41 @@ The Registry is compatible with Docker engine **version 1.6.0 or higher**.
Start your registry Start your registry
docker run -d -p 5000:5000 --name registry registry:2 ```sh
docker run -d -p 5000:5000 --name registry registry:2
```
Pull (or build) some image from the hub Pull (or build) some image from the hub
docker pull ubuntu ```sh
docker pull ubuntu
```
Tag the image so that it points to your registry Tag the image so that it points to your registry
docker image tag ubuntu localhost:5000/myfirstimage ```sh
docker image tag ubuntu localhost:5000/myfirstimage
```
Push it Push it
docker push localhost:5000/myfirstimage ```sh
docker push localhost:5000/myfirstimage
```
Pull it back Pull it back
docker pull localhost:5000/myfirstimage ```sh
docker pull localhost:5000/myfirstimage
```
Now stop your registry and remove all data Now stop your registry and remove all data
docker container stop registry && docker container rm -v registry ```sh
docker container stop registry && docker container rm -v registry
```
## Next ## Next
You should now read the [detailed introduction about the registry](./about/_index.md), You should now read the [detailed introduction about the registry](about),
or jump directly to [deployment instructions](./about/deploying.md). or jump directly to [deployment instructions](about/deploying).

6
docs/content/about/_index.md
View file

@ -27,7 +27,7 @@ The Registry GitHub repository includes additional information about advanced
authentication and authorization methods. Only very large or public deployments authentication and authorization methods. Only very large or public deployments
are expected to extend the Registry in this way. 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, calling webhooks in response to activity, and both extensive logging and reporting,
mostly useful for large installations that want to collect metrics. mostly useful for large installations that want to collect metrics.
@ -39,7 +39,7 @@ Image names as used in typical docker commands reflect their origin:
* `docker pull myregistrydomain:port/foo/bar` instructs docker to contact the registry located at `myregistrydomain:port` to find the image `foo/bar` * `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 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 [official Docker engine documentation](https://docs.docker.com/engine/reference/commandline/cli/).
## Use cases ## Use cases
@ -70,4 +70,4 @@ golang are certainly useful as well for advanced operations or hacking.
## Next ## Next
Dive into [deploying your registry](deploying.md) Dive into [deploying your registry](deploying)

2
docs/content/about/architecture.md
View file

@ -1,5 +1,5 @@
--- ---
published: false draft: true
--- ---
# Architecture # Architecture

6
docs/content/about/compatibility.md
View file

@ -5,13 +5,14 @@ title: Registry compatibility
--- ---
## Synopsis ## Synopsis
If a manifest is pulled by _digest_ from a registry 2.3 with Docker Engine 1.9 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 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. causes the Engine to receive a manifest it cannot use and the pull fails.
## Registry manifest support ## 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_. known as _Schema 1_.
With the move toward multiple architecture images, the distribution project 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 This conversion has some implications for pulling manifests by digest and this
document enumerates these implications. document enumerates these implications.
## Content Addressable Storage (CAS) ## Content Addressable Storage (CAS)
Manifests are stored and retrieved in the registry by keying off a digest 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 Schema 1 type manifest when it detects that the registry does not
support the new version. support the new version.
## Registry v2.3 ## Registry v2.3
### Manifest push with Docker 1.10 ### 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 When the manifest is pulled by digest or tag with any Docker version, a
_Schema 1_ manifest is returned. _Schema 1_ manifest is returned.

87
docs/content/about/configuration.md
View file

@ -20,7 +20,7 @@ To override a configuration option, create an environment variable named
and the `_` (underscore) represents indention levels. For example, you can and the `_` (underscore) represents indention levels. For example, you can
configure the `rootdirectory` of the `filesystem` storage backend: configure the `rootdirectory` of the `filesystem` storage backend:
```none ```yaml
storage: storage:
filesystem: filesystem:
rootdirectory: /var/lib/registry rootdirectory: /var/lib/registry
@ -28,7 +28,7 @@ storage:
To override this value, set an environment variable like this: To override this value, set an environment variable like this:
```none ```sh
REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere 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 are mutually exclusive. Read the detailed reference information about each
option before finalizing your configuration. option before finalizing your configuration.
```none ```yaml
version: 0.1 version: 0.1
log: log:
accesslog: accesslog:
@ -293,7 +293,7 @@ the children marked **required**.
## `version` ## `version`
```none ```yaml
version: 0.1 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 system outputs everything to stderr. You can adjust the granularity and format
with this configuration section. with this configuration section.
```none ```yaml
log: log:
accesslog: accesslog:
disabled: true disabled: true
@ -326,7 +326,7 @@ log:
### `accesslog` ### `accesslog`
```none ```yaml
accesslog: accesslog:
disabled: true disabled: true
``` ```
@ -338,7 +338,7 @@ Access logging can be disabled by setting the boolean flag `disabled` to `true`.
## `hooks` ## `hooks`
```none ```yaml
hooks: hooks:
- type: mail - type: mail
levels: levels:
@ -362,7 +362,7 @@ Refer to `loglevel` to configure the level of messages printed.
> **DEPRECATED:** Please use [log](#log) instead. > **DEPRECATED:** Please use [log](#log) instead.
```none ```yaml
loglevel: debug loglevel: debug
``` ```
@ -371,7 +371,7 @@ Permitted values are `error`, `warn`, `info` and `debug`. The default is
## `storage` ## `storage`
```none ```yaml
storage: storage:
filesystem: filesystem:
rootdirectory: /var/lib/registry rootdirectory: /var/lib/registry
@ -436,15 +436,15 @@ returns an error. You can choose any of these backend storage drivers:
| Storage driver | Description | | 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). | | `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](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/azure.md). | | `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](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/gcs.md). | | `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](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/s3.md). | | `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 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 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. on a ramdisk.
If you are deploying a registry on Windows, a Windows volume mounted from the 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), the mount point must be within the `MAX_PATH` limits (typically 255 characters),
or this error will occur: or this error will occur:
```none ```text
mkdir /XXX protocol error and your registry will not function properly. 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 by digest. It defaults to false, but it can be enabled by writing the following
on the configuration file: on the configuration file:
```none ```yaml
delete: delete:
enabled: true enabled: true
``` ```
@ -531,14 +531,14 @@ instance is aggressively caching.
To disable redirects, add a single flag `disable`, set to `true` To disable redirects, add a single flag `disable`, set to `true`
under the `redirect` section: under the `redirect` section:
```none ```yaml
redirect: redirect:
disable: true disable: true
``` ```
## `auth` ## `auth`
```none ```yaml
auth: auth:
silly: silly:
realm: silly-realm realm: silly-realm
@ -593,7 +593,7 @@ security.
For more information about Token based authentication configuration, see the For more information about Token based authentication configuration, see the
[specification](spec/auth/token.md). [specification](/spec/auth/token).
### `htpasswd` ### `htpasswd`
@ -601,7 +601,7 @@ The _htpasswd_ authentication backed allows you to configure basic
authentication using an authentication using an
[Apache htpasswd file](https://httpd.apache.org/docs/2.4/programs/htpasswd.html). [Apache htpasswd file](https://httpd.apache.org/docs/2.4/programs/htpasswd.html).
The only supported password format is 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 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. 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 This is an example configuration of the `cloudfront` middleware, a storage
middleware: middleware:
```none ```yaml
middleware: middleware:
registry: registry:
- name: ARegistryMiddleware - name: ARegistryMiddleware
@ -694,7 +694,7 @@ location of a proxy for the layer stored by the S3 storage driver.
## `http` ## `http`
```none ```yaml
http: http:
addr: localhost:5000 addr: localhost:5000
net: tcp net: tcp
@ -834,7 +834,7 @@ to access proxy statistics. These statistics are exposed at `/debug/vars` in JSO
#### `prometheus` #### `prometheus`
```none ```yaml
prometheus: prometheus:
enabled: true enabled: true
path: /metrics path: /metrics
@ -879,7 +879,7 @@ settings for the registry.
## `notifications` ## `notifications`
```none ```yaml
notifications: notifications:
events: events:
includereferences: true includereferences: true
@ -937,7 +937,7 @@ The `events` structure configures the information provided in event notification
## `redis` ## `redis`
```none ```yaml
redis: redis:
addr: localhost:6379 addr: localhost:6379
password: asecret password: asecret
@ -974,7 +974,7 @@ registry does not set an expiration value on keys.
### `pool` ### `pool`
```none ```yaml
pool: pool:
maxidle: 16 maxidle: 16
maxactive: 64 maxactive: 64
@ -991,7 +991,7 @@ Use these settings to configure the behavior of the Redis connection pool.
### `tls` ### `tls`
```none ```yaml
tls: tls:
enabled: false enabled: false
``` ```
@ -1005,7 +1005,7 @@ Use these settings to configure Redis TLS.
## `health` ## `health`
```none ```yaml
health: health:
storagedriver: storagedriver:
enabled: true enabled: true
@ -1090,7 +1090,7 @@ attempt fails, the health check will fail.
## `proxy` ## `proxy`
``` ```yaml
proxy: proxy:
remoteurl: https://registry-1.docker.io remoteurl: https://registry-1.docker.io
username: [username] username: [username]
@ -1099,8 +1099,8 @@ proxy:
``` ```
The `proxy` structure allows a registry to be configured as a pull-through cache The `proxy` structure allows a registry to be configured as a pull-through cache
to Docker Hub. See to Docker Hub. See
[mirror](https://github.com/docker/docker.github.io/tree/master/registry/recipes/mirror.md) [mirror](/recipes/mirror)
for more information. Pushing to a registry configured as a pull-through cache for more information. Pushing to a registry configured as a pull-through cache
is unsupported. is unsupported.
@ -1120,7 +1120,7 @@ username (such as `batman`) and the password for that username.
## `validation` ## `validation`
```none ```yaml
validation: validation:
manifests: manifests:
urls: 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 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: one of the `allow` regular expressions **and** one of the following holds:
1. `deny` is unset. 1. `deny` is unset.
2. `deny` is set but no URLs within the manifest match any of the `deny` regular 2. `deny` is set but no URLs within the manifest match any of the `deny` regular
expressions. expressions.
## Example: Development configuration ## Example: Development configuration
You can use this simple example for local development: You can use this simple example for local development:
```none ```yaml
version: 0.1 version: 0.1
log: log:
level: debug level: debug
@ -1183,10 +1183,9 @@ See
for another simple configuration. Both examples are generally useful for local for another simple configuration. Both examples are generally useful for local
development. development.
## Example: Middleware configuration ## 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 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 layers via a content delivery network (CDN). This reduces requests to the
storage layer. storage layer.
@ -1195,7 +1194,7 @@ Cloudfront requires the S3 storage driver.
This is the configuration expressed in YAML: This is the configuration expressed in YAML:
```none ```yaml
middleware: middleware:
storage: storage:
- name: cloudfront - name: cloudfront
@ -1210,6 +1209,8 @@ middleware:
See the configuration reference for [Cloudfront](#cloudfront) for more See the configuration reference for [Cloudfront](#cloudfront) for more
information about configuration options. information about configuration options.
> **Note**: Cloudfront keys exist separately from other AWS keys. See {{< hint type=note >}}
> [the documentation on AWS credentials](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html) Cloudfront keys exist separately from other AWS keys. See
> for more information. [the documentation on AWS credentials](https://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html)
for more information.
{{< /hint >}}

315
docs/content/about/deploying.md
View file

@ -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 This topic provides basic information about deploying and configuring a
registry. For an exhaustive list of configuration options, see the 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 If you have an air-gapped datacenter, see
[Considerations for air-gapped registries](#considerations-for-air-gapped-registries). [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 > **Warning**: These first few examples show registry configurations that are
> only appropriate for testing. A production-ready registry must be protected by > 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 > 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. > production-ready registry.
## Copy an image from Docker Hub to your 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 `ubuntu:16.04` and `my-ubuntu` images are deleted locally and the
`my-ubuntu` image is pulled from the local registry. `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 ```console
$ docker pull ubuntu:16.04 $ docker pull ubuntu:16.04
``` ```
2. Tag the image as `localhost:5000/my-ubuntu`. This creates an additional tag 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 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. port, Docker interprets this as the location of a registry, when pushing.
```console ```console
$ docker tag ubuntu:16.04 localhost:5000/my-ubuntu $ 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 ```console
$ docker push localhost:5000/my-ubuntu $ docker push localhost:5000/my-ubuntu
``` ```
4. Remove the locally-cached `ubuntu:16.04` and `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 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. does not remove the `localhost:5000/my-ubuntu` image from your registry.
```console ```console
$ docker image remove ubuntu:16.04 $ docker image remove ubuntu:16.04
$ docker image remove localhost:5000/my-ubuntu $ 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 ```console
$ docker pull localhost:5000/my-ubuntu $ docker pull localhost:5000/my-ubuntu
``` ```
## Stop a local registry ## Stop a local registry
@ -94,7 +94,7 @@ To configure the container, you can pass additional or modified options to the
`docker run` command. `docker run` command.
The following sections provide basic guidelines for configuring your registry. 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 ### Start the registry automatically
@ -144,7 +144,7 @@ $ docker run -d \
### Customize the storage location ### 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 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 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 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 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 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 bucket, Google Cloud Platform, or on another storage back-end by using
[storage drivers](./storage-drivers/index.md). For more information, see [storage drivers](/storage-drivers). For more information, see
[storage configuration options](./configuration.md#storage). [storage configuration options](../configuration#storage).
## Run an externally-accessible registry ## Run an externally-accessible registry
@ -190,48 +190,48 @@ These examples assume the following:
If you have been issued an _intermediate_ certificate instead, see If you have been issued an _intermediate_ certificate instead, see
[use an intermediate certificate](#use-an-intermediate-certificate). [use an intermediate certificate](#use-an-intermediate-certificate).
1. Create a `certs` directory. 1. Create a `certs` directory.
```console ```console
$ mkdir -p certs $ mkdir -p certs
``` ```
Copy the `.crt` and `.key` files from the CA into the `certs` directory. 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 The following steps assume that the files are named `domain.crt` and
`domain.key`. `domain.key`.
2. Stop the registry if it is currently running. 2. Stop the registry if it is currently running.
```console ```console
$ docker container stop registry $ docker container stop registry
``` ```
3. Restart the registry, directing it to use the TLS certificate. This command 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 bind-mounts the `certs/` directory into the container at `/certs/`, and sets
environment variables that tell the container where to find the `domain.crt` 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. and `domain.key` file. The registry runs on port 443, the default HTTPS port.
```console ```console
$ docker run -d \ $ docker run -d \
--restart=always \ --restart=always \
--name registry \ --name registry \
-v "$(pwd)"/certs:/certs \ -v "$(pwd)"/certs:/certs \
-e REGISTRY_HTTP_ADDR=0.0.0.0:443 \ -e REGISTRY_HTTP_ADDR=0.0.0.0:443 \
-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \ -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
-e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \ -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
-p 443:443 \ -p 443:443 \
registry:2 registry:2
``` ```
4. Docker clients can now pull from and push to your registry using its 4. Docker clients can now pull from and push to your registry using its
external address. The following commands demonstrate this: external address. The following commands demonstrate this:
```console ```console
$ docker pull ubuntu:16.04 $ docker pull ubuntu:16.04
$ docker tag ubuntu:16.04 myregistry.domain.com/my-ubuntu $ docker tag ubuntu:16.04 myregistry.domain.com/my-ubuntu
$ docker push myregistry.domain.com/my-ubuntu $ docker push myregistry.domain.com/my-ubuntu
$ docker pull myregistry.domain.com/my-ubuntu $ docker pull myregistry.domain.com/my-ubuntu
``` ```
#### Use an intermediate certificate #### 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 browser-trusted certificate. For more information on Let's Encrypt, see
[https://letsencrypt.org/how-it-works/](https://letsencrypt.org/how-it-works/) [https://letsencrypt.org/how-it-works/](https://letsencrypt.org/how-it-works/)
and the relevant section of the and the relevant section of the
[registry configuration](configuration.md#letsencrypt). [registry configuration](../configuration#letsencrypt).
### Use an insecure registry (testing only) ### Use an insecure registry (testing only)
It is possible to use a self-signed certificate, or to use our registry 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 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 ## 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 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 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 provide automatic load balancing scaling, and the ability to control the
distribution of your service, among other advantages. Services also allow you to distribution of your service, among other advantages. Services also allow you to
store sensitive data such as TLS certificates in 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 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. 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 share the same resources. For the current version of the registry, this means
the following must be the same: the following must be the same:
- Storage Driver - Storage Driver
- HTTP Secret - HTTP Secret
- Redis Cache (if configured) - Redis Cache (if configured)
Differences in any of the above cause problems serving requests. Differences in any of the above cause problems serving requests.
As an example, if you're using the filesystem driver, all registry instances 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 This example uses native basic authentication using `htpasswd` to store the
secrets. secrets.
> **Warning**: {{< hint type=warning >}}
> You **cannot** use authentication with authentication schemes that send You **cannot** use authentication with authentication schemes that send
> credentials as clear text. You must credentials as clear text. You must
> [configure TLS first](deploying.md#run-an-externally-accessible-registry) for [configure TLS first](#run-an-externally-accessible-registry) for
> authentication to work. authentication to work.
{:.warning} {{< /hint >}}
> **Warning** {{< hint type=warning >}}
> The official registry image **only** supports htpasswd credentials in The official registry image **only** supports htpasswd credentials in
> bcrypt format, so if you omit the `-B` option when generating the credential bcrypt format, so if you omit the `-B` option when generating the credential
> using htpasswd, all authentication attempts will fail. using htpasswd, all authentication attempts will fail.
{:.warning} {{< /hint >}}
1. Create a password file with one entry for the user `testuser`, with password 1. Create a password file with one entry for the user `testuser`, with password
`testpassword`: `testpassword`:
```console ```console
$ mkdir auth $ mkdir auth
$ docker run \ $ docker run \
--entrypoint htpasswd \ --entrypoint htpasswd \
httpd:2 -Bbn testuser testpassword > auth/htpasswd httpd:2 -Bbn testuser testpassword > auth/htpasswd
``` ```
On Windows, make sure the output file is correctly encoded:
```powershell On Windows, make sure the output file is correctly encoded:
docker run --rm --entrypoint htpasswd httpd:2 -Bbn testuser testpassword | Set-Content -Encoding ASCII auth/htpasswd
```
2. Stop the registry. ```powershell
docker run --rm --entrypoint htpasswd httpd:2 -Bbn testuser testpassword | Set-Content -Encoding ASCII auth/htpasswd
```
```console 2. Stop the registry.
$ docker container stop registry
```
3. Start the registry with basic authentication. ```console
$ docker container stop registry
```
```console 3. Start the registry with basic authentication.
$ 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
```
4. Try to pull an image from the registry, or push an image to the registry. ```console
These commands fail. $ 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 5. Log in to the registry.
$ docker login myregistrydomain.com:5000
```
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 Provide the username and password from the first step.
the registry.
> **X509 errors**: X509 errors usually indicate that you are attempting to use Test that you can now pull an image from the registry or push an image to
> a self-signed certificate without configuring the Docker daemon correctly. the registry.
> See [run an insecure registry](insecure.md).
{{< 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 ### More advanced authentication
You may want to leverage more advanced basic auth implementations by using a 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 The registry also supports delegated authentication which redirects users to a
specific trusted token server. This approach is more complicated to set up, and 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 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 the registry's integration into your global authorization and authentication
systems. Refer to the following [background information](spec/auth/token.md) and systems. Refer to the following [background information](/spec/auth/token) and
[configuration information here](configuration.md#auth). [configuration information here](../configuration#auth).
This approach requires you to implement your own authentication system or This approach requires you to implement your own authentication system or
leverage a third-party implementation. leverage a third-party implementation.
@ -537,41 +539,42 @@ following:
You are responsible for ensuring that you are in compliance with the terms of You are responsible for ensuring that you are in compliance with the terms of
use for non-distributable layers. use for non-distributable layers.
1. Edit the `daemon.json` file, which is located in `/etc/docker/` on Linux 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. hosts and `C:\ProgramData\docker\config\daemon.json` on Windows Server.
Assuming the file was previously empty, add the following contents: Assuming the file was previously empty, add the following contents:
```json ```json
{ {
"allow-nondistributable-artifacts": ["myregistrydomain.com:5000"] "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 4. When you push images to the registries in the list, their
non-distributable layers are pushed to the registry. 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.
{{< 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 ## Next steps
More specific and advanced information is available in the following sections: More specific and advanced information is available in the following sections:
- [Configuration reference](configuration.md) - [Configuration reference](../configuration)
- [Working with notifications](notifications.md) - [Working with notifications](../notifications)
- [Advanced "recipes"](recipes/index.md) - [Advanced "recipes"](/recipes)
- [Registry API](spec/api.md) - [Registry API](/spec/api)
- [Storage driver model](storage-drivers/index.md) - [Storage driver model](/storage-drivers)
- [Token authentication](spec/auth/token.md) - [Token authentication](/spec/auth/token)

6
docs/content/about/garbage-collection.md
View file

@ -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 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. 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 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 to the layer. As long as a layer is referenced by one manifest, it cannot be garbage
collected. collected.
Manifests and layers can be `deleted` with the registry API (refer to the API Manifests and layers can be `deleted` with the registry API (refer to the API
documentation [here](spec/api.md#deleting-a-layer) and documentation [here](/spec/api#deleting-a-layer) and
[here](spec/api.md#deleting-an-image) for details). This API removes references [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 to the target and makes them eligible for garbage collection. It also makes them
unable to be read via the API. unable to be read via the API.

2
docs/content/about/glossary.md
View file

@ -1,5 +1,5 @@
--- ---
published: false draft: true
--- ---
# Glossary # Glossary

2
docs/content/about/help.md
View file

@ -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). - 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 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).

110
docs/content/about/insecure.md
View file

@ -11,96 +11,96 @@ involves security trade-offs and additional configuration steps.
## Deploy a plain HTTP registry ## Deploy a plain HTTP registry
> **Warning**: {{< hint type=warning >}}
> It's not possible to use an insecure registry with basic authentication. It's not possible to use an insecure registry with basic authentication.
{:.warning} {{< /hint >}}
This procedure configures Docker to entirely disregard security for your This procedure configures Docker to entirely disregard security for your
registry. This is **very** insecure and is not recommended. It exposes 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 registry to trivial man-in-the-middle (MITM) attacks. Only use this solution for
isolated testing or in a tightly controlled, air-gapped environment. isolated testing or in a tightly controlled, air-gapped environment.
1. Edit the `daemon.json` file, whose default location is 1. Edit the `daemon.json` file, whose default location is
`/etc/docker/daemon.json` on Linux or `/etc/docker/daemon.json` on Linux or
`C:\ProgramData\docker\config\daemon.json` on Windows Server. If you use `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 Docker Desktop for Mac or Docker Desktop for Windows, click the Docker icon, choose
**Preferences** (Mac) or **Settings** (Windows), and choose **Docker Engine**. **Preferences** (Mac) or **Settings** (Windows), and choose **Docker Engine**.
If the `daemon.json` file does not exist, create it. Assuming there are no 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: other settings in the file, it should have the following contents:
```json ```json
{ {
"insecure-registries" : ["myregistrydomain.com:5000"] "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. - First, try using HTTPS.
- If HTTPS is available but the certificate is invalid, ignore the error
about the certificate. - If HTTPS is available but the certificate is invalid, ignore the error
- If HTTPS is not available, fall back to HTTP. about the certificate.
- If HTTPS is not available, fall back to HTTP.
2. Restart Docker for the changes to take effect. 2. Restart Docker for the changes to take effect.
Repeat these steps on every Engine host that wants to access your registry. Repeat these steps on every Engine host that wants to access your registry.
## Use self-signed certificates ## Use self-signed certificates
> **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) 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 >}}
This is more secure than the insecure registry solution. This is more secure than the insecure registry solution.
1. Generate your own certificate: 1. Generate your own certificate:
```console ```console
$ mkdir -p certs $ mkdir -p certs
$ openssl req \ $ openssl req \
-newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \ -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \
-addext "subjectAltName = DNS:myregistry.domain.com" \ -addext "subjectAltName = DNS:myregistry.domain.com" \
-x509 -days 365 -out certs/domain.crt -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 3. Instruct every Docker daemon to trust that certificate. The way to do this
depends on your OS. depends on your OS.
- **Linux**: Copy the `domain.crt` file to - **Linux**: Copy the `domain.crt` file to
`/etc/docker/certs.d/myregistrydomain.com:5000/ca.crt` on every Docker `/etc/docker/certs.d/myregistrydomain.com:5000/ca.crt` on every Docker
host. You do not need to restart Docker. host. You do not need to restart Docker.
- **Windows Server**: - **Windows Server**:
1. Open Windows Explorer, right-click the `domain.crt` 1. Open Windows Explorer, right-click the `domain.crt`
file, and choose Install certificate. When prompted, select the following file, and choose Install certificate. When prompted, select the following
options: options:
| Store location | local machine | | Store location | local machine |
| Place all certificates in the following store | selected | | 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 - **Docker Desktop for Mac**: Follow the instructions in
[Adding custom CA certificates](../desktop/mac/index.md#add-tls-certificates){: target="_blank" rel="noopener" class="_"}. [Adding custom CA certificates](https://docs.docker.com/desktop/mac/#add-tls-certificates).
Restart Docker. Restart Docker.
- **Docker Desktop for Windows**: Follow the instructions in - **Docker Desktop for Windows**: Follow the instructions in
[Adding custom CA certificates](../desktop/windows/index.md#adding-tls-certificates){: target="_blank" rel="noopener" class="_"}. [Adding custom CA certificates](https://docs.docker.com/desktop/windows/#adding-tls-certificates).
Restart Docker. Restart Docker.
## Troubleshoot insecure registry ## Troubleshoot insecure registry

6
docs/content/about/notifications.md
View file

@ -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 happening within the registry. Notifications are sent in response to manifest
pushes and pulls and layer pushes and pulls. These actions are serialized into 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 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 ## 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 5 failures happen consecutively, the registry backs off for 1 second before
trying again. 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 A properly configured endpoint should lead to a log message from the registry
upon startup: upon startup:

12
docs/content/recipes/_index.md
View file

@ -9,7 +9,7 @@ These recipes are not useful for most standard set-ups.
## Requirements ## 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: At this point, it's assumed that:
@ -21,8 +21,8 @@ At this point, it's assumed that:
## The List ## The List
* [using Apache as an authenticating proxy](apache.md) * [using Apache as an authenticating proxy](apache)
* [using Nginx as an authenticating proxy](nginx.md) * [using Nginx as an authenticating proxy](nginx)
* [running a Registry on macOS](osx-setup-guide.md) * [running a Registry on macOS](osx-setup-guide)
* [mirror the Docker Hub](mirror.md) * [mirror the Docker Hub](mirror)
* [start registry via systemd](systemd.md) * [start registry via systemd](systemd)

28
docs/content/recipes/apache.md
View file

@ -12,7 +12,7 @@ Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO
### Alternatives ### 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 ### Solution
@ -30,13 +30,13 @@ Furthermore, introducing an extra http layer in your communication pipeline adds
## Setting things up ## Setting things up
Read again [the requirements](index.md#requirements). Read again [the requirements](../#requirements).
Ready? Ready?
Run the following script: Run the following script:
``` ```sh
mkdir -p auth mkdir -p auth
mkdir -p data mkdir -p data
@ -191,19 +191,27 @@ EOF
Now, start your stack: 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: Log in with a "push" authorized user (using `testuserpush` and `testpasswordpush`), then tag and push your first image:
docker login myregistrydomain.com:5043 ```console
docker tag ubuntu myregistrydomain.com:5043/test $ docker login myregistrydomain.com:5043
docker push myregistrydomain.com:5043/test $ 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: Now, log in with a "pull-only" user (using `testuser` and `testpassword`), then pull back the image:
docker login myregistrydomain.com:5043 ```console
docker pull myregistrydomain.com:5043/test $ docker login myregistrydomain.com:5043
$ docker pull myregistrydomain.com:5043/test
```
Verify that the "pull-only" can NOT push: Verify that the "pull-only" can NOT push:
docker push myregistrydomain.com:5043/test ```console
$ docker push myregistrydomain.com:5043/test
```

9
docs/content/recipes/mirror.md
View file

@ -2,8 +2,6 @@
description: Setting-up a local mirror for Docker Hub images description: Setting-up a local mirror for Docker Hub images
keywords: registry, on-prem, images, tags, repository, distribution, mirror, Hub, recipe, advanced keywords: registry, on-prem, images, tags, repository, distribution, mirror, Hub, recipe, advanced
title: Registry as a pull through cache title: Registry as a pull through cache
redirect_from:
- /engine/admin/registry_mirror/
--- ---
## Use-case ## Use-case
@ -88,7 +86,8 @@ but this property does not hold true for a registry cache cluster.
> **Note** > **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 ### Configure the cache
@ -113,12 +112,12 @@ proxy:
> **Warning**: For the scheduler to clean up old entries, `delete` must > **Warning**: For the scheduler to clean up old entries, `delete` must
> be enabled in the registry configuration. See > 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 ### Configure the Docker daemon
Either pass the `--registry-mirror` option when starting `dockerd` manually, 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. and add the `registry-mirrors` key and value, to make the change persistent.
```json ```json

200
docs/content/recipes/nginx.md
View file

@ -2,8 +2,6 @@
description: Restricting access to your registry using a nginx proxy description: Restricting access to your registry using a nginx proxy
keywords: registry, on-prem, images, tags, repository, distribution, nginx, proxy, authentication, TLS, recipe, advanced keywords: registry, on-prem, images, tags, repository, distribution, nginx, proxy, authentication, TLS, recipe, advanced
title: Authenticate proxy with nginx title: Authenticate proxy with nginx
redirect_from:
- /registry/nginx/
--- ---
## Use-case ## Use-case
@ -19,7 +17,7 @@ mechanism fronting their internal http portal.
If you just want authentication for your registry, and are happy maintaining If you just want authentication for your registry, and are happy maintaining
users access separately, you should really consider sticking with the native users access separately, you should really consider sticking with the native
[basic auth registry feature](../deploying.md#native-basic-auth). [basic auth registry feature](/about/deploying#native-basic-auth).
### Solution ### Solution
@ -52,7 +50,7 @@ complexity is required.
For instance, Amazon's Elastic Load Balancer (ELB) in HTTPS mode already sets For instance, Amazon's Elastic Load Balancer (ELB) in HTTPS mode already sets
the following client header: the following client header:
``` ```none
X-Real-IP X-Real-IP
X-Forwarded-For X-Forwarded-For
X-Forwarded-Proto X-Forwarded-Proto
@ -74,132 +72,136 @@ properly. For more information, see
## Setting things up ## Setting things up
Review the [requirements](index.md#requirements), then follow these steps. Review the [requirements](../#requirements), then follow these steps.
1. Create the required directories 1. Create the required directories
```console ```console
$ mkdir -p auth data $ mkdir -p auth data
``` ```
2. Create the main nginx configuration. Paste this code block into a new file called `auth/nginx.conf`: 2. Create the main nginx configuration. Paste this code block into a new file called `auth/nginx.conf`:
```conf ```conf
events { events {
worker_connections 1024; worker_connections 1024;
} }
http { http {
upstream docker-registry { upstream docker-registry {
server registry:5000; server registry:5000;
} }
## Set a variable to help us decide if we need to add the ## Set a variable to help us decide if we need to add the
## 'Docker-Distribution-Api-Version' header. ## 'Docker-Distribution-Api-Version' header.
## The registry always sets this header. ## The registry always sets this header.
## In the case of nginx performing auth, the header is unset ## In the case of nginx performing auth, the header is unset
## since nginx is auth-ing before proxying. ## since nginx is auth-ing before proxying.
map $upstream_http_docker_distribution_api_version $docker_distribution_api_version { map $upstream_http_docker_distribution_api_version $docker_distribution_api_version {
'' 'registry/2.0'; '' 'registry/2.0';
} }
server { server {
listen 443 ssl; listen 443 ssl;
server_name myregistrydomain.com; server_name myregistrydomain.com;
# SSL # SSL
ssl_certificate /etc/nginx/conf.d/domain.crt; ssl_certificate /etc/nginx/conf.d/domain.crt;
ssl_certificate_key /etc/nginx/conf.d/domain.key; ssl_certificate_key /etc/nginx/conf.d/domain.key;
# Recommendations from https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html # Recommendations from https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html
ssl_protocols TLSv1.1 TLSv1.2; ssl_protocols TLSv1.1 TLSv1.2;
ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH'; ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';
ssl_prefer_server_ciphers on; ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m; ssl_session_cache shared:SSL:10m;
# disable any limits to avoid HTTP 413 for large image uploads # disable any limits to avoid HTTP 413 for large image uploads
client_max_body_size 0; client_max_body_size 0;
# required to avoid HTTP 411: see Issue #1486 (https://github.com/moby/moby/issues/1486) # required to avoid HTTP 411: see Issue #1486 (https://github.com/moby/moby/issues/1486)
chunked_transfer_encoding on; chunked_transfer_encoding on;
location /v2/ { location /v2/ {
# Do not allow connections from docker 1.5 and earlier # 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 # 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 ).*$" ) { if ($http_user_agent ~ "^(docker\/1\.(3|4|5(?!\.[0-9]-dev))|Go ).*$" ) {
return 404; return 404;
} }
# To add basic authentication to v2 use auth_basic setting. # To add basic authentication to v2 use auth_basic setting.
auth_basic "Registry realm"; auth_basic "Registry realm";
auth_basic_user_file /etc/nginx/conf.d/nginx.htpasswd; auth_basic_user_file /etc/nginx/conf.d/nginx.htpasswd;
## If $docker_distribution_api_version is empty, the header is not added. ## If $docker_distribution_api_version is empty, the header is not added.
## See the map directive above where this variable is defined. ## See the map directive above where this variable is defined.
add_header 'Docker-Distribution-Api-Version' $docker_distribution_api_version always; add_header 'Docker-Distribution-Api-Version' $docker_distribution_api_version always;
proxy_pass http://docker-registry; proxy_pass http://docker-registry;
proxy_set_header Host $http_host; # required for docker client's sake 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-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-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 900; proxy_read_timeout 900;
} }
} }
} }
``` ```
3. Create a password file `auth/nginx.htpasswd` for "testuser" and "testpassword". 3. Create a password file `auth/nginx.htpasswd` for "testuser" and "testpassword".
```console ```console
$ docker run --rm --entrypoint htpasswd registry:2 -Bbn testuser testpassword > auth/nginx.htpasswd $ 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. > **Note**: If you do not want to use `bcrypt`, you can omit the `-B` parameter.
4. Copy your certificate files to the `auth/` directory. 4. Copy your certificate files to the `auth/` directory.
```console ```console
$ cp domain.crt auth $ cp domain.crt auth
$ cp domain.key auth $ cp domain.key auth
``` ```
5. Create the compose file. Paste the following YAML into a new file called `docker-compose.yml`. 5. Create the compose file. Paste the following YAML into a new file called `docker-compose.yml`.
```yaml ```yaml
version: "3" version: "3"
services: services:
nginx: nginx:
# Note : Only nginx:alpine supports bcrypt. # Note : Only nginx:alpine supports bcrypt.
# If you don't need to use bcrypt, you can use a different tag. # If you don't need to use bcrypt, you can use a different tag.
# Ref. https://github.com/nginxinc/docker-nginx/issues/29 # Ref. https://github.com/nginxinc/docker-nginx/issues/29
image: "nginx:alpine" image: "nginx:alpine"
ports: ports:
- 5043:443 - 5043:443
depends_on: depends_on:
- registry - registry
volumes: volumes:
- ./auth:/etc/nginx/conf.d - ./auth:/etc/nginx/conf.d
- ./auth/nginx.conf:/etc/nginx/nginx.conf:ro - ./auth/nginx.conf:/etc/nginx/nginx.conf:ro
registry: registry:
image: registry:2 image: registry:2
volumes: volumes:
- ./data:/var/lib/registry - ./data:/var/lib/registry
``` ```
## Starting and stopping ## Starting and stopping
Now, start your stack: Now, start your stack:
docker-compose up -d ```consonle
$ docker-compose up -d
```
Login with a "push" authorized user (using `testuser` and `testpassword`), then Login with a "push" authorized user (using `testuser` and `testpassword`), then
tag and push your first image: tag and push your first image:
docker login -u=testuser -p=testpassword -e=root@example.ch myregistrydomain.com:5043 ```console
docker tag ubuntu myregistrydomain.com:5043/test $ docker login -u=testuser -p=testpassword -e=root@example.ch myregistrydomain.com:5043
docker push myregistrydomain.com:5043/test $ docker tag ubuntu myregistrydomain.com:5043/test
docker pull myregistrydomain.com:5043/test $ docker push myregistrydomain.com:5043/test
$ docker pull myregistrydomain.com:5043/test
```

54
docs/content/recipes/osx-setup-guide.md
View file

@ -26,49 +26,65 @@ If you know, safely skip to the next section.
If you don't, the TLDR is: If you don't, the TLDR is:
bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer) ```console
source ~/.gvm/scripts/gvm $ bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)
gvm install go1.4.2 $ source ~/.gvm/scripts/gvm
gvm use go1.4.2 $ 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). If you want to understand, you should read [How to Write Go Code](https://golang.org/doc/code.html).
## Checkout the source tree ## Checkout the source tree
mkdir -p $GOPATH/src/github.com/distribution ```console
git clone https://github.com/distribution/distribution.git $GOPATH/src/github.com/distribution/distribution $ mkdir -p $GOPATH/src/github.com/distribution
cd $GOPATH/src/github.com/distribution/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 ## Build the binary
GOPATH=$(PWD)/Godeps/_workspace:$GOPATH make binaries ```console
sudo mkdir -p /usr/local/libexec $ GOPATH=$(PWD)/Godeps/_workspace:$GOPATH make binaries
sudo cp bin/registry /usr/local/libexec/registry $ sudo mkdir -p /usr/local/libexec
$ sudo cp bin/registry /usr/local/libexec/registry
```
## Setup ## Setup
Copy the registry configuration file in place: Copy the registry configuration file in place:
mkdir /Users/Shared/Registry ```console
cp docs/osx/config.yml /Users/Shared/Registry/config.yml $ mkdir /Users/Shared/Registry
$ cp docs/osx/config.yml /Users/Shared/Registry/config.yml
```
## Run the registry under launchd ## Run the registry under launchd
Copy the registry plist into place: Copy the registry plist into place:
plutil -lint docs/recipes/osx/com.docker.registry.plist ```console
cp docs/recipes/osx/com.docker.registry.plist ~/Library/LaunchAgents/ $ plutil -lint docs/recipes/osx/com.docker.registry.plist
chmod 644 ~/Library/LaunchAgents/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: Start the registry:
launchctl load ~/Library/LaunchAgents/com.docker.registry.plist ```console
$ launchctl load ~/Library/LaunchAgents/com.docker.registry.plist
```
### Restart the registry service ### Restart the registry service
launchctl stop com.docker.registry ```console
launchctl start com.docker.registry $ launchctl stop com.docker.registry
$ launchctl start com.docker.registry
```
### Unload the registry service ### Unload the registry service
launchctl unload ~/Library/LaunchAgents/com.docker.registry.plist ```console
$ launchctl unload ~/Library/LaunchAgents/com.docker.registry.plist
```

15
docs/content/recipes/systemd.md
View file

@ -7,8 +7,9 @@ title: Start registry via systemd
## Use-case ## Use-case
Using systemd to manage containers can make service discovery and maintenance easier 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: can start the registry with socket-activation, providing additional security options:
* Run as non-root and expose on a low-numbered socket (< 1024) * Run as non-root and expose on a low-numbered socket (< 1024)
* Run with `--network=none` * Run with `--network=none`
@ -18,7 +19,8 @@ When deploying the registry via Docker, a simple service file can be used to man
the registry: the registry:
registry.service registry.service
```
```ini
[Unit] [Unit]
Description=Docker registry Description=Docker registry
After=docker.service After=docker.service
@ -40,7 +42,7 @@ WantedBy=multi-user.target
In this case, the registry will store images in the named-volume `registry`. 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 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. the case of issues.
### Podman ### Podman
@ -50,7 +52,7 @@ socket-activation of containers.
#### Create service file #### Create service file
``` ```sh
podman create --name registry --network=none -v registry:/var/lib/registry registry:2 podman create --name registry --network=none -v registry:/var/lib/registry registry:2
podman generate systemd --name --new registry > registry.service podman generate systemd --name --new registry > registry.service
``` ```
@ -58,7 +60,8 @@ podman generate systemd --name --new registry > registry.service
#### Create socket file #### Create socket file
registry.socket registry.socket
```
```ini
[Unit] [Unit]
Description=container registry Description=container registry
@ -71,7 +74,7 @@ WantedBy=sockets.target
### Installation ### 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 often include additional setup steps that are beyond the scope of this recipe, whereas
for Podman, rootless containers generally work out of the box. for Podman, rootless containers generally work out of the box.

8
docs/content/spec/_index.md
View file

@ -6,7 +6,7 @@ keywords: registry, service, images, repository, json
# Docker Registry Reference # Docker Registry Reference
* [HTTP API V2](api.md) * [HTTP API V2](api)
* [Storage Driver](https://docs.docker.com/registry/storage-drivers/) * [Storage Driver](/storage-drivers/)
* [Token Authentication Specification](auth/token.md) * [Token Authentication Specification](auth/token)
* [Token Authentication Implementation](auth/jwt.md) * [Token Authentication Implementation](auth/jwt)

1088
docs/content/spec/api.md
View file

File diff suppressed because it is too large Load diff

2
docs/content/spec/api.md.tmpl
View file

@ -2,7 +2,7 @@
title: "HTTP API V2" title: "HTTP API V2"
description: "Specification for the Registry API." description: "Specification for the Registry API."
keywords: registry, on-prem, images, tags, repository, distribution, api, advanced keywords: registry, on-prem, images, tags, repository, distribution, api, advanced
redirect_from: aliases:
- /reference/api/registry_api/ - /reference/api/registry_api/
--- ---

8
docs/content/spec/auth/_index.md
View file

@ -6,7 +6,7 @@ keywords: registry, on-prem, images, tags, repository, distribution, authenticat
# Docker Registry v2 authentication # Docker Registry v2 authentication
See the [Token Authentication Specification](token.md), See the [Token Authentication Specification](token),
[Token Authentication Implementation](jwt.md), [Token Authentication Implementation](jwt),
[Token Scope Documentation](scope.md), [Token Scope Documentation](scope),
[OAuth2 Token Authentication](oauth.md) for more information. [OAuth2 Token Authentication](oauth) for more information.

6
docs/content/spec/auth/oauth.md
View file

@ -12,7 +12,7 @@ reference for the protocol and HTTP endpoints described here.
**Note**: Not all token servers implement oauth2. If the request to the endpoint **Note**: Not all token servers implement oauth2. If the request to the endpoint
returns `404` using the HTTP `POST` method, refer to returns `404` using the HTTP `POST` method, refer to
[Token Documentation](token.md) for using the HTTP `GET` method supported by all [Token Documentation](../token) for using the HTTP `GET` method supported by all
token servers. token servers.
## Refresh token format ## Refresh token format
@ -161,7 +161,7 @@ Content-Type: application/x-www-form-urlencoded
#### Example getting refresh token #### Example getting refresh token
``` ```none
POST /token HTTP/1.1 POST /token HTTP/1.1
Host: auth.docker.io Host: auth.docker.io
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
@ -176,7 +176,7 @@ Content-Type: application/json
#### Example refreshing an Access Token #### Example refreshing an Access Token
``` ```none
POST /token HTTP/1.1 POST /token HTTP/1.1
Host: auth.docker.io Host: auth.docker.io
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded

23
docs/content/spec/auth/scope.md
View file

@ -41,10 +41,11 @@ is authorized for a specific resource.
#### Resource Class #### Resource Class
> [!WARNING] {{< hint type=warning >}}
> Resource Class is deprecated and ignored. Resource Class is deprecated and ignored.
> `repository` and `repository(plugin)` are considered equal when authorizing a token. `repository` and `repository(plugin)` are considered equal when authorizing a token.
> Authorization services should no longer return scopes with a resource class. Authorization services should no longer return scopes with a resource class.
{{< /hint >}}
The resource type might have a resource class which further classifies the The resource type might have a resource class which further classifies the
the resource name within the resource type. A class is not required and the resource name within the resource type. A class is not required and
@ -108,11 +109,13 @@ Full reference grammar is defined
[here](https://pkg.go.dev/github.com/distribution/distribution/reference). Currently [here](https://pkg.go.dev/github.com/distribution/distribution/reference). Currently
the scope name grammar is a subset of the reference grammar. the scope name grammar is a subset of the reference grammar.
> **NOTE:** that the `resourcename` may contain one `:` due to a possible port {{< hint type=note >}}
> number in the hostname component of the `resourcename`, so a naive Note that the `resourcename` may contain one `:` due to a possible port
> implementation that interprets the first three `:`-delimited tokens of a number in the hostname component of the `resourcename`, so a naive
> `scope` to be the `resourcetype`, `resourcename`, and a list of `action` implementation that interprets the first three `:`-delimited tokens of a
> would be insufficient. `scope` to be the `resourcetype`, `resourcename`, and a list of `action`
would be insufficient.
{{< /hint >}}
## Resource Provider Use ## Resource Provider Use
@ -141,7 +144,7 @@ Each JWT access token may only have a single subject and audience but multiple
resource scopes. The subject and audience are put into standard JWT fields resource scopes. The subject and audience are put into standard JWT fields
`sub` and `aud`. The resource scope is put into the `access` field. The `sub` and `aud`. The resource scope is put into the `access` field. The
structure of the access field can be seen in the structure of the access field can be seen in the
[jwt documentation](jwt.md). [jwt documentation](../jwt).
## Refresh Tokens ## Refresh Tokens

4
docs/content/spec/auth/token.md
View file

@ -8,7 +8,7 @@ keywords: registry, on-prem, images, tags, repository, distribution, Bearer auth
This document outlines the v2 Docker registry authentication scheme: This document outlines the v2 Docker registry authentication scheme:
![v2 registry auth](../images/v2-registry-auth.png) ![v2 registry auth](/images/v2-registry-auth.png)
1. Attempt to begin a push/pull operation with the registry. 1. Attempt to begin a push/pull operation with the registry.
2. If the registry requires authorization it will return a `401 Unauthorized` 2. If the registry requires authorization it will return a `401 Unauthorized`
@ -191,7 +191,7 @@ https://auth.docker.io/token?service=registry.docker.io&scope=repository:samalba
The token server should first attempt to authenticate the client using any The token server should first attempt to authenticate the client using any
authentication credentials provided with the request. From Docker 1.11 the authentication credentials provided with the request. From Docker 1.11 the
Docker engine supports both Basic Authentication and [OAuth2](oauth.md) for Docker engine supports both Basic Authentication and [OAuth2](../oauth) for
getting tokens. Docker 1.10 and before, the registry client in the Docker Engine getting tokens. Docker 1.10 and before, the registry client in the Docker Engine
only supports Basic Authentication. If an attempt to authenticate to the token only supports Basic Authentication. If an attempt to authenticate to the token
server fails, the token server should return a `401 Unauthorized` response server fails, the token server should return a `401 Unauthorized` response

10
docs/content/spec/deprecated-schema-v1.md
View file

@ -1,10 +1,9 @@
--- ---
title: Update deprecated schema image manifest version 2, v1 images title: Image manifest version 2, schema 1
description: Update deprecated schema v1 iamges description: Update deprecated schema v1 images
keywords: registry, on-prem, images, tags, repository, distribution, api, advanced, manifest keywords: registry, on-prem, images, tags, repository, distribution, api, advanced, manifest
--- ---
## Image manifest version 2, schema 1
With the release of image manifest version 2, schema 2, image manifest version With the release of image manifest version 2, schema 2, image manifest version
2, schema 1 has been deprecated. This could lead to compatibility and 2, schema 1 has been deprecated. This could lead to compatibility and
vulnerability issues in images that haven't been updated to image manifest vulnerability issues in images that haven't been updated to image manifest
@ -17,7 +16,7 @@ associated with the deprecated image manifest that will block your image from
running successfully. A list of possible methods to help update your image is running successfully. A list of possible methods to help update your image is
also included below. also included below.
### Update to image manifest version 2, schema 2 ## Update to image manifest version 2, schema 2
One way to upgrade an image from image manifest version 2, schema 1 to One way to upgrade an image from image manifest version 2, schema 1 to
schema 2 is to `docker pull` the image and then `docker push` the image with a schema 2 is to `docker pull` the image and then `docker push` the image with a
@ -29,8 +28,7 @@ manifest format, but does not update the contents within the image. Images
using manifest version 2, schema 1 may contain unpatched vulnerabilities. We using manifest version 2, schema 1 may contain unpatched vulnerabilities. We
recommend looking for an alternative image or rebuilding it. recommend looking for an alternative image or rebuilding it.
## Update FROM statement
### Update FROM statement
You can rebuild the image by updating the `FROM` statement in your You can rebuild the image by updating the `FROM` statement in your
`Dockerfile`. If your image manifest is out-of-date, there is a chance the `Dockerfile`. If your image manifest is out-of-date, there is a chance the

2
docs/content/spec/implementations.md
View file

@ -1,5 +1,5 @@
--- ---
published: false draft: true
--- ---
# Distribution API Implementations # Distribution API Implementations

2
docs/content/spec/json.md
View file

@ -1,5 +1,5 @@
--- ---
published: false draft: true
title: "Docker Distribution JSON Canonicalization" title: "Docker Distribution JSON Canonicalization"
description: "Explains registry JSON objects" description: "Explains registry JSON objects"
keywords: ["registry, service, images, repository, json"] keywords: ["registry, service, images, repository, json"]

16
docs/content/spec/manifest-v2-2.md
View file

@ -1,5 +1,5 @@
--- ---
title: "Image Manifest V 2, Schema 2 " title: "Image Manifest V 2, Schema 2"
description: "image manifest for the Registry." description: "image manifest for the Registry."
keywords: registry, on-prem, images, tags, repository, distribution, api, advanced, manifest keywords: registry, on-prem, images, tags, repository, distribution, api, advanced, manifest
--- ---
@ -10,7 +10,7 @@ This document outlines the format of the V2 image manifest, schema version 2.
The original (and provisional) image manifest for V2 (schema 1), was introduced The original (and provisional) image manifest for V2 (schema 1), was introduced
in the Docker daemon in the [v1.3.0 in the Docker daemon in the [v1.3.0
release](https://github.com/docker/docker/commit/9f482a66ab37ec396ac61ed0c00d59122ac07453) release](https://github.com/docker/docker/commit/9f482a66ab37ec396ac61ed0c00d59122ac07453)
and is specified in the [schema 1 manifest definition](manifest-v2-1.md) and is now deprecated.
This second schema version has two primary goals. The first is to allow This second schema version has two primary goals. The first is to allow
multi-architecture images, through a "fat manifest" which references image multi-architecture images, through a "fat manifest" which references image
@ -71,7 +71,7 @@ image manifest based on the Content-Type returned in the HTTP response.
- **`digest`** *string* - **`digest`** *string*
The digest of the content, as defined by the The digest of the content, as defined by the
[Registry V2 HTTP API Specificiation](api.md#digest-parameter). [Registry V2 HTTP API Specificiation](../api#digest-parameter).
- **`platform`** *object* - **`platform`** *object*
@ -113,7 +113,8 @@ image manifest based on the Content-Type returned in the HTTP response.
## Example Manifest List ## Example Manifest List
*Example showing a simple manifest list pointing to image manifests for two platforms:* Example showing a simple manifest list pointing to image manifests for two platforms:
```json ```json
{ {
"schemaVersion": 2, "schemaVersion": 2,
@ -186,7 +187,7 @@ image. It's the direct replacement for the schema-1 manifest.
- **`digest`** *string* - **`digest`** *string*
The digest of the content, as defined by the The digest of the content, as defined by the
[Registry V2 HTTP API Specificiation](api.md#digest-parameter). [Registry V2 HTTP API Specificiation](../api#digest-parameter).
- **`layers`** *array* - **`layers`** *array*
@ -212,7 +213,7 @@ image. It's the direct replacement for the schema-1 manifest.
- **`digest`** *string* - **`digest`** *string*
The digest of the content, as defined by the The digest of the content, as defined by the
[Registry V2 HTTP API Specificiation](api.md#digest-parameter). [Registry V2 HTTP API Specificiation](../api#digest-parameter).
- **`urls`** *array* - **`urls`** *array*
@ -222,7 +223,8 @@ image. It's the direct replacement for the schema-1 manifest.
## Example Image Manifest ## Example Image Manifest
*Example showing an image manifest:* Example showing an image manifest:
```json ```json
{ {
"schemaVersion": 2, "schemaVersion": 2,

7
docs/content/spec/menu.md
View file

@ -1,7 +0,0 @@
---
title: "Reference"
description: "Explains registry JSON objects"
keywords: registry, service, images, repository, json
type: "menu"
identifier: "smn_registry_ref"
---

25
docs/content/storage-drivers/_index.md
View file

@ -1,8 +1,6 @@
--- ---
description: Explains how to use storage drivers description: Explains how to use storage drivers
keywords: registry, on-prem, images, tags, repository, distribution, storage drivers, advanced keywords: registry, on-prem, images, tags, repository, distribution, storage drivers, advanced
redirect_from:
- /registry/storagedrivers/
title: Registry storage driver title: Registry storage driver
--- ---
@ -12,11 +10,11 @@ This document describes the registry storage driver model, implementation, and e
This storage driver package comes bundled with several drivers: This storage driver package comes bundled with several drivers:
- [inmemory](inmemory.md): A temporary storage driver using a local inmemory map. This exists solely for reference and testing. - [inmemory](inmemory): A temporary storage driver using a local inmemory map. This exists solely for reference and testing.
- [filesystem](filesystem.md): A local storage driver configured to use a directory tree in the local filesystem. - [filesystem](filesystem): A local storage driver configured to use a directory tree in the local filesystem.
- [s3](s3.md): A driver storing objects in an Amazon Simple Storage Service (S3) bucket. - [s3](s3): A driver storing objects in an Amazon Simple Storage Service (S3) bucket.
- [azure](azure.md): A driver storing objects in [Microsoft Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/). - [azure](azure): A driver storing objects in [Microsoft Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/).
- [gcs](gcs.md): A driver storing objects in a [Google Cloud Storage](https://cloud.google.com/storage/) bucket. - [gcs](gcs): A driver storing objects in a [Google Cloud Storage](https://cloud.google.com/storage/) bucket.
- oss: *NO LONGER SUPPORTED* - oss: *NO LONGER SUPPORTED*
- swift: *NO LONGER SUPPORTED* - swift: *NO LONGER SUPPORTED*
@ -41,16 +39,17 @@ with a driver name and parameters map. If no such storage driver can be found,
## Driver contribution ## Driver contribution
New storage drivers are not currently being accepted. New storage drivers are not currently being accepted.
See https://github.com/distribution/distribution/issues/3988 for discussion. See <https://github.com/distribution/distribution/issues/3988> for discussion.
There are forks of this repo that implement custom storage drivers. There are forks of this repo that implement custom storage drivers.
These are not supported by the OCI distribution project. These are not supported by the OCI distribution project.
The known forks are: The known forks are:
- Storj DCS: https://github.com/storj/docker-registry
- HuaweiCloud OBS: https://github.com/setoru/distribution/tree/obs - Storj DCS: <https://github.com/storj/docker-registry>
- us3: https://github.com/lambertxiao/distribution/tree/main - HuaweiCloud OBS: <https://github.com/setoru/distribution/tree/obs>
- Baidu BOS: https://github.com/dolfly/distribution/tree/bos - us3: <https://github.com/lambertxiao/distribution/tree/main>
- HDFS: https://github.com/haosdent/distribution/tree/master - Baidu BOS: <https://github.com/dolfly/distribution/tree/bos>
- HDFS: <https://github.com/haosdent/distribution/tree/master>
### Writing new storage drivers ### Writing new storage drivers

5
docs/content/storage-drivers/gcs.md
View file

@ -15,5 +15,6 @@ An implementation of the `storagedriver.StorageDriver` interface which uses Goog
| `rootdirectory` | no | The root directory tree in which all registry files are stored. Defaults to the empty string (bucket root). If a prefix is used, the path `bucketname/<prefix>` has to be pre-created before starting the registry. The prefix is applied to all Google Cloud Storage keys to allow you to segment data in your bucket if necessary.| | `rootdirectory` | no | The root directory tree in which all registry files are stored. Defaults to the empty string (bucket root). If a prefix is used, the path `bucketname/<prefix>` has to be pre-created before starting the registry. The prefix is applied to all Google Cloud Storage keys to allow you to segment data in your bucket if necessary.|
| `chunksize` | no (default 5242880) | This is the chunk size used for uploading large blobs, must be a multiple of 256*1024. | | `chunksize` | no (default 5242880) | This is the chunk size used for uploading large blobs, must be a multiple of 256*1024. |
**Note:** Instead of a key file you can use [Google Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials). {{< hint type=note >}}
Instead of a key file you can use [Google Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials).
{{< /hint >}}

6
docs/content/storage-drivers/inmemory.md
View file

@ -7,9 +7,11 @@ title: In-memory storage driver (testing only)
For purely tests purposes, you can use the `inmemory` storage driver. This For purely tests purposes, you can use the `inmemory` storage driver. This
driver is an implementation of the `storagedriver.StorageDriver` interface which driver is an implementation of the `storagedriver.StorageDriver` interface which
uses local memory for object storage. If you would like to run a registry from uses local memory for object storage. If you would like to run a registry from
volatile memory, use the [`filesystem` driver](filesystem.md) on a ramdisk. volatile memory, use the [`filesystem` driver](../filesystem) on a ramdisk.
**IMPORTANT**: This storage driver *does not* persist data across runs. This is why it is only suitable for testing. *Never* use this driver in production. {{< hint type=important >}}
This storage driver *does not* persist data across runs. This is why it is only suitable for testing. *Never* use this driver in production.
{{< /hint >}}
## Parameters ## Parameters

16
docs/content/storage-drivers/s3.md
View file

@ -11,8 +11,8 @@ Amazon S3 or S3 compatible services for object storage.
| Parameter | Required | Description | | Parameter | Required | Description |
|:--------------|:---------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:--------------|:---------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `accesskey` | no | Your AWS Access Key. If you use [IAM roles](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html), omit to fetch temporary credentials from IAM. | | `accesskey` | no | Your AWS Access Key. If you use [IAM roles](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html), omit to fetch temporary credentials from IAM. |
| `secretkey` | no | Your AWS Secret Key. If you use [IAM roles](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html), omit to fetch temporary credentials from IAM. | | `secretkey` | no | Your AWS Secret Key. If you use [IAM roles](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html), omit to fetch temporary credentials from IAM. |
| `region` | yes | The AWS region in which your bucket exists. | | `region` | yes | The AWS region in which your bucket exists. |
| `regionendpoint` | no | Endpoint for S3 compatible storage services (Minio, etc). | | `regionendpoint` | no | Endpoint for S3 compatible storage services (Minio, etc). |
| `forcepathstyle` | no | To enable path-style addressing when the value is set to `true`. The default is `true`. | | `forcepathstyle` | no | To enable path-style addressing when the value is set to `true`. The default is `true`. |
@ -30,10 +30,10 @@ Amazon S3 or S3 compatible services for object storage.
> **Note** You can provide empty strings for your access and secret keys to run the driver > **Note** You can provide empty strings for your access and secret keys to run the driver
> on an ec2 instance and handles authentication with the instance's credentials. If you > on an ec2 instance and handles authentication with the instance's credentials. If you
> use [IAM roles](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html), > use [IAM roles](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html),
> omit these keys to fetch temporary credentials from IAM. > omit these keys to fetch temporary credentials from IAM.
`region`: The name of the aws region in which you would like to store objects (for example `us-east-1`). For a list of regions, see [Regions, Availability Zones, and Local Zones](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). `region`: The name of the aws region in which you would like to store objects (for example `us-east-1`). For a list of regions, see [Regions, Availability Zones, and Local Zones](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html).
`regionendpoint`: (optional) Endpoint URL for S3 compatible APIs. This should not be provided when using Amazon S3. `regionendpoint`: (optional) Endpoint URL for S3 compatible APIs. This should not be provided when using Amazon S3.
@ -55,7 +55,7 @@ Amazon S3 or S3 compatible services for object storage.
`storageclass`: (optional) The storage class applied to each registry file. Defaults to STANDARD. Valid options are STANDARD and REDUCED_REDUNDANCY. `storageclass`: (optional) The storage class applied to each registry file. Defaults to STANDARD. Valid options are STANDARD and REDUCED_REDUNDANCY.
`objectacl`: (optional) The canned object ACL to be applied to each registry object. Defaults to `private`. If you are using a bucket owned by another AWS account, it is recommended that you set this to `bucket-owner-full-control` so that the bucket owner can access your objects. Other valid options are available in the [AWS S3 documentation](http://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl). `objectacl`: (optional) The canned object ACL to be applied to each registry object. Defaults to `private`. If you are using a bucket owned by another AWS account, it is recommended that you set this to `bucket-owner-full-control` so that the bucket owner can access your objects. Other valid options are available in the [AWS S3 documentation](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl).
`loglevel`: (optional) Valid values are: `off` (default), `debug`, `debugwithsigning`, `debugwithhttpbody`, `debugwithrequestretries`, `debugwithrequesterrors` and `debugwitheventstreambody`. See the [AWS SDK for Go API reference](https://docs.aws.amazon.com/sdk-for-go/api/aws/#LogLevelType) for details. `loglevel`: (optional) Valid values are: `off` (default), `debug`, `debugwithsigning`, `debugwithhttpbody`, `debugwithrequestretries`, `debugwithrequesterrors` and `debugwitheventstreambody`. See the [AWS SDK for Go API reference](https://docs.aws.amazon.com/sdk-for-go/api/aws/#LogLevelType) for details.
@ -91,7 +91,7 @@ The following AWS policy is required by the registry for push and pull. Make sur
} }
``` ```
See [the S3 policy documentation](http://docs.aws.amazon.com/AmazonS3/latest/dev/mpuAndPermissions.html) for more details. See [the S3 policy documentation](https://docs.aws.amazon.com/AmazonS3/latest/dev/mpuAndPermissions.html) for more details.
# CloudFront as Middleware with S3 backend # CloudFront as Middleware with S3 backend
@ -112,7 +112,7 @@ to see whether you need CloudFront or S3 Transfer Acceleration.
If you are unfamiliar with creating a CloudFront distribution, see [Getting If you are unfamiliar with creating a CloudFront distribution, see [Getting
Started with Started with
Cloudfront](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GettingStarted.html). Cloudfront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GettingStarted.html).
Defaults can be kept in most areas except: Defaults can be kept in most areas except:
@ -162,4 +162,4 @@ middleware:
A CloudFront key-pair is required for all AWS accounts needing access to your A CloudFront key-pair is required for all AWS accounts needing access to your
CloudFront distribution. You must have access to your AWS account's root credentials to create the required Cloudfront keypair. For information, see [Creating CloudFront Key CloudFront distribution. You must have access to your AWS account's root credentials to create the required Cloudfront keypair. For information, see [Creating CloudFront Key
Pairs](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html#private-content-creating-cloudfront-key-pairs). Pairs](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html#private-content-creating-cloudfront-key-pairs).

2
docs/hugo.yaml
View file

@ -1,4 +1,4 @@
baseURL: https://example.com/ baseURL: /
languageCode: en-us languageCode: en-us
title: CNCF Distribution title: CNCF Distribution
theme: hugo-geekdoc theme: hugo-geekdoc

0
docs/content/images/notifications.gliffy → docs/static/images/notifications.gliffy vendored
View file

0
docs/content/images/notifications.png → docs/static/images/notifications.png vendored
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 20 KiB

0
docs/content/images/notifications.svg → docs/static/images/notifications.svg vendored
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 31 KiB

0
docs/content/images/v2-registry-auth.png → docs/static/images/v2-registry-auth.png vendored
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB