Merge pull request #1758 from SvenDowideit/31may2016-docs-updates

31may2016 docs updates

docs/Dockerfile

 FROM docs/base:oss
-MAINTAINER Mary Anthony <mary@docker.com> (@moxiegirl)
+MAINTAINER Docker Docs <docs@docker.com>
 
 ENV PROJECT=registry
 
 # To get the git info for this repo
 COPY . /src
-RUN rm -r /docs/content/$PROJECT/
+RUN rm -rf /docs/content/$PROJECT/
 COPY . /docs/content/$PROJECT/

docs/Makefile

-.PHONY: all binary build cross default docs docs-build docs-shell shell test test-unit test-integration test-integration-cli test-docker-py validate
-
-# env vars passed through directly to Docker's build scripts
-# to allow things like `make DOCKER_CLIENTONLY=1 binary` easily
-# `docs/sources/contributing/devenvironment.md ` and `project/PACKAGERS.md` have some limited documentation of some of these
-DOCKER_ENVS := \
-	-e BUILDFLAGS \
-	-e DOCKER_CLIENTONLY \
-	-e DOCKER_EXECDRIVER \
-	-e DOCKER_GRAPHDRIVER \
-	-e TESTDIRS \
-	-e TESTFLAGS \
-	-e TIMEOUT
-# note: we _cannot_ add "-e DOCKER_BUILDTAGS" here because even if it's unset in the shell, that would shadow the "ENV DOCKER_BUILDTAGS" set in our Dockerfile, which is very important for our official builds
+.PHONY: all default docs docs-build docs-shell shell test
 
 # to allow `make DOCSDIR=docs docs-shell` (to create a bind mount in docs)
 DOCS_MOUNT := $(if $(DOCSDIR),-v $(CURDIR)/$(DOCSDIR):/$(DOCSDIR))
@@ -25,9 +12,8 @@ HUGO_BASE_URL=$(shell test -z "$(DOCKER_IP)" && echo localhost || echo "$(DOCKER
 HUGO_BIND_IP=0.0.0.0
 
 GIT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD 2>/dev/null)
-DOCKER_IMAGE := docker$(if $(GIT_BRANCH),:$(GIT_BRANCH))
-DOCKER_DOCS_IMAGE := docs-base$(if $(GIT_BRANCH),:$(GIT_BRANCH))
-
+GIT_BRANCH_CLEAN := $(shell echo $(GIT_BRANCH) | sed -e "s/[^[:alnum:]]/-/g")
+DOCKER_DOCS_IMAGE := registry-docs$(if $(GIT_BRANCH_CLEAN),:$(GIT_BRANCH_CLEAN))
 
 DOCKER_RUN_DOCS := docker run --rm -it $(DOCS_MOUNT) -e AWS_S3_BUCKET -e NOCACHE
 
@@ -42,14 +28,11 @@ docs: docs-build
 docs-draft: docs-build
 	$(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 -e DOCKERHOST "$(DOCKER_DOCS_IMAGE)" hugo server --buildDrafts="true" --port=$(DOCSPORT) --baseUrl=$(HUGO_BASE_URL) --bind=$(HUGO_BIND_IP)
 
-
 docs-shell: docs-build
 	$(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 "$(DOCKER_DOCS_IMAGE)" bash
 
-
 docs-build:
-#	( git remote | grep -v upstream ) || git diff --name-status upstream/release..upstream/docs ./ > ./changed-files
-#	echo "$(GIT_BRANCH)" > GIT_BRANCH
-#	echo "$(AWS_S3_BUCKET)" > AWS_S3_BUCKET
-#	echo "$(GITCOMMIT)" > GITCOMMIT
 	docker build -t "$(DOCKER_DOCS_IMAGE)" .
+
+test: docs-build
+	$(DOCKER_RUN_DOCS) "$(DOCKER_DOCS_IMAGE)"

docs/compatibility.md

 <!--[metadata]>
 +++
-title = "registry Compatibility"
+title = "Compatibility"
 description = "describes get by digest pitfall"
 keywords = ["registry, manifest, images, tags, repository, distribution, digest"]
+[menu.main]
+parent="smn_registry_ref"
+weight=9
 +++
 <![end-metadata]-->
 
@@ -15,7 +18,7 @@ will cause the Engine to receive a manifest it cannot use and the pull will fail
 
 ## Registry Manifest Support
 
-Historically, the registry has supported a [single manifest type](https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-1.md)
+Historically, the registry has supported a [single manifest type](./spec/manifest-v2-1.md)
 known as _Schema 1_.
 
 With the move toward multiple architecture images the distribution project
@@ -78,4 +81,4 @@ constraints of CAS.*
 For this reason 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 will cause the Engine to receive a manifest it cannot use and the
-pull will fail.
\ No newline at end of file
+pull will fail.

docs/configuration.md

@@ -1667,7 +1667,7 @@ The TCP address to connect to, including a port number.
       username: [username]
       password: [password]
 
-Proxy enables a registry to be configured as a pull through cache to the official Docker Hub.  See [mirror](mirror.md) for more information. Pushing to a registry configured as a pull through cache is currently unsupported.
+Proxy enables a registry to be configured as a pull through cache to the official Docker Hub.  See [mirror](recipes/mirror.md) for more information. Pushing to a registry configured as a pull through cache is currently unsupported.
 
 <table>
   <tr>

docs/deploying.md

@@ -11,7 +11,7 @@ weight=3
 
 # Deploying a registry server
 
-You need to [install Docker version 1.6.0 or newer](https://docs.docker.com/installation/).
+You need to [install Docker version 1.6.0 or newer](/engine/installation/index.md).
 
 ## Running on localhost
 
@@ -39,7 +39,7 @@ To stop your registry, you would:
 
 ## Storage
 
-By default, your registry data is persisted as a [docker volume](https://docs.docker.com/userguide/dockervolumes/) on the host filesystem. Properly understanding volumes is essential if you want to stick with a local filesystem storage.
+By default, your registry data is persisted as a [docker volume](/engine/userguide/containers/dockervolumes.md) on the host filesystem. Properly understanding volumes is essential if you want to stick with a local filesystem storage.
 
 Specifically, you might want to point your volume location to a specific place in order to more easily access your registry data. To do so you can:
 
@@ -49,7 +49,7 @@ Specifically, you might want to point your volume location to a specific place i
 
 ### Alternatives
 
-You should usually consider using [another storage backend](https://github.com/docker/distribution/blob/master/docs/storagedrivers.md) instead of the local filesystem. Use the [storage configuration options](https://github.com/docker/distribution/blob/master/docs/configuration.md#storage) to configure an alternate storage backend.
+You should usually consider using [another storage backend](./storage-drivers/index.md) instead of the local filesystem. Use the [storage configuration options](./configuration.md#storage) to configure an alternate storage backend.
 
 Using one of these will allow you to more easily scale your registry, and leverage your storage redundancy and availability features. 
 
@@ -180,7 +180,7 @@ Seeing X509 errors is usually a sign you are trying to use self-signed certifica
 
 ### 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).
+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/index.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 makes sense if you want to fully configure ACLs and more control over the Registry integration into your global authorization and authentication systems.
 
@@ -192,7 +192,7 @@ Beware that you will have to implement your own authentication service for this
 
 As your registry configuration grows more complex, dealing with it can quickly become tedious.
 
-It's highly recommended to use [Docker Compose](https://docs.docker.com/compose/) to facilitate operating your registry. 
+It's highly recommended to use [Docker Compose](/compose/index.md) to facilitate operating your registry. 
 
 Here is a simple `docker-compose.yml` example that condenses everything explained so far:
 
@@ -226,7 +226,7 @@ You will find more specific and advanced informations in the following sections:
 
  - [Configuration reference](configuration.md)
  - [Working with notifications](notifications.md)
- - [Advanced "recipes"](recipes.md)
+ - [Advanced "recipes"](recipes/index.md)
  - [Registry API](spec/api.md)
- - [Storage driver model](storagedrivers.md)
+ - [Storage driver model](storage-drivers/index.md)
  - [Token authentication](spec/auth/token.md)

docs/garbage-collection.md

@@ -3,6 +3,9 @@
 title = "Garbage Collection"
 description = "High level discussion of garbage collection"
 keywords = ["registry, garbage, images, tags, repository, distribution"]
+[menu.main]
+parent="smn_registry_ref"
+weight=4
 +++
 <![end-metadata]-->
 

docs/help.md

@@ -21,4 +21,4 @@ If you want to report a bug:
 - be sure to first read about [how to contribute](https://github.com/docker/distribution/blob/master/CONTRIBUTING.md)
 - you can then do so on the [GitHub project bugtracker](https://github.com/docker/distribution/issues)
 
-You can also find out more about the Docker's project [Getting Help resources](https://docs.docker.com/opensource/get-help/).
+You can also find out more about the Docker's project [Getting Help resources](/opensource/get-help.md).

docs/index.md

 <!--[metadata]>
 +++
-title = "Docker Registry"
+title = "Registry Overview"
 description = "High-level overview of the Registry"
 keywords = ["registry, on-prem, images, tags, repository, distribution"]
+aliases = ["/registry/overview/"]
 [menu.main]
-identifier="smn_registry"
-parent="mn_components"
+parent="smn_registry"
+weight=1
 +++
 <![end-metadata]-->
 
@@ -28,7 +29,7 @@ You should use the Registry if you want to:
 
 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](https://docs.docker.com/docker-trusted-registry/).
+Users looking for a commercially supported version of the Registry should look into [Docker Trusted Registry](/docker-trusted-registry/overview.md).
 
 ## Requirements
 

docs/insecure.md

@@ -3,6 +3,9 @@
 title = "Testing an insecure registry"
 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
 +++
 <![end-metadata]-->
 
@@ -60,7 +63,7 @@ This is more secure than the insecure registry solution.  You must configure eve
 
 2. Be sure to use the name `myregistrydomain.com` as a CN.
 
-3. Use the result to [start your registry with TLS enabled](https://github.com/docker/distribution/blob/master/docs/deploying.md#get-a-certificate)
+3. Use the result to [start your registry with TLS enabled](./deploying.md#get-a-certificate)
 
 4. Instruct every docker daemon to trust that certificate.
 

docs/introduction.md

@@ -19,7 +19,7 @@ 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](storagedrivers.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.
 
@@ -34,7 +34,7 @@ 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](https://docs.docker.com/reference/commandline/cli/).
+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
 

docs/overview.md → docs/menu.md

 <!--[metadata]>
 +++
-title = "Registry Overview"
+title = "Docker Registry"
 description = "High-level overview of the Registry"
 keywords = ["registry, on-prem, images, tags, repository, distribution"]
+type = "menu"
 [menu.main]
-parent="smn_registry"
+identifier="smn_registry"
+parent="mn_components"
 +++
 <![end-metadata]-->
 
@@ -17,5 +19,5 @@ The Docker Registry documentation includes the following topics:
 * [Deploying a registry server](deploying.md)
 * [Registry Configuration Reference](configuration.md)
 * [Notifications](notifications.md)
-* [Recipes](recipes.md)
+* [Recipes](recipes/index.md)
 * [Getting help](help.md)

docs/apache.md → docs/recipes/apache.md

@@ -3,6 +3,8 @@
 title = "Authenticating proxy with apache"
 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"
 +++
 <![end-metadata]-->
 
@@ -16,7 +18,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
 
@@ -34,7 +36,7 @@ Furthermore, introducing an extra http layer in your communication pipeline will
 
 ## Setting things up
 
-Read again [the requirements](recipes.md#requirements).
+Read again [the requirements](index.md#requirements).
 
 Ready?
 

docs/building.md → docs/recipes/building.md

@@ -3,6 +3,8 @@
 title = "Build instructions"
 description = "Explains how to build & hack on the registry"
 keywords = ["registry, on-prem, images, tags, repository, distribution, build, recipe, advanced"]
+[menu.main]
+parent="smn_recipes"
 +++
 <![end-metadata]-->
 

docs/recipes.md → docs/recipes/index.md

 <!--[metadata]>
 +++
-title = "Recipes"
+title = "Recipes Overview"
 description = "Fun stuff to do with your registry"
 keywords = ["registry, on-prem, images, tags, repository, distribution, recipes, advanced"]
 [menu.main]
-parent="smn_registry"
-weight=7
+parent="smn_recipes"
+weight=-10
 +++
 <![end-metadata]-->
 
@@ -17,7 +17,7 @@ Most users are not expected to have a use for these.
 
 ## Requirements
 
-You should have followed entirely the basic [deployment guide](deploying.md).
+You should have followed entirely the basic [deployment guide](../deploying.md).
 
 If you have not, please take the time to do so.
 

docs/recipes/menu.md

+<!--[metadata]>
++++
+title = "Recipes"
+description = "Registry Recipes"
+keywords = ["registry, on-prem, images, tags, repository, distribution"]
+type = "menu"
+[menu.main]
+identifier="smn_recipes"
+parent="smn_registry"
+weight=6
++++
+<![end-metadata]-->
+
+# Recipes
+
+## The List
+
+ * [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/mirror.md → docs/recipes/mirror.md

@@ -3,6 +3,8 @@
 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"]
+[menu.main]
+parent="smn_recipes"
 +++
 <![end-metadata]-->
 

docs/nginx.md → docs/recipes/nginx.md

@@ -3,6 +3,8 @@
 title = "Authenticating proxy with nginx"
 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"
 +++
 <![end-metadata]-->
 
@@ -17,7 +19,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
 
@@ -53,7 +55,7 @@ Otherwise nginx will reset the ELB's values, and the requests will not be routed
 
 ## Setting things up
 
-Read again [the requirements](recipes.md#requirements).
+Read again [the requirements](index.md#requirements).
 
 Ready?
 

docs/osx-setup-guide.md → docs/recipes/osx-setup-guide.md

@@ -3,6 +3,8 @@
 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"]
+[menu.main]
+parent="smn_recipes"
 +++
 <![end-metadata]-->
 
@@ -16,7 +18,7 @@ This is useful if you intend to run a registry server natively on OS X.
 
 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.
+The simplest road to get there is traditionally to use the [docker Toolbox](https://www.docker.com/toolbox), or [docker-machine](/machine/index.md), which usually relies on the [boot2docker](http://boot2docker.io/) iso inside a VirtualBox VM.
 
 ### Solution