From 908a1f14f5919cd2abd8d41f89cc635efbf0b8f8 Mon Sep 17 00:00:00 2001 From: John Mulhausen Date: Fri, 4 Nov 2016 15:38:40 -0700 Subject: [PATCH] Converges titles to imperative-form, front-matter based, and sentence-case (#438) Multiple title fixes, consistency fixes, convergence into metadata-based titles. --- docs/compatibility.md | 8 +--- docs/configuration.md | 8 +--- docs/deploying.md | 6 --- docs/deprecated.md | 8 +--- docs/garbage-collection.md | 9 +--- docs/help.md | 8 +--- docs/index.md | 30 +++++++------- docs/insecure.md | 8 +--- docs/introduction.md | 55 +++++++++++++++++-------- docs/notifications.md | 8 +--- docs/recipes/apache.md | 16 +++----- docs/recipes/index.md | 6 --- docs/recipes/mirror.md | 66 +++++++++++++++++++----------- docs/recipes/nginx.md | 54 ++++++++++++++---------- docs/recipes/osx-setup-guide.md | 7 +--- docs/spec/api.md | 7 +--- docs/spec/auth/index.md | 8 +--- docs/spec/auth/jwt.md | 11 +---- docs/spec/auth/oauth.md | 9 +--- docs/spec/auth/scope.md | 12 +----- docs/spec/auth/token.md | 21 ++++------ docs/spec/index.md | 8 +--- docs/spec/json.md | 7 +--- docs/spec/manifest-v2-1.md | 7 +--- docs/spec/manifest-v2-2.md | 7 +--- docs/storage-drivers/azure.md | 5 --- docs/storage-drivers/filesystem.md | 5 --- docs/storage-drivers/gcs.md | 7 +--- docs/storage-drivers/index.md | 9 +--- docs/storage-drivers/inmemory.md | 7 +--- docs/storage-drivers/oss.md | 8 +--- docs/storage-drivers/s3.md | 30 +++++++++----- docs/storage-drivers/swift.md | 16 ++++---- 33 files changed, 193 insertions(+), 288 deletions(-) diff --git a/docs/compatibility.md b/docs/compatibility.md index 6d18ffc3..37f6d07a 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -2,15 +2,9 @@ description: describes get by digest pitfall keywords: - registry, manifest, images, tags, repository, distribution, digest -menu: - main: - parent: smn_registry_ref - weight: 9 -title: Compatibility +title: Registry compatibility --- -# Registry Compatibility - ## Synopsis *If a manifest is pulled by _digest_ from a registry 2.3 with Docker Engine 1.9 and older, and the manifest was pushed with Docker Engine 1.10, a security check diff --git a/docs/configuration.md b/docs/configuration.md index 72c95972..c71b8a33 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2,15 +2,9 @@ description: Explains how to configure a registry keywords: - registry, on-prem, images, tags, repository, distribution, configuration -menu: - main: - parent: smn_registry - weight: 4 -title: Configuring a registry +title: Registry configuration reference --- -# Registry Configuration Reference - The Registry configuration is based on a YAML file, detailed below. While it comes with sane default values out of the box, you are heavily encouraged to review it exhaustively before moving your systems to production. ## Override specific configuration options diff --git a/docs/deploying.md b/docs/deploying.md index 1aa42aa0..4f346186 100644 --- a/docs/deploying.md +++ b/docs/deploying.md @@ -2,15 +2,9 @@ description: Explains how to deploy a registry keywords: - registry, on-prem, images, tags, repository, distribution, deployment -menu: - main: - parent: smn_registry - weight: 3 title: Deploying a registry server --- -# Deploying a registry server - You need to [install Docker version 1.6.0 or newer](/engine/installation/index.md). ## Running on localhost diff --git a/docs/deprecated.md b/docs/deprecated.md index d30ff425..be971ce6 100644 --- a/docs/deprecated.md +++ b/docs/deprecated.md @@ -2,15 +2,9 @@ description: describes deprecated functionality keywords: - registry, manifest, images, signatures, repository, distribution, digest -menu: - main: - parent: smn_registry_ref - weight: 8 -title: Deprecated Features +title: Docker Registry deprecation --- -# Docker Registry Deprecation - This document details functionality or components which are deprecated within the registry. diff --git a/docs/garbage-collection.md b/docs/garbage-collection.md index d24bb77c..4d0467b2 100644 --- a/docs/garbage-collection.md +++ b/docs/garbage-collection.md @@ -2,15 +2,9 @@ description: High level discussion of garbage collection keywords: - registry, garbage, images, tags, repository, distribution -menu: - main: - parent: smn_registry_ref - weight: 4 -title: Garbage Collection +title: Garbage collection --- -# Garbage Collection - As of v2.4.0 a garbage collector command is included within the registry binary. This document describes what this command does and how and why it should be used. @@ -134,4 +128,3 @@ blob eligible for deletion: sha256:87192bdbe00f8f2a62527f36bb4c7c7f4eaf9307e4b87 blob eligible for deletion: sha256:b549a9959a664038fc35c155a95742cf12297672ca0ae35735ec027d55bf4e97 blob eligible for deletion: sha256:f251d679a7c61455f06d793e43c06786d7766c88b8c24edf242b2c08e3c3f599 ``` - diff --git a/docs/help.md b/docs/help.md index 8728924c..d73c76d8 100644 --- a/docs/help.md +++ b/docs/help.md @@ -2,15 +2,9 @@ description: Getting help with the Registry keywords: - registry, on-prem, images, tags, repository, distribution, help, 101, TL;DR -menu: - main: - parent: smn_registry - weight: 9 -title: Getting help +title: Get help --- -# Getting help - If you need help, or just want to chat, you can reach us: - on irc: `#docker-distribution` on freenode diff --git a/docs/index.md b/docs/index.md index 0a57a2d3..f3bd589c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,19 +4,14 @@ aliases: description: High-level overview of the Registry keywords: - registry, on-prem, images, tags, repository, distribution -menu: - main: - parent: smn_registry - weight: 1 -title: Registry Overview +title: Docker Registry --- -# Docker Registry - ## What it is -The Registry is a stateless, highly scalable server side application that stores and lets you distribute Docker images. -The Registry is open-source, under the permissive [Apache license](http://en.wikipedia.org/wiki/Apache_License). +The Registry is a stateless, highly scalable server side application that stores +and lets you distribute Docker images. The Registry is open-source, under the +permissive [Apache license](http://en.wikipedia.org/wiki/Apache_License). ## Why use it @@ -28,14 +23,19 @@ You should use the Registry if you want to: ## Alternatives -Users looking for a zero maintenance, ready-to-go solution are encouraged to head-over to the [Docker Hub](https://hub.docker.com), which provides a free-to-use, hosted Registry, plus additional features (organization accounts, automated builds, and more). +Users looking for a zero maintenance, ready-to-go solution are encouraged to +head-over to the [Docker Hub](https://hub.docker.com), which provides a +free-to-use, hosted Registry, plus additional features (organization accounts, +automated builds, and more). -Users looking for a commercially supported version of the Registry should look into [Docker Trusted Registry](/docker-trusted-registry/overview/). +Users looking for a commercially supported version of the Registry should look +into [Docker Trusted Registry](/docker-trusted-registry/overview/). ## Requirements -The Registry is compatible with Docker engine **version 1.6.0 or higher**. -If you really need to work with older Docker versions, you should look into the [old python registry](https://github.com/docker/docker-registry). +The Registry is compatible with Docker engine **version 1.6.0 or higher**. If +you really need to work with older Docker versions, you should look into the +[old python registry](https://github.com/docker/docker-registry). ## TL;DR @@ -65,4 +65,6 @@ Now stop your registry and remove all data ## Next -You should now read the [detailed introduction about the registry](introduction.md), or jump directly to [deployment instructions](deploying.md). +You should now read the [detailed introduction about the +registry](introduction.md), or jump directly to [deployment +instructions](deploying.md). diff --git a/docs/insecure.md b/docs/insecure.md index 0bb21458..d7d1ba8c 100644 --- a/docs/insecure.md +++ b/docs/insecure.md @@ -2,15 +2,9 @@ description: Deploying a Registry in an insecure fashion keywords: - registry, on-prem, images, tags, repository, distribution, insecure -menu: - main: - parent: smn_registry_ref - weight: 5 -title: Testing an insecure registry +title: Test an insecure registry --- -# Insecure Registry - While it's highly recommended to secure your registry using a TLS certificate issued by a known CA, you may alternatively decide to use self-signed certificates, or even use your registry over plain http. diff --git a/docs/introduction.md b/docs/introduction.md index f95be819..6b7e46e0 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -2,16 +2,11 @@ description: Explains what the Registry is, basic use cases and requirements keywords: - registry, on-prem, images, tags, repository, distribution, use cases, requirements -menu: - main: - parent: smn_registry - weight: 2 -title: Understanding the Registry +title: About Registry --- -# Understanding the Registry - -A registry is a storage and content delivery system, holding named Docker images, available in different tagged versions. +A registry is a storage and content delivery system, holding named Docker +images, available in different tagged versions. > Example: the image `distribution/registry`, with tags `2.0` and `2.1`. @@ -19,13 +14,24 @@ Users interact with a registry by using docker push and pull commands. > Example: `docker pull registry-1.docker.io/distribution/registry:2.1`. -Storage itself is delegated to drivers. The default storage driver is the local posix filesystem, which is suitable for development or small deployments. Additional cloud-based storage drivers like S3, Microsoft Azure, OpenStack Swift and Aliyun OSS are also supported. People looking into using other storage backends may do so by writing their own driver implementing the [Storage API](storage-drivers/index.md). +Storage itself is delegated to drivers. The default storage driver is the local +posix filesystem, which is suitable for development or small deployments. +Additional cloud-based storage drivers like S3, Microsoft Azure, OpenStack Swift +and Aliyun OSS are also supported. People looking into using other storage +backends may do so by writing their own driver implementing the [Storage +API](storage-drivers/index.md). -Since securing access to your hosted images is paramount, the Registry natively supports TLS and basic authentication. +Since securing access to your hosted images is paramount, the Registry natively +supports TLS and basic authentication. -The Registry GitHub repository includes additional information about advanced authentication and authorization methods. Only very large or public deployments are expected to extend the Registry in this way. +The Registry GitHub repository includes additional information about advanced +authentication and authorization methods. Only very large or public deployments +are expected to extend the Registry in this way. -Finally, the Registry ships with a robust [notification system](notifications.md), calling webhooks in response to activity, and both extensive logging and reporting, mostly useful for large installations that want to collect metrics. +Finally, the Registry ships with a robust [notification +system](notifications.md), calling webhooks in response to activity, and both +extensive logging and reporting, mostly useful for large installations that want +to collect metrics. ## Understanding image naming @@ -34,21 +40,36 @@ Image names as used in typical docker commands reflect their origin: * `docker pull ubuntu` instructs docker to pull an image named `ubuntu` from the official Docker Hub. This is simply a shortcut for the longer `docker pull docker.io/library/ubuntu` command * `docker pull myregistrydomain:port/foo/bar` instructs docker to contact the registry located at `myregistrydomain:port` to find the image `foo/bar` -You can find out more about the various Docker commands dealing with images in the [official Docker engine documentation](/engine/reference/commandline/cli.md). +You can find out more about the various Docker commands dealing with images in +the [official Docker engine +documentation](/engine/reference/commandline/cli.md). ## Use cases -Running your own Registry is a great solution to integrate with and complement your CI/CD system. In a typical workflow, a commit to your source revision control system would trigger a build on your CI system, which would then push a new image to your Registry if the build is successful. A notification from the Registry would then trigger a deployment on a staging environment, or notify other systems that a new image is available. +Running your own Registry is a great solution to integrate with and complement +your CI/CD system. In a typical workflow, a commit to your source revision +control system would trigger a build on your CI system, which would then push a +new image to your Registry if the build is successful. A notification from the +Registry would then trigger a deployment on a staging environment, or notify +other systems that a new image is available. -It's also an essential component if you want to quickly deploy a new image over a large cluster of machines. +It's also an essential component if you want to quickly deploy a new image over +a large cluster of machines. Finally, it's the best way to distribute images inside an isolated network. ## Requirements -You absolutely need to be familiar with Docker, specifically with regard to pushing and pulling images. You must understand the difference between the daemon and the cli, and at least grasp basic concepts about networking. +You absolutely need to be familiar with Docker, specifically with regard to +pushing and pulling images. You must understand the difference between the +daemon and the cli, and at least grasp basic concepts about networking. -Also, while just starting a registry is fairly easy, operating it in a production environment requires operational skills, just like any other service. You are expected to be familiar with systems availability and scalability, logging and log processing, systems monitoring, and security 101. Strong understanding of http and overall network communications, plus familiarity with golang are certainly useful as well for advanced operations or hacking. +Also, while just starting a registry is fairly easy, operating it in a +production environment requires operational skills, just like any other service. +You are expected to be familiar with systems availability and scalability, +logging and log processing, systems monitoring, and security 101. Strong +understanding of http and overall network communications, plus familiarity with +golang are certainly useful as well for advanced operations or hacking. ## Next diff --git a/docs/notifications.md b/docs/notifications.md index dd01a5b8..7f503e1b 100644 --- a/docs/notifications.md +++ b/docs/notifications.md @@ -2,15 +2,9 @@ description: Explains how to work with registry notifications keywords: - registry, on-prem, images, tags, repository, distribution, notifications, advanced -menu: - main: - parent: smn_registry - weight: 5 -title: Working with notifications +title: Work with notifications --- -# Notifications - The Registry supports sending webhook notifications in response to events happening within the registry. Notifications are sent in response to manifest pushes and pulls and layer pushes and pulls. These actions are serialized into diff --git a/docs/recipes/apache.md b/docs/recipes/apache.md index 1b503584..e74aa198 100644 --- a/docs/recipes/apache.md +++ b/docs/recipes/apache.md @@ -1,16 +1,10 @@ --- description: Restricting access to your registry using an apache proxy keywords: -- registry, on-prem, images, tags, repository, distribution, authentication, proxy, - apache, httpd, TLS, recipe, advanced -menu: - main: - parent: smn_recipes -title: Authenticating proxy with apache +- registry, on-prem, images, tags, repository, distribution, authentication, proxy, apache, httpd, TLS, recipe, advanced +title: Authenticate proxy with apache --- -# Authenticating proxy with apache - ## Use-case People already relying on an apache proxy to authenticate their users to other services might want to leverage it and have Registry communications tunneled through the same pipeline. @@ -19,7 +13,7 @@ Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO ### Alternatives -If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](../deploying.md#native-basic-auth). +If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](../deploying.md#native-basic-auth). ### Solution @@ -27,7 +21,7 @@ With the method presented here, you implement basic authentication for docker en While we use a simple htpasswd file as an example, any other apache authentication backend should be fairly easy to implement once you are done with the example. -We also implement push restriction (to a limited user group) for the sake of the example. Again, you should modify this to fit your mileage. +We also implement push restriction (to a limited user group) for the sake of the example. Again, you should modify this to fit your mileage. ### Gotchas @@ -200,7 +194,7 @@ Now, start your stack: docker-compose up -d -Login with a "push" authorized user (using `testuserpush` and `testpasswordpush`), then tag and push your first image: +Login with a "push" authorized user (using `testuserpush` and `testpasswordpush`), then tag and push your first image: docker login myregistrydomain.com:5043 docker tag ubuntu myregistrydomain.com:5043/test diff --git a/docs/recipes/index.md b/docs/recipes/index.md index 482a4894..ab6986a6 100644 --- a/docs/recipes/index.md +++ b/docs/recipes/index.md @@ -2,15 +2,9 @@ description: Fun stuff to do with your registry keywords: - registry, on-prem, images, tags, repository, distribution, recipes, advanced -menu: - main: - parent: smn_recipes - weight: -10 title: Recipes Overview --- -# Recipes - You will find here a list of "recipes", end-to-end scenarios for exotic or otherwise advanced use-cases. Most users are not expected to have a use for these. diff --git a/docs/recipes/mirror.md b/docs/recipes/mirror.md index 6e66f73a..cc40ae74 100644 --- a/docs/recipes/mirror.md +++ b/docs/recipes/mirror.md @@ -1,59 +1,76 @@ --- description: Setting-up a local mirror for Docker Hub images keywords: -- registry, on-prem, images, tags, repository, distribution, mirror, Hub, recipe, - advanced -menu: - main: - parent: smn_recipes -title: Mirroring Docker Hub +- registry, on-prem, images, tags, repository, distribution, mirror, Hub, recipe, advanced +title: Registry as a pull through cache --- -# Registry as a pull through cache - ## Use-case -If you have multiple instances of Docker running in your environment (e.g., multiple physical or virtual machines, all running the Docker daemon), each time one of them requires an image that it doesn’t have it will go out to the internet and fetch it from the public Docker registry. By running a local registry mirror, you can keep most of the redundant image fetch traffic on your local network. +If you have multiple instances of Docker running in your environment (e.g., +multiple physical or virtual machines, all running the Docker daemon), each time +one of them requires an image that it doesn’t have it will go out to the +internet and fetch it from the public Docker registry. By running a local +registry mirror, you can keep most of the redundant image fetch traffic on your +local network. ### Alternatives -Alternatively, if the set of images you are using is well delimited, you can simply pull them manually and push them to a simple, local, private registry. +Alternatively, if the set of images you are using is well delimited, you can +simply pull them manually and push them to a simple, local, private registry. -Furthermore, if your images are all built in-house, not using the Hub at all and relying entirely on your local registry is the simplest scenario. +Furthermore, if your images are all built in-house, not using the Hub at all and +relying entirely on your local registry is the simplest scenario. ### Gotcha -It's currently not possible to mirror another private registry. Only the central Hub can be mirrored. +It's currently not possible to mirror another private registry. Only the central +Hub can be mirrored. ### Solution -The Registry can be configured as a pull through cache. In this mode a Registry responds to all normal docker pull requests but stores all content locally. +The Registry can be configured as a pull through cache. In this mode a Registry +responds to all normal docker pull requests but stores all content locally. ## How does it work? -The first time you request an image from your local registry mirror, it pulls the image from the public Docker registry and stores it locally before handing it back to you. On subsequent requests, the local registry mirror is able to serve the image from its own storage. +The first time you request an image from your local registry mirror, it pulls +the image from the public Docker registry and stores it locally before handing +it back to you. On subsequent requests, the local registry mirror is able to +serve the image from its own storage. ### What if the content changes on the Hub? -When a pull is attempted with a tag, the Registry will check the remote to ensure if it has the latest version of the requested content. If it doesn't it will fetch the latest content and cache it. +When a pull is attempted with a tag, the Registry will check the remote to +ensure if it has the latest version of the requested content. If it doesn't it +will fetch the latest content and cache it. ### What about my disk? -In environments with high churn rates, stale data can build up in the cache. When running as a pull through cache the Registry will periodically remove old content to save disk space. Subsequent requests for removed content will cause a remote fetch and local re-caching. +In environments with high churn rates, stale data can build up in the cache. +When running as a pull through cache the Registry will periodically remove old +content to save disk space. Subsequent requests for removed content will cause a +remote fetch and local re-caching. -To ensure best performance and guarantee correctness the Registry cache should be configured to use the `filesystem` driver for storage. +To ensure best performance and guarantee correctness the Registry cache should +be configured to use the `filesystem` driver for storage. ## Running a Registry as a pull through cache -The easiest way to run a registry as a pull through cache is to run the official Registry image. +The easiest way to run a registry as a pull through cache is to run the official +Registry image. -Multiple registry caches can be deployed over the same back-end. A single registry cache will ensure that concurrent requests do not pull duplicate data, but this property will not hold true for a registry cache cluster. +Multiple registry caches can be deployed over the same back-end. A single +registry cache will ensure that concurrent requests do not pull duplicate data, +but this property will not hold true for a registry cache cluster. ### Configuring the cache -To configure a Registry to run as a pull through cache, the addition of a `proxy` section is required to the config file. +To configure a Registry to run as a pull through cache, the addition of a +`proxy` section is required to the config file. -In order to access private images on the Docker Hub, a username and password can be supplied. +In order to access private images on the Docker Hub, a username and password can +be supplied. proxy: remoteurl: https://registry-1.docker.io @@ -66,7 +83,8 @@ In order to access private images on the Docker Hub, a username and password can ### Configuring the Docker daemon -You will need to pass the `--registry-mirror` option to your Docker daemon on startup: +You will need to pass the `--registry-mirror` option to your Docker daemon on +startup: docker --registry-mirror=https:// daemon @@ -74,4 +92,6 @@ For example, if your mirror is serving on `http://10.0.0.2:5000`, you would run: docker --registry-mirror=https://10.0.0.2:5000 daemon -NOTE: Depending on your local host setup, you may be able to add the `--registry-mirror` option to the `DOCKER_OPTS` variable in `/etc/default/docker`. +> NOTE: Depending on your local host setup, you may be able to add the +`--registry-mirror` option to the `DOCKER_OPTS` variable in +`/etc/default/docker`. diff --git a/docs/recipes/nginx.md b/docs/recipes/nginx.md index 94fca625..c1873943 100644 --- a/docs/recipes/nginx.md +++ b/docs/recipes/nginx.md @@ -1,42 +1,50 @@ --- description: Restricting access to your registry using a nginx proxy keywords: -- registry, on-prem, images, tags, repository, distribution, nginx, proxy, authentication, - TLS, recipe, advanced -menu: - main: - parent: smn_recipes -title: Authenticating proxy with nginx +- registry, on-prem, images, tags, repository, distribution, nginx, proxy, authentication, TLS, recipe, advanced +title: Authenticate proxy with nginx --- -# Authenticating proxy with nginx - - ## Use-case -People already relying on a nginx proxy to authenticate their users to other services might want to leverage it and have Registry communications tunneled through the same pipeline. +People already relying on a nginx proxy to authenticate their users to other +services might want to leverage it and have Registry communications tunneled +through the same pipeline. -Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO mechanism fronting their internal http portal. +Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO +mechanism fronting their internal http portal. ### Alternatives -If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](../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](../deploying.md#native-basic-auth). ### Solution -With the method presented here, you implement basic authentication for docker engines in a reverse proxy that sits in front of your registry. +With the method presented here, you implement basic authentication for docker +engines in a reverse proxy that sits in front of your registry. -While we use a simple htpasswd file as an example, any other nginx authentication backend should be fairly easy to implement once you are done with the example. +While we use a simple htpasswd file as an example, any other nginx +authentication backend should be fairly easy to implement once you are done with +the example. -We also implement push restriction (to a limited user group) for the sake of the example. Again, you should modify this to fit your mileage. +We also implement push restriction (to a limited user group) for the sake of the +example. Again, you should modify this to fit your mileage. ### Gotchas -While this model gives you the ability to use whatever authentication backend you want through the secondary authentication mechanism implemented inside your proxy, it also requires that you move TLS termination from the Registry to the proxy itself. +While this model gives you the ability to use whatever authentication backend +you want through the secondary authentication mechanism implemented inside your +proxy, it also requires that you move TLS termination from the Registry to the +proxy itself. -Furthermore, introducing an extra http layer in your communication pipeline will make it more complex to deploy, maintain, and debug, and will possibly create issues. Make sure the extra complexity is required. +Furthermore, introducing an extra http layer in your communication pipeline will +make it more complex to deploy, maintain, and debug, and will possibly create +issues. Make sure the extra complexity is required. -For instance, Amazon's Elastic Load Balancer (ELB) in HTTPS mode already sets the following client header: +For instance, Amazon's Elastic Load Balancer (ELB) in HTTPS mode already sets +the following client header: ``` X-Real-IP @@ -44,7 +52,8 @@ X-Forwarded-For X-Forwarded-Proto ``` -So if you have an nginx sitting behind it, should remove these lines from the example config below: +So if you have an nginx sitting behind it, should remove these lines from the +example config below: ``` X-Real-IP $remote_addr; # pass on real client's IP @@ -52,7 +61,9 @@ X-Forwarded-For $proxy_add_x_forwarded_for; X-Forwarded-Proto $scheme; ``` -Otherwise nginx will reset the ELB's values, and the requests will not be routed properly. For more information, see [#970](https://github.com/docker/distribution/issues/970). +Otherwise nginx will reset the ELB's values, and the requests will not be routed +properly. For more information, see +[#970](https://github.com/docker/distribution/issues/970). ## Setting things up @@ -183,7 +194,8 @@ Now, start your stack: docker-compose up -d -Login with a "push" authorized user (using `testuser` and `testpassword`), then tag and push your first image: +Login with a "push" authorized user (using `testuser` and `testpassword`), then +tag and push your first image: docker login -u=testuser -p=testpassword -e=root@example.ch myregistrydomain.com:5043 docker tag ubuntu myregistrydomain.com:5043/test diff --git a/docs/recipes/osx-setup-guide.md b/docs/recipes/osx-setup-guide.md index f926f8c9..375f4408 100644 --- a/docs/recipes/osx-setup-guide.md +++ b/docs/recipes/osx-setup-guide.md @@ -2,14 +2,9 @@ description: Explains how to run a registry on macOS keywords: - registry, on-prem, images, tags, repository, distribution, macOS, recipe, advanced -menu: - main: - parent: smn_recipes -title: Running on macOS +title: macOS Setup Guide --- -# macOS Setup Guide - ## Use-case This is useful if you intend to run a registry server natively on macOS. diff --git a/docs/spec/api.md b/docs/spec/api.md index 45551b9e..4e99944f 100644 --- a/docs/spec/api.md +++ b/docs/spec/api.md @@ -2,14 +2,9 @@ description: Specification for the Registry API. keywords: - registry, on-prem, images, tags, repository, distribution, api, advanced -menu: - main: - parent: smn_registry_ref -title: HTTP API V2 +title: Docker Registry HTTP API V2 --- -# Docker Registry HTTP API V2 - ## Introduction The _Docker Registry HTTP API_ is the protocol to facilitate distribution of diff --git a/docs/spec/auth/index.md b/docs/spec/auth/index.md index 6b539f0e..324c4bce 100644 --- a/docs/spec/auth/index.md +++ b/docs/spec/auth/index.md @@ -2,15 +2,9 @@ description: Docker Registry v2 authentication schema keywords: - registry, on-prem, images, tags, repository, distribution, authentication, advanced -menu: - main: - parent: smn_registry_ref - weight: 100 -title: Docker Registry Token Authentication +title: Docker Registry v2 authentication --- -# Docker Registry v2 authentication - See the [Token Authentication Specification](token.md), [Token Authentication Implementation](jwt.md), [Token Scope Documentation](scope.md), diff --git a/docs/spec/auth/jwt.md b/docs/spec/auth/jwt.md index e0a2e641..eb0d6fa5 100644 --- a/docs/spec/auth/jwt.md +++ b/docs/spec/auth/jwt.md @@ -1,17 +1,10 @@ --- -description: Describe the reference implementation of the Docker Registry v2 authentication - schema +description: Describe the reference implementation of the Docker Registry v2 authentication schema keywords: - registry, on-prem, images, tags, repository, distribution, JWT authentication, advanced -menu: - main: - parent: smn_registry_ref - weight: 101 -title: Token Authentication Implementation +title: Docker Registry v2 Bearer token specification --- -# Docker Registry v2 Bearer token specification - This specification covers the `docker/distribution` implementation of the v2 Registry's authentication schema. Specifically, it describes the JSON Web Token schema that `docker/distribution` has adopted to implement the diff --git a/docs/spec/auth/oauth.md b/docs/spec/auth/oauth.md index ce0bcc49..388a4144 100644 --- a/docs/spec/auth/oauth.md +++ b/docs/spec/auth/oauth.md @@ -2,15 +2,9 @@ description: Specifies the Docker Registry v2 authentication keywords: - registry, on-prem, images, tags, repository, distribution, oauth2, advanced -menu: - main: - parent: smn_registry_ref - weight: 102 -title: Oauth2 Token Authentication +title: Docker Registry v2 authentication using OAuth2 --- -# Docker Registry v2 authentication using OAuth2 - This document describes support for the OAuth2 protocol within the authorization server. [RFC6749](https://tools.ietf.org/html/rfc6749) should be used as a reference for the protocol and HTTP endpoints described here. @@ -188,4 +182,3 @@ Content-Type: application/json {"refresh_token":"kas9Da81Dfa8","access_token":"eyJhbGciOiJFUzI1NiIsInR5":"expires_in":900,"scope":"repository:samalba/my-app:pull,repository:samalba/my-app:push"} ``` - diff --git a/docs/spec/auth/scope.md b/docs/spec/auth/scope.md index 8cd8699e..aa4bebf1 100644 --- a/docs/spec/auth/scope.md +++ b/docs/spec/auth/scope.md @@ -1,17 +1,10 @@ --- -description: Describes the scope and access fields used for registry authorization - tokens +description: Describes the scope and access fields used for registry authorization tokens keywords: - registry, on-prem, images, tags, repository, distribution, advanced, access, scope -menu: - main: - parent: smn_registry_ref - weight: 103 -title: Token Scope Documentation +title: Docker Registry token scope and access --- -# Docker Registry Token Scope and Access - Tokens used by the registry are always restricted what resources they may be used to access, where those resources may be accessed, and what actions may be done on those resources. Tokens always have the context of a user which @@ -141,4 +134,3 @@ done by fetching an access token using the refresh token. Since the refresh token is not scoped to specific resources for an audience, extra care should be taken to only use the refresh token to negotiate new access tokens directly with the authorization server, and never with a resource provider. - diff --git a/docs/spec/auth/token.md b/docs/spec/auth/token.md index fa49357e..ed3f382f 100644 --- a/docs/spec/auth/token.md +++ b/docs/spec/auth/token.md @@ -1,17 +1,10 @@ --- description: Specifies the Docker Registry v2 authentication keywords: -- registry, on-prem, images, tags, repository, distribution, Bearer authentication, - advanced -menu: - main: - parent: smn_registry_ref - weight: 104 -title: Token Authentication Specification +- registry, on-prem, images, tags, repository, distribution, Bearer authentication, advanced +title: Docker Registry v2 authentication via central service --- -# Docker Registry v2 authentication via central service - This document outlines the v2 Docker registry authentication scheme: ![v2 registry auth](../../images/v2-registry-auth.png) @@ -26,7 +19,7 @@ This document outlines the v2 Docker registry authentication scheme: 5. The client retries the original request with the Bearer token embedded in the request's Authorization header. 6. The Registry authorizes the client by validating the Bearer token and the - claim set embedded within it and begins the push/pull session as usual. + claim set embedded within it and begins the push/pull session as usual. ## Requirements @@ -82,7 +75,8 @@ Note the HTTP Response Header indicating the auth challenge: Www-Authenticate: Bearer realm="https://auth.docker.io/token",service="registry.docker.io",scope="repository:samalba/my-app:pull,push" ``` -This format is documented in [Section 3 of RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750#section-3) +This format is documented in [Section 3 of RFC 6750: The OAuth 2.0 Authorization +Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750#section-3) This challenge indicates that the registry requires a token issued by the specified token server and that the request the client is attempting will @@ -162,7 +156,7 @@ Defines getting a bearer and refresh token using the token endpoint. expires_in
- (Optional) The duration in seconds since the token was issued that it + (Optional) The duration in seconds since the token was issued that it will remain valid. When omitted, this defaults to 60 seconds. For compatibility with older clients, a token should never be returned with less than 60 seconds to live. @@ -253,4 +247,5 @@ token placed in the HTTP `Authorization` header like so: Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IkJWM0Q6MkFWWjpVQjVaOktJQVA6SU5QTDo1RU42Ok40SjQ6Nk1XTzpEUktFOkJWUUs6M0ZKTDpQT1RMIn0.eyJpc3MiOiJhdXRoLmRvY2tlci5jb20iLCJzdWIiOiJCQ0NZOk9VNlo6UUVKNTpXTjJDOjJBVkM6WTdZRDpBM0xZOjQ1VVc6NE9HRDpLQUxMOkNOSjU6NUlVTCIsImF1ZCI6InJlZ2lzdHJ5LmRvY2tlci5jb20iLCJleHAiOjE0MTUzODczMTUsIm5iZiI6MTQxNTM4NzAxNSwiaWF0IjoxNDE1Mzg3MDE1LCJqdGkiOiJ0WUpDTzFjNmNueXk3a0FuMGM3cktQZ2JWMUgxYkZ3cyIsInNjb3BlIjoiamxoYXduOnJlcG9zaXRvcnk6c2FtYWxiYS9teS1hcHA6cHVzaCxwdWxsIGpsaGF3bjpuYW1lc3BhY2U6c2FtYWxiYTpwdWxsIn0.Y3zZSwaZPqy4y9oRBVRImZyv3m_S9XDHF1tWwN7mL52C_IiA73SJkWVNsvNqpJIn5h7A2F8biv_S2ppQ1lgkbw ``` -This is also described in [Section 2.1 of RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750#section-2.1) +This is also described in [Section 2.1 of RFC 6750: The OAuth 2.0 Authorization +Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750#section-2.1) diff --git a/docs/spec/index.md b/docs/spec/index.md index 7ad0aaea..74b13149 100644 --- a/docs/spec/index.md +++ b/docs/spec/index.md @@ -2,15 +2,9 @@ description: Explains registry JSON objects keywords: - registry, service, images, repository, json -menu: - main: - parent: smn_registry_ref - weight: -1 -title: Reference Overview +title: Docker Registry Reference --- -# Docker Registry Reference - * [HTTP API V2](api.md) * [Storage Driver](../storage-drivers/index.md) * [Token Authentication Specification](auth/token.md) diff --git a/docs/spec/json.md b/docs/spec/json.md index e5d0d304..69cb4498 100644 --- a/docs/spec/json.md +++ b/docs/spec/json.md @@ -3,14 +3,9 @@ description: Explains registry JSON objects published: false keywords: - registry, service, images, repository, json -menu: - main: - parent: smn_registry_ref -title: Docker Distribution JSON Canonicalization +title: Docker Distribution JSON canonicalization --- -# Docker Distribution JSON Canonicalization - To provide consistent content hashing of JSON objects throughout Docker Distribution APIs, the specification defines a canonical JSON format. Adopting such a canonicalization also aids in caching JSON responses. diff --git a/docs/spec/manifest-v2-1.md b/docs/spec/manifest-v2-1.md index 3162f3f8..63db46e3 100644 --- a/docs/spec/manifest-v2-1.md +++ b/docs/spec/manifest-v2-1.md @@ -2,14 +2,9 @@ description: image manifest for the Registry. keywords: - registry, on-prem, images, tags, repository, distribution, api, advanced, manifest -menu: - main: - parent: smn_registry_ref -title: 'Image Manifest V 2, Schema 1 ' +title: Image manifest V2, schema 1 --- -# Image Manifest Version 2, Schema 1 - This document outlines the format of of the V2 image manifest. The image manifest described herein was introduced in the Docker daemon in the [v1.3.0 release](https://github.com/docker/docker/commit/9f482a66ab37ec396ac61ed0c00d59122ac07453). diff --git a/docs/spec/manifest-v2-2.md b/docs/spec/manifest-v2-2.md index eaf9295c..4c28e9ac 100644 --- a/docs/spec/manifest-v2-2.md +++ b/docs/spec/manifest-v2-2.md @@ -2,14 +2,9 @@ description: image manifest for the Registry. keywords: - registry, on-prem, images, tags, repository, distribution, api, advanced, manifest -menu: - main: - parent: smn_registry_ref -title: 'Image Manifest V 2, Schema 2 ' +title: Image manifest V2, schema 2 --- -# Image Manifest Version 2, Schema 2 - This document outlines the format of of the V2 image manifest, schema version 2. The original (and provisional) image manifest for V2 (schema 1), was introduced in the Docker daemon in the [v1.3.0 diff --git a/docs/storage-drivers/azure.md b/docs/storage-drivers/azure.md index 64e476e4..899418ce 100644 --- a/docs/storage-drivers/azure.md +++ b/docs/storage-drivers/azure.md @@ -2,14 +2,9 @@ description: Explains how to use the Azure storage drivers keywords: - registry, service, driver, images, storage, azure -menu: - main: - parent: smn_storagedrivers title: Microsoft Azure storage driver --- -# Microsoft Azure storage driver - An implementation of the `storagedriver.StorageDriver` interface which uses [Microsoft Azure Blob Storage](http://azure.microsoft.com/en-us/services/storage/) for object storage. ## Parameters diff --git a/docs/storage-drivers/filesystem.md b/docs/storage-drivers/filesystem.md index 2c7f6628..2a1f7e1c 100644 --- a/docs/storage-drivers/filesystem.md +++ b/docs/storage-drivers/filesystem.md @@ -2,14 +2,9 @@ description: Explains how to use the filesystem storage drivers keywords: - registry, service, driver, images, storage, filesystem -menu: - main: - parent: smn_storagedrivers title: Filesystem storage driver --- -# Filesystem storage driver - An implementation of the `storagedriver.StorageDriver` interface which uses the local filesystem. ## Parameters diff --git a/docs/storage-drivers/gcs.md b/docs/storage-drivers/gcs.md index 4c8a7c88..4ecc4962 100644 --- a/docs/storage-drivers/gcs.md +++ b/docs/storage-drivers/gcs.md @@ -2,14 +2,9 @@ description: Explains how to use the Google Cloud Storage drivers keywords: - registry, service, driver, images, storage, gcs, google, cloud -menu: - main: - parent: smn_storagedrivers -title: GCS storage driver +title: Google Cloud Storage driver --- -# Google Cloud Storage driver - An implementation of the `storagedriver.StorageDriver` interface which uses Google Cloud for object storage. ## Parameters diff --git a/docs/storage-drivers/index.md b/docs/storage-drivers/index.md index 1c9fbe9d..9279e20d 100644 --- a/docs/storage-drivers/index.md +++ b/docs/storage-drivers/index.md @@ -4,16 +4,9 @@ aliases: description: Explains how to use storage drivers keywords: - registry, on-prem, images, tags, repository, distribution, storage drivers, advanced -menu: - main: - identifier: storage_index - parent: smn_storagedrivers - weight: -1 -title: Storage Driver overview +title: Docker Registry storage driver --- -# Docker Registry Storage Driver - This document describes the registry storage driver model, implementation, and explains how to contribute new storage drivers. ## Provided Drivers diff --git a/docs/storage-drivers/inmemory.md b/docs/storage-drivers/inmemory.md index 6fbed6aa..e4b40426 100644 --- a/docs/storage-drivers/inmemory.md +++ b/docs/storage-drivers/inmemory.md @@ -2,14 +2,9 @@ description: Explains how to use the in-memory storage drivers keywords: - registry, service, driver, images, storage, in-memory -menu: - main: - parent: smn_storagedrivers -title: In-memory storage driver +title: In-memory storage driver (testing only) --- -# In-memory storage driver (Testing Only) - For purely tests purposes, you can use the `inmemory` storage driver. This 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 diff --git a/docs/storage-drivers/oss.md b/docs/storage-drivers/oss.md index 44109003..95054943 100644 --- a/docs/storage-drivers/oss.md +++ b/docs/storage-drivers/oss.md @@ -2,15 +2,11 @@ description: Explains how to use the Aliyun OSS storage driver keywords: - registry, service, driver, images, storage, OSS, aliyun -menu: - main: - parent: smn_storagedrivers title: Aliyun OSS storage driver --- -# Aliyun OSS storage driver - -An implementation of the `storagedriver.StorageDriver` interface which uses [Aliyun OSS](http://www.aliyun.com/product/oss) for object storage. +An implementation of the `storagedriver.StorageDriver` interface which uses +[Aliyun OSS](http://www.aliyun.com/product/oss) for object storage. ## Parameters diff --git a/docs/storage-drivers/s3.md b/docs/storage-drivers/s3.md index cf729490..88e23049 100644 --- a/docs/storage-drivers/s3.md +++ b/docs/storage-drivers/s3.md @@ -2,15 +2,11 @@ description: Explains how to use the S3 storage drivers keywords: - registry, service, driver, images, storage, S3 -menu: - main: - parent: smn_storagedrivers title: S3 storage driver --- -# S3 storage driver - -An implementation of the `storagedriver.StorageDriver` interface which uses Amazon S3 or S3 compatible services for object storage. +An implementation of the `storagedriver.StorageDriver` interface which uses +Amazon S3 or S3 compatible services for object storage. ## Parameters @@ -221,17 +217,25 @@ The following IAM permissions are required by the registry for push and pull. S ## Use Case -Adding CloudFront as a middleware for your S3 backed registry can dramatically improve pull times. Your registry will have the ability to retrieve your images from edge servers, rather than the geographically limited location of your S3 bucket. The farther your registry is from your bucket, the more improvements you will see. See [Amazon CloudFront](https://aws.amazon.com/cloudfront/details/). +Adding CloudFront as a middleware for your S3 backed registry can dramatically +improve pull times. Your registry will have the ability to retrieve your images +from edge servers, rather than the geographically limited location of your S3 +bucket. The farther your registry is from your bucket, the more improvements you +will see. See [Amazon CloudFront](https://aws.amazon.com/cloudfront/details/). ## Configuring CloudFront for Distribution -If you are unfamiliar with creating a CloudFront distribution, see [Getting Started with Cloudfront](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GettingStarted.html). +If you are unfamiliar with creating a CloudFront distribution, see [Getting +Started with +Cloudfront](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GettingStarted.html). Defaults can be kept in most areas except: ### Origin: -The CloudFront distribution must be created such that the `Origin Path` is set to the directory level of the root "docker" key in S3. If your registry exists on the root of the bucket, this path should be left blank. +The CloudFront distribution must be created such that the `Origin Path` is set +to the directory level of the root "docker" key in S3. If your registry exists +on the root of the bucket, this path should be left blank. ### Behaviors: @@ -243,7 +247,9 @@ The CloudFront distribution must be created such that the `Origin Path` is set t ## Registry configuration -Here the `middleware` option is used. It is still important to keep the `storage` option as CloudFront will only handle `pull` actions; `push` actions are still directly written to S3. +Here the `middleware` option is used. It is still important to keep the +`storage` option as CloudFront will only handle `pull` actions; `push` actions +are still directly written to S3. The following example shows what you will need at minimum: @@ -265,4 +271,6 @@ middleware: ## CloudFront Key-Pair -A CloudFront key-pair is required for all AWS accounts needing access to your CloudFront distribution. For information, please see [Creating CloudFront Key Pairs](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html#private-content-creating-cloudfront-key-pairs). +A CloudFront key-pair is required for all AWS accounts needing access to your +CloudFront distribution. For information, please see [Creating CloudFront Key +Pairs](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html#private-content-creating-cloudfront-key-pairs). diff --git a/docs/storage-drivers/swift.md b/docs/storage-drivers/swift.md index eaa80511..6029a628 100644 --- a/docs/storage-drivers/swift.md +++ b/docs/storage-drivers/swift.md @@ -2,15 +2,12 @@ description: Explains how to use the OpenStack swift storage driver keywords: - registry, service, driver, images, storage, swift -menu: - main: - parent: smn_storagedrivers -title: Swift storage driver +title: OpenStack Swift storage driver --- -# OpenStack Swift storage driver - -An implementation of the `storagedriver.StorageDriver` interface that uses [OpenStack Swift](http://docs.openstack.org/developer/swift/) for object storage. +An implementation of the `storagedriver.StorageDriver` interface that uses +[OpenStack Swift](http://docs.openstack.org/developer/swift/) for object +storage. ## Parameters @@ -210,8 +207,9 @@ An implementation of the `storagedriver.StorageDriver` interface that uses [Open -The features supported by the Swift server are queried by requesting the `/info` URL on the server. In case the administrator -disabled that feature, the configuration file can specify the following optional parameters : +The features supported by the Swift server are queried by requesting the `/info` +URL on the server. In case the administrator disabled that feature, the +configuration file can specify the following optional parameters :