Merge pull request #931 from dmp42/5.all-ur-proxy-are-belong-to-us

Documentation fixes

contrib/apache/README.MD

@@ -28,7 +28,7 @@ HTTP for mirror and HTTPS for v1 & v2
 
 ### Registry v2
 
-    docker run -d -e SETTINGS_FLAVOR=dev -v /var/lib/axway/docker-registry/storage/hosting2-v2:/tmp -p 5002:5000 registry:2.0"
+    docker run -d -e SETTINGS_FLAVOR=dev -v /var/lib/axway/docker-registry/storage/hosting2-v2:/tmp -p 5002:5000 registry:2"
 
 # For Hosting mode access
 

docs/apache.md

@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
 title = "Authenticating proxy with apache"
-description = "Restricting access to your registry using a proxy"
+description = "Restricting access to your registry using an apache proxy"
-keywords = ["registry, service, images, repository, authentication"]
+keywords = ["registry, on-prem, images, tags, repository, distribution, authentication, proxy, apache, httpd, TLS, recipe, advanced"]
 +++
 <![end-metadata]-->
 
@@ -211,24 +211,3 @@ Now, login with a "pull-only" user (using `testuser` and `testpassword`), then p
 Verify that the "pull-only" can NOT push:
 
     docker push myregistrydomain.com:5043/test
-
-### Docker still complains about the certificate?
-
-That's certainly because you are using a self-signed certificate, despite the warnings.
-
-If you really insist on using these, you have to trust it at the OS level.
-
-Usually, on Ubuntu this is done with:
-
-    cp auth/domain.crt /usr/local/share/ca-certificates/myregistrydomain.com.crt
-    update-ca-certificates
-
-... and on RedHat with:
-
-    cp auth/domain.crt /etc/pki/ca-trust/source/anchors/myregistrydomain.com.crt
-    update-ca-trust
-
-Now:
-
- * `service docker stop && service docker start` (or any other way you use to restart docker)
- * `docker-compose up -d` to bring your registry up

docs/building.md

@@ -1,10 +1,32 @@
 <!--[metadata]>
 +++
-draft = "true"
+title = "Build instructions"
+description = "Explains how to build & hack on the registry"
+keywords = ["registry, on-prem, images, tags, repository, distribution, build, recipe, advanced"]
 +++
 <![end-metadata]-->
 
-# Build the development environment
+# Building the registry source
+
+## Use-case
+
+This is useful if you intend to actively work on the registry.
+
+### Alternatives
+
+Most people should use the [official Registry docker image](https://hub.docker.com/r/library/registry/).
+
+People looking for advanced operational use cases might consider rolling their own image with a custom Dockerfile inheriting `FROM registry:2`.
+
+OS X users who want to run natively can do so following [the instructions here](osx-setup-guide.md).
+
+### Gotchas
+
+You are expected to know your way around with go & git.
+
+If you are a casual user with no development experience, and no preliminary knowledge of go, building from source is probably not a good solution for you.
+
+## Build the development environment
 
 The first prerequisite of properly building distribution targets is to have a Go
 development environment setup. Please follow [How to Write Go Code](https://golang.org/doc/code.html)
@@ -14,27 +36,21 @@ environment.
 If a Go development environment is setup, one can use `go get` to install the
 `registry` command from the current latest:
 
-```sh
+    go get github.com/docker/distribution/cmd/registry
-go get github.com/docker/distribution/cmd/registry
-```
 
 The above will install the source repository into the `GOPATH`.
 
 Now create the directory for the registry data (this might require you to set permissions properly)
 
-```sh
+    mkdir -p /var/lib/registry
-mkdir -p /var/lib/registry
-```
 
 ... or alternatively `export REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere` if you want to store data into another location.
 
 The `registry`
 binary can then be run with the following:
 
-```
+    $ $GOPATH/bin/registry -version
-$ $GOPATH/bin/registry -version
+    $GOPATH/bin/registry github.com/docker/distribution v2.0.0-alpha.1+unknown
-$GOPATH/bin/registry github.com/docker/distribution v2.0.0-alpha.1+unknown
-```
 
 > __NOTE:__ While you do not need to use `go get` to checkout the distribution
 > project, for these build instructions to work, the project must be checked
@@ -44,13 +60,11 @@ $GOPATH/bin/registry github.com/docker/distribution v2.0.0-alpha.1+unknown
 The registry can be run with the default config using the following
 incantation:
 
-```
+    $ $GOPATH/bin/registry $GOPATH/src/github.com/docker/distribution/cmd/registry/config-example.yml
-$ $GOPATH/bin/registry $GOPATH/src/github.com/docker/distribution/cmd/registry/config-dev.yml
+    INFO[0000] endpoint local-5003 disabled, skipping        app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
-INFO[0000] endpoint local-5003 disabled, skipping        app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
+    INFO[0000] endpoint local-8083 disabled, skipping        app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
-INFO[0000] endpoint local-8083 disabled, skipping        app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
+    INFO[0000] listening on :5000                            app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
-INFO[0000] listening on :5000                            app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
+    INFO[0000] debug server listening localhost:5001
-INFO[0000] debug server listening localhost:5001
-```
 
 If it is working, one should see the above log messages.
 
@@ -64,53 +78,47 @@ commands, such as `go test`, should work per package (please see
 A `Makefile` has been provided as a convenience to support repeatable builds.
 Please install the following into `GOPATH` for it to work:
 
-```
+    go get github.com/tools/godep github.com/golang/lint/golint
-go get github.com/tools/godep github.com/golang/lint/golint
-```
 
 **TODO(stevvooe):** Add a `make setup` command to Makefile to run this. Have to think about how to interact with Godeps properly.
 
 Once these commands are available in the `GOPATH`, run `make` to get a full
 build:
 
-```
+    $ GOPATH=`godep path`:$GOPATH make
-$ GOPATH=`godep path`:$GOPATH make
+    + clean
-+ clean
+    + fmt
-+ fmt
+    + vet
-+ vet
+    + lint
-+ lint
+    + build
-+ build
+    github.com/docker/docker/vendor/src/code.google.com/p/go/src/pkg/archive/tar
-github.com/docker/docker/vendor/src/code.google.com/p/go/src/pkg/archive/tar
+    github.com/Sirupsen/logrus
-github.com/Sirupsen/logrus
+    github.com/docker/libtrust
-github.com/docker/libtrust
+    ...
-...
+    github.com/yvasiyarov/gorelic
-github.com/yvasiyarov/gorelic
+    github.com/docker/distribution/registry/handlers
-github.com/docker/distribution/registry/handlers
+    github.com/docker/distribution/cmd/registry
-github.com/docker/distribution/cmd/registry
+    + test
-+ test
+    ...
-...
+    ok    github.com/docker/distribution/digest 7.875s
-ok    github.com/docker/distribution/digest 7.875s
+    ok    github.com/docker/distribution/manifest 0.028s
-ok    github.com/docker/distribution/manifest 0.028s
+    ok    github.com/docker/distribution/notifications  17.322s
-ok    github.com/docker/distribution/notifications  17.322s
+    ?     github.com/docker/distribution/registry [no test files]
-?     github.com/docker/distribution/registry [no test files]
+    ok    github.com/docker/distribution/registry/api/v2  0.101s
-ok    github.com/docker/distribution/registry/api/v2  0.101s
+    ?     github.com/docker/distribution/registry/auth  [no test files]
-?     github.com/docker/distribution/registry/auth  [no test files]
+    ok    github.com/docker/distribution/registry/auth/silly  0.011s
-ok    github.com/docker/distribution/registry/auth/silly  0.011s
+    ...
-...
+    + /Users/sday/go/src/github.com/docker/distribution/bin/registry
-+ /Users/sday/go/src/github.com/docker/distribution/bin/registry
+    + /Users/sday/go/src/github.com/docker/distribution/bin/registry-api-descriptor-template
-+ /Users/sday/go/src/github.com/docker/distribution/bin/registry-api-descriptor-template
+    + binaries
-+ binaries
-```
 
 The above provides a repeatable build using the contents of the vendored
 Godeps directory. This includes formatting, vetting, linting, building,
 testing and generating tagged binaries. We can verify this worked by running
 the registry binary generated in the "./bin" directory:
 
-```sh
+    $ ./bin/registry -version
-$ ./bin/registry -version
+    ./bin/registry github.com/docker/distribution v2.0.0-alpha.2-80-g16d8b2c.m
-./bin/registry github.com/docker/distribution v2.0.0-alpha.2-80-g16d8b2c.m
-```
 
 ### Developing
 
@@ -124,9 +132,7 @@ can be demonstrated using `godep` to migrate the `GOPATH` to use the specified
 dependencies. The `GOPATH` can be migrated to the current package versions
 declared in `Godeps` with the following command:
 
-```sh
+    godep restore
-godep restore
-```
 
 > **WARNING:** This command will checkout versions of the code specified in
 > Godeps/Godeps.json, modifying the contents of `GOPATH`. If this is
@@ -136,9 +142,7 @@ godep restore
 With a successful run of the above command, one can now use `make` without
 specifying the `GOPATH`:
 
-```sh
+    make
-$ make
-```
 
 If that is successful, standard `go` commands, such as `go test` should work,
 per package, without issue.
@@ -151,6 +155,4 @@ the environment variable `DOCKER_BUILDTAGS`.
 To enable the [Ceph RADOS storage driver](storage-drivers/rados.md)
 (librados-dev and librbd-dev will be required to build the bindings):
 
-```sh
+    export DOCKER_BUILDTAGS='include_rados'
-export DOCKER_BUILDTAGS='include_rados'
-```

docs/configuration.md

@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
-title = "Configure a Registry"
+title = "Configuring a registry"
-description = "Explains how to deploy a registry"
+description = "Explains how to configure a registry"
-keywords = ["registry, service, images,  repository"]
+keywords = ["registry, on-prem, images, tags, repository, distribution, configuration"]
 [menu.main]
 parent="smn_registry"
 weight=4
@@ -37,7 +37,7 @@ directory.
 >as replacing the storage driver type with `REGISTRY_STORAGE=filesystem`, then
 >all sub-fields will be erased. As such, specifying the storage type in the
 >environment will remove all parameters related to the old storage
->configuration.
+>configuration (order *matters*).
 
 ## Overriding the entire configuration file
 
@@ -226,8 +226,6 @@ options marked as **required**. This indicates that you can omit the parent with
 all its children. However, if the parent is included, you must also include all
 the children marked **required**.
 
-
-
 ## version
 
     version: 0.1

docs/deploying.md

@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
 title = "Deploying a registry server"
-description = "Explains how to deploy a registry server"
+description = "Explains how to deploy a registry"
-keywords = ["registry, service, images, repository"]
+keywords = ["registry, on-prem, images, tags, repository, distribution, deployment"]
 [menu.main]
 parent="smn_registry"
 weight=3
@@ -61,7 +61,11 @@ While running on `localhost` has its uses, most people want their registry to be
 
 Assuming that you own the domain `myregistrydomain.com`, and that its DNS record points to the host where you are running your registry, you first need to get a certificate from a CA.
 
-Move and/or rename your crt file to: `certs/domain.crt` - and your key file to: `certs/domain.key`.
+Create a `certs` directory:
+
+    mkdir -p certs
+
+Then move and/or rename your crt file to: `certs/domain.crt`, and your key file to: `certs/domain.key`.
 
 Make sure you stopped your registry from the previous steps, then start your registry again with TLS enabled:
 
@@ -82,13 +86,17 @@ You should now be able to access your registry from another docker host:
 
 A certificate issuer may supply you with an *intermediate* certificate. In this case, you must combine your certificate with the intermediate's to form a *certificate bundle*. You can do this using the `cat` command: 
 
-    cat server.crt intermediate-certificates.pem > certs/domain.crt
+    cat domain.crt intermediate-certificates.pem > certs/domain.crt
 
-#### Load Balancing Considerations
+### Alternatives
+
+While rarely advisable, you may want to use self-signed certificates instead, or use your registry in an insecure fashion. You will find instructions [here](insecure.md).
+
+## Load Balancing Considerations
 
 One may want to use a load balancer to distribute load, terminate TLS or
-provide high availability. While a full laod balancing setup is outside the
+provide high availability. While a full load balancing setup is outside the
-scope this document, there are a few considerations that can make the process
+scope of this document, there are a few considerations that can make the process
 smoother.
 
 The most important aspect is that a load balanced cluster of registries must
@@ -99,15 +107,15 @@ the following must be the same:
   - HTTP Secret
   - Redis Cache (if configured)
 
-If any of these are different, the registry may have trouble serving requests.
+If any of these are different, the registry will have trouble serving requests.
 As an example, if you're using the filesystem driver, all registry instances
 must have access to the same filesystem root, which means they should be in
 the same machine. For other drivers, such as s3 or azure, they should be
 accessing the same resource, and will likely share an identical configuration.
 The _HTTP Secret_ coordinates uploads, so also must be the same across
-instances. Configuring different redis instances will mostly work (at the time
+instances. Configuring different redis instances will work (at the time
 of writing), but will not be optimal if the instances are not shared, causing
-more reqeusts to be directed to the backend.
+more requests to be directed to the backend.
 
 Getting the headers correct is very important. For all responses to any
 request under the "/v2/" url space, the `Docker-Distribution-API-Version`
@@ -116,21 +124,22 @@ This header allows the docker engine to quickly resolve authentication realms
 and fallback to version 1 registries, if necessary. Confirming this is setup
 correctly can help avoid problems with fallback.
 
+In the same train of thought, you must make sure you are properly sending the
+`X-Forwarded-Proto`, `X-Forwared-For` and `Host` headers to their "client-side"
+values. Failure to do so usually makes the registry issue redirects to internal
+hostnames or downgrading from https to http.
+
 A properly secured registry should return 401 when the "/v2/" endpoint is hit
 without credentials. The response should include a `WWW-Authenticate`
 challenge, providing guidance on how to authenticate, such as with basic auth
 or a token service. If the load balancer has health checks, it is recommended
-to configure it to consider a 401 response as healthy and any others as down.
+to configure it to consider a 401 response as healthy and any other as down.
 This will secure your registry by ensuring that configuration problems with
 authentication don't accidentally expose an unprotected registry. If you're
 using a less sophisticated load balancer, such as Amazon's Elastic Load
 Balancer, that doesn't allow one to change the healthy response code, health
 checks can be directed at "/", which will always return a `200 OK` response.
 
-### Alternatives
-
-While rarely advisable, you may want to use self-signed certificates instead, or use your registry in an insecure fashion. You will find instructions [here](insecure.md).
-
 ## Restricting access
 
 Except for registries running on secure local networks, registries should always implement access restrictions.
@@ -164,15 +173,19 @@ You should now be able to:
 
 And then push and pull images as an authenticated user.
 
+#### Gotcha
+
+Seeing X509 errors is usually a sign you are trying to use self-signed certificates, and failed to [configure your docker daemon properly](insecure.md).
+
 ### Alternatives
 
 1. You may want to leverage more advanced basic auth implementations through a proxy design, in front of the registry. You will find examples of such patterns in the [recipes list](recipes.md).
 
-2. Alternatively, the Registry also supports delegated authentication, redirecting users to a specific, trusted token server. That approach requires significantly more investment, and only make sense if you want to fully configure ACLs and more control over the Registry integration into your global authorization and authentication systems.
+2. Alternatively, the Registry also supports delegated authentication, redirecting users to a specific, trusted token server. That approach requires significantly more investment, and only makes sense if you want to fully configure ACLs and more control over the Registry integration into your global authorization and authentication systems.
 
 You will find [background information here](spec/auth/token.md), and [configuration information here](configuration.md#auth).
 
-Beware that you will have to implement your own authentication service for this to work.
+Beware that you will have to implement your own authentication service for this to work, or leverage a third-party implementation.
 
 ## Managing with Compose
 
@@ -191,7 +204,6 @@ registry:
   environment:
     REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt
     REGISTRY_HTTP_TLS_KEY: /certs/domain.key
-    REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /var/lib/registry
     REGISTRY_AUTH: htpasswd
     REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
     REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm
@@ -216,10 +228,4 @@ You will find more specific and advanced informations in the following sections:
  - [Advanced "recipes"](recipes.md)
  - [Registry API](spec/api.md)
  - [Storage driver model](storagedrivers.md)
-
+ - [Token authentication](spec/auth/token.md)
-<!--
- - [Glossary](glossary.md)
-### Development resources
- - [Building the registry](building.md)
- - [Architecture notes](architecture.md)
- -->

docs/help.md

@@ -2,7 +2,7 @@
 +++
 title = "Getting help"
 description = "Getting help with the Registry"
-keywords = ["registry, service, images,  repository, help"]
+keywords = ["registry, on-prem, images, tags, repository, distribution, help, 101, TL;DR"]
 [menu.main]
 parent="smn_registry"
 weight=9

docs/index.md

@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
-title = "Docker Registry 2.0"
+title = "Docker Registry"
-description = "Introduces the Docker Registry"
+description = "High-level overview of the Registry"
-keywords = ["registry, images, repository"]
+keywords = ["registry, on-prem, images, tags, repository, distribution"]
 [menu.main]
 parent="smn_registry"
 +++
@@ -32,7 +32,7 @@ Users looking for a commercially supported version of the Registry should look i
 ## 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)
+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
 

docs/insecure.md

@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
-title = "Insecure Registry"
+title = "Testing an insecure registry"
-description = "Deploying an insecure Registry"
+description = "Deploying a Registry in an insecure fashion"
-keywords = ["registry, images, repository"]
+keywords = ["registry, on-prem, images, tags, repository, distribution, insecure"]
 +++
 <![end-metadata]-->
 
@@ -23,16 +23,16 @@ This basically tells Docker to entirely disregard security for your registry.
 
 **Pros:**
 
- - easy to configure
+ - relatively easy to configure
  
 **Cons:**
  
- - very insecure
+ - this is **very** insecure: you are basically exposing yourself to trivial MITM, and this solution should only be used for isolated testing or in a tightly controlled, air-gapped environment
  - you have to configure every docker daemon that wants to access your registry 
   
 ## Using self-signed certificates
 
-> :warning: using this along with basic authentication requires to **also** trust the certificate into the OS cert store for some versions of docker
+> :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)
 
 Generate your own certificate:
 
@@ -42,11 +42,11 @@ Generate your own certificate:
 
 Be sure to use the name `myregistrydomain.com` as a CN.
 
-Stop and restart your registry.
+Use the result to [start your registry with TLS enabled](https://github.com/docker/distribution/blob/master/docs/deploying.md#get-a-certificate)
 
-Then you have to instruct every docker daemon to trust that certificate. This is done by copying the `domain.crt` file to `/etc/docker/certs.d/myregistrydomain.com:5000/ca.crt` (don't forget to restart docker after doing so).
+Then you have to instruct every docker daemon to trust that certificate. This is done by copying the `domain.crt` file to `/etc/docker/certs.d/myregistrydomain.com:5000/ca.crt`.
 
-Stop and restart all your docker daemons.
+Don't forget to restart docker after doing so.
 
 **Pros:**
 
@@ -68,3 +68,19 @@ If this private registry supports only HTTP or HTTPS with an unknown CA certific
 In the case of HTTPS, if you have access to the registry's CA certificate, no need for the flag;
 simply place the CA certificate at /etc/docker/certs.d/myregistrydomain.com:5000/ca.crt
 ```
+
+## Docker still complains about the certificate when using authentication?
+
+When using authentication, some versions of docker also require you to trust the certificate at the OS level.
+
+Usually, on Ubuntu this is done with:
+
+    cp auth/domain.crt /usr/local/share/ca-certificates/myregistrydomain.com.crt
+    update-ca-certificates
+
+... and on RedHat with:
+
+    cp auth/domain.crt /etc/pki/ca-trust/source/anchors/myregistrydomain.com.crt
+    update-ca-trust
+
+Now restart docker (`service docker stop && service docker start`, or any other way you use to restart docker).

docs/introduction.md

@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
 title = "Understanding the Registry"
-description = "Explains what it is, basic use cases and requirements"
+description = "Explains what the Registry is, basic use cases and requirements"
-keywords = ["registry, service, images, repository, understand, use cases, requirements"]
+keywords = ["registry, on-prem, images, tags, repository, distribution, use cases, requirements"]
 [menu.main]
 parent="smn_registry"
 weight=2
@@ -31,7 +31,7 @@ Finally, the Registry ships with a robust [notification system](notifications.md
 
 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 registry-1.docker.io/library/ubuntu` command
+ * `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](https://docs.docker.com/reference/commandline/cli/).

docs/mirror.md

@@ -1,28 +1,40 @@
 <!--[metadata]>
 +++
-draft = "true"
+title = "Mirroring Docker Hub"
+description = "Setting-up a local mirror for Docker Hub images"
+keywords = ["registry, on-prem, images, tags, repository, distribution, mirror, Hub, recipe, advanced"]
 +++
 <![end-metadata]-->
 
 # Registry as a pull through cache
 
-A v2 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.
+## Use-case
 
-NOTE: Currently this feature can only be used to proxy against the official Docker Hub.
+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.
 
-## Why?
+### Alternatives
 
-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 image fetch traffic on your local network.
+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.
+
+### Gotcha
+
+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.
 
 ## 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.
 
-## What if the content changes on the Hub?
+### 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.
 
-## What about my disk?
+### 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.
 
@@ -30,7 +42,7 @@ To ensure best performance and guarantee correctness the Registry cache should b
 
 ## 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 pull through cache official 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.
 
@@ -38,33 +50,23 @@ Multiple registry caches can be deployed over the same back-end.  A single regis
 
 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 the username and password can be supplied.
+In order to access private images on the Docker Hub, a username and password can be supplied.
 
-```            
+    proxy:
-proxy:
       remoteurl: https://registry-1.docker.io
       username: [username]
       password: [password]
-```
 
+> :warn: if you specify a username and password, it's very important to understand that private resources that this user has access to on the Hub will be made available on your mirror. It's thus paramount that you secure your mirror by implementing authentication if you expect these resources to stay private!
 
-
+### Configuring the Docker daemon
-## Configuring the Docker daemon
 
 You will need to pass the `--registry-mirror` option to your Docker daemon on startup:
 
-```
+    docker --registry-mirror=https://<my-docker-mirror-host> daemon
-docker --registry-mirror=https://<my-docker-mirror-host> -d
-```
 
 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
-docker --registry-mirror=https://10.0.0.2:5000 -d
-```
-
-NOTE: Depending on your local host setup, you may be able to add the --registry-mirror options 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`.

docs/mkdocs.yml

@@ -1,18 +0,0 @@
-- ['registry/index.md', 'Reference', 'Docker Registry 2.0']
-- ['registry/introduction.md', 'Reference', '    ▪  Introduction' ]
-- ['registry/deploying.md', 'Reference', '    ▪  Deploy a registry' ]
-- ['registry/configuration.md', 'Reference', '    ▪  Configure a registry' ]
-- ['registry/authentication.md', 'Reference', '    ▪  Authentication' ]
-- ['registry/glossary.md', 'Reference', '    ▪  Glossary' ]
-- ['registry/help.md', 'Reference', '    ▪  Getting help' ]
-- ['registry/storagedrivers.md', 'Reference', '    ▪  Storage driver model' ]
-- ['registry/notifications.md', 'Reference', '    ▪  Work with notifications' ]
-- ['registry/spec/api.md', 'Reference', '    ▪  Registry Service API v2' ]
-
-- ['registry/spec/json.md', '**HIDDEN**']
-- ['registry/spec/auth/token.md', '**HIDDEN**']
-- ['registry/storage-drivers/azure.md', '**HIDDEN**' ]
-- ['registry/storage-drivers/filesystem.md', '**HIDDEN**' ]
-- ['registry/storage-drivers/inmemory.md', '**HIDDEN**' ]
-- ['registry/storage-drivers/rados.md', '**HIDDEN**' ]
-- ['registry/storage-drivers/s3.md','**HIDDEN**' ]

docs/nginx.md

@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
 title = "Authenticating proxy with nginx"
-description = "Restricting access to your registry using a proxy"
+description = "Restricting access to your registry using a nginx proxy"
-keywords = ["registry, service, images, repository, authentication"]
+keywords = ["registry, on-prem, images, tags, repository, distribution, nginx, proxy, authentication, TLS, recipe, advanced"]
 +++
 <![end-metadata]-->
 
@@ -133,24 +133,3 @@ Login with a "push" authorized user (using `testuserpush` and `testpasswordpush`
     docker tag ubuntu myregistrydomain.com:5043/test
     docker push myregistrydomain.com:5043/test
     docker pull myregistrydomain.com:5043/test
-
-## Docker still complains about the certificate?
-
-That's certainly because you are using a self-signed certificate, despite the warnings.
-
-If you really insist on using these, you have to trust it at the OS level.
-
-Usually, on Ubuntu this is done with:
-
-    cp auth/domain.crt /usr/local/share/ca-certificates/myregistrydomain.com.crt
-    update-ca-certificates
-
-... and on RedHat with:
-
-    cp auth/domain.crt /etc/pki/ca-trust/source/anchors/myregistrydomain.com.crt
-    update-ca-trust
-
-Now:
-
- * `service docker stop && service docker start` (or any other way you use to restart docker)
- * `docker-compose up -d` to bring your registry up

docs/notifications.md

@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
-title = "Work with Notifications"
+title = "Working with notifications"
-description = "Explains work with registry notifications"
+description = "Explains how to work with registry notifications"
-keywords = ["registry, service, images, notifications,  repository"]
+keywords = ["registry, on-prem, images, tags, repository, distribution, notifications, advanced"]
 [menu.main]
 parent="smn_registry"
 weight=5
@@ -17,7 +17,7 @@ pushes and pulls and layer pushes and pulls. These actions are serialized into
 events. The events are queued into a registry-internal broadcast system which
 queues and dispatches events to [_Endpoints_](#endpoints).
 
-![](../images/notifications.png)
+![](images/notifications.png)
 
 ## Endpoints
 
@@ -63,7 +63,7 @@ INFO[0000] configuring endpoint alistener (https://mylistener.example.com/event)
 
 Events have a well-defined JSON structure and are sent as the body of
 notification requests. One or more events are sent in a structure called an
-envelope. Each event has a unique id that can be used to uniqify incoming
+envelope. Each event has a unique id that can be used to uniquely identify incoming
 requests, if required. Along with that, an _action_ is provided with a
 _target, identifying the object mutated during the event.
 
@@ -104,7 +104,7 @@ manifest:
 }
 ```
 
-> __NOTE(stevvooe):__ As of version 2.1, the `length` field for event targets
+> __NOTE:__ As of version 2.1, the `length` field for event targets
 > is being deprecated for the `size` field, bringing the target in line with
 > common nomenclature. Both will continue to be set for the foreseeable
 > future. Newer code should favor `size` but accept either.
@@ -234,7 +234,7 @@ The state of the endpoints are reported via the debug/vars http interface,
 usually configured to "http://localhost:5001/debug/vars". Information such as
 configuration and metrics are available by endpoint.
 
-The following provides and example of a few endpoints that have experience
+The following provides an example of a few endpoints that have experienced
 several failures and have since recovered:
 
 ```json
@@ -318,4 +318,3 @@ is a possibility, although it may have an effect on request service time.
 Please see the
 [godoc](http://godoc.org/github.com/docker/distribution/notifications#Sink)
 for more information.
-

docs/osx-setup-guide.md

@@ -1,62 +1,79 @@
 <!--[metadata]>
 +++
-draft = "true"
+title = "Running on OS X"
+description = "Explains how to run a registry on OS X"
+keywords = ["registry, on-prem, images, tags, repository, distribution, OS X, recipe, advanced"]
 +++
 <![end-metadata]-->
 
 # OS X Setup Guide
 
-This guide will walk you through running the new Go based [Docker registry](https://github.com/docker/distribution) on your local OS X machine.
+## Use-case
+
+This is useful if you intend to run a registry server natively on OS X.
+
+### Alternatives
+
+You can start a VM on OS X, and deploy your registry normally as a container using Docker inside that VM.
+
+The simplest road to get there is traditionally to use the [docker Toolbox](https://www.docker.com/toolbox), or [docker-machine](https://docs.docker.com/machine/), which usually relies on the [boot2docker](http://boot2docker.io/) iso inside a VirtualBox VM.
+
+### Solution
+
+Using the method described here, you install and compile your own from the git repository and run it as an OS X agent.
+
+### Gotchas
+
+Production services operation on OS X is out of scope of this document. Be sure you understand well these aspects before considering going to production with this.
+
+## Setup golang on your machine
+
+If you know, safely skip to the next section.
+
+If you don't, the TLDR is:
+
+    bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)
+    source ~/.gvm/scripts/gvm
+    gvm install go1.4.2
+    gvm use go1.4.2
+
+If you want to understand, you should read [How to Write Go Code](https://golang.org/doc/code.html).
 
 ## Checkout the Docker Distribution source tree
 
-```
+    mkdir -p $GOPATH/src/github.com/docker
-mkdir -p $GOPATH/src/github.com/docker
+    git clone https://github.com/docker/distribution.git $GOPATH/src/github.com/docker/distribution
-git clone https://github.com/docker/distribution.git $GOPATH/src/github.com/docker/distribution
+    cd $GOPATH/src/github.com/docker/distribution
-cd $GOPATH/src/github.com/docker/distribution
-```
 
-## Build the registry binary
+## Build the binary
 
-```
+    GOPATH=$(PWD)/Godeps/_workspace:$GOPATH make binaries
-GOPATH=$(PWD)/Godeps/_workspace:$GOPATH make binaries
+    sudo cp bin/registry /usr/local/libexec/registry
-sudo cp bin/registry /usr/local/libexec/registry
-```
 
 ## Setup
 
 Copy the registry configuration file in place:
 
-```
+    mkdir /Users/Shared/Registry
-mkdir /Users/Shared/Registry
+    cp docs/osx/config.yml /Users/Shared/Registry/config.yml
-cp docs/osx/config.yml /Users/Shared/Registry/config.yml
-```
 
 ## Running the Docker Registry under launchd
 
 Copy the Docker registry plist into place:
 
-```
+    plutil -lint docs/osx/com.docker.registry.plist
-plutil -lint docs/osx/com.docker.registry.plist
+    cp docs/osx/com.docker.registry.plist ~/Library/LaunchAgents/
-cp docs/osx/com.docker.registry.plist ~/Library/LaunchAgents/
+    chmod 644 ~/Library/LaunchAgents/com.docker.registry.plist
-chmod 644 ~/Library/LaunchAgents/com.docker.registry.plist
-```
 
 Start the Docker registry:
 
-```
+    launchctl load ~/Library/LaunchAgents/com.docker.registry.plist
-launchctl load ~/Library/LaunchAgents/com.docker.registry.plist
-```
 
 ### Restarting the docker registry service
 
-```
+    launchctl stop com.docker.registry
-launchctl stop com.docker.registry
+    launchctl start com.docker.registry
-launchctl start com.docker.registry
-```
 
 ### Unloading the docker registry service
 
-```
+    launchctl unload ~/Library/LaunchAgents/com.docker.registry.plist
-launchctl unload ~/Library/LaunchAgents/com.docker.registry.plist
-```

docs/recipes.md

@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
-title = "Recipes for Registry"
+title = "Recipes"
 description = "Fun stuff to do with your registry"
-keywords = ["registry, service, images, repository, recipe"]
+keywords = ["registry, on-prem, images, tags, repository, distribution, recipes, advanced"]
 +++
 <![end-metadata]-->
 
@@ -30,3 +30,6 @@ At this point, it's assumed that:
 
  * [using Apache as an authenticating proxy](apache.md)
  * [using Nginx as an authenticating proxy](nginx.md)
+ * [running a Registry on OS X](osx-setup-guide.md)
+ * [hacking the registry: build instructions](building.md)
+ * [mirror the Docker Hub](mirror.md)

docs/spec/api.md

@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
-title = "Docker Registry HTTP API V2"
+title = "HTTP API V2"
-description = "This is a specification for the API."
+description = "Specification for the Registry API."
-keywords = ["registry, service, driver, images, storage,  api"]
+keywords = ["registry, on-prem, images, tags, repository, distribution, api, advanced"]
 [menu.main]
 parent="smn_registry_ref"
 +++
@@ -21,7 +21,7 @@ of this API, known as _Docker Registry HTTP API V2_.
 While the V1 registry protocol is usable, there are several problems with the
 architecture that have led to this new version. The main driver of this
 specification these changes to the docker the image format, covered in
-docker/docker#8093. The new, self-contained image manifest simplifies image
+[docker/docker#8093](https://github.com/docker/docker/issues/8093). The new, self-contained image manifest simplifies image
 definition and improves security. This specification will build on that work,
 leveraging new properties of the manifest format to improve performance,
 reduce bandwidth usage and decrease the likelihood of backend corruption.

docs/spec/api.md.tmpl

@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
-title = "Docker Registry HTTP API V2"
+title = "HTTP API V2"
-description = "This is a specification for the API."
+description = "Specification for the Registry API."
-keywords = ["registry, service, driver, images, storage,  api"]
+keywords = ["registry, on-prem, images, tags, repository, distribution, api, advanced"]
 [menu.main]
 parent="smn_registry_ref"
 +++
@@ -21,7 +21,7 @@ of this API, known as _Docker Registry HTTP API V2_.
 While the V1 registry protocol is usable, there are several problems with the
 architecture that have led to this new version. The main driver of this
 specification these changes to the docker the image format, covered in
-docker/docker#8093. The new, self-contained image manifest simplifies image
+[docker/docker#8093](https://github.com/docker/docker/issues/8093). The new, self-contained image manifest simplifies image
 definition and improves security. This specification will build on that work,
 leveraging new properties of the manifest format to improve performance,
 reduce bandwidth usage and decrease the likelihood of backend corruption.

docs/spec/auth/token.md

@@ -1,15 +1,13 @@
 <!--[metadata]>
 +++
-title = "Docker Registry v2 Authentication"
+title = "Token Authentication"
 description = "Introduces the Docker Registry v2 authentication"
-keywords = ["registry, images, repository, v2,  authentication"]
+keywords = ["registry, on-prem, images, tags, repository, distribution, JWT authentication, advanced"]
 [menu.main]
 parent="smn_registry_ref"
 +++
 <![end-metadata]-->
 
-
-
 # Docker Registry v2 authentication via central service
 
 Today a Docker Registry can run in standalone mode in which there are no

docs/storagedrivers.md

@@ -1,11 +1,10 @@
 <!--[metadata]>
 +++
-title = "Docker Registry Storage Driver"
+title = "Storage Drivers"
-description = "Explains how to use the storage drivers"
+description = "Explains how to use storage drivers"
-keywords = ["registry, service, driver, images,  storage"]
+keywords = ["registry, on-prem, images, tags, repository, distribution, storage drivers, advanced"]
 [menu.main]
 parent="smn_registry_ref"
-identifier="smn_registry_drivers"
 +++
 <![end-metadata]-->
 
@@ -47,14 +46,17 @@ with a driver name and parameters map. If no such storage driver can be found,
 ## Driver Contribution
 
 ### Writing new storage drivers
+
 To create a valid storage driver, one must implement the
 `storagedriver.StorageDriver` interface and make sure to expose this driver
 via the factory system.
 
 #### Registering
+
 Storage drivers should call `factory.Register` with their driver name in an `init` method, allowing callers of `factory.New` to construct instances of this driver without requiring modification of imports throughout the codebase.
 
 ## Testing
+
 Storage driver test suites are provided in
 `storagedriver/testsuites/testsuites.go` and may be used for any storage
 driver written in Go. Tests can be registered using the `RegisterSuite`