diff --git a/docs/Dockerfile b/docs/Dockerfile index 8fa63a334..fcc634229 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -1,9 +1,9 @@ FROM docs/base:oss -MAINTAINER Mary Anthony (@moxiegirl) +MAINTAINER Docker Docs 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/ diff --git a/docs/Makefile b/docs/Makefile index 021e8f6e5..585bc871a 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,17 +1,4 @@ -.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)" diff --git a/docs/configuration.md b/docs/configuration.md index 6a1afb794..89dafda30 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1680,7 +1680,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. diff --git a/docs/deploying.md b/docs/deploying.md index 1e7f5dd64..b67d53969 100644 --- a/docs/deploying.md +++ b/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: @@ -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) diff --git a/docs/help.md b/docs/help.md index c6ac7ad95..77ec378f7 100644 --- a/docs/help.md +++ b/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). diff --git a/docs/index.md b/docs/index.md index 0252fcb53..2eb5f7678 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,11 +1,11 @@ diff --git a/docs/introduction.md b/docs/introduction.md index e8b05d8cc..eceb5ffc1 100644 --- a/docs/introduction.md +++ b/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 diff --git a/docs/overview.md b/docs/menu.md similarity index 82% rename from docs/overview.md rename to docs/menu.md index d3532b62e..7e24a6907 100644 --- a/docs/overview.md +++ b/docs/menu.md @@ -1,10 +1,12 @@ @@ -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) diff --git a/docs/apache.md b/docs/recipes/apache.md similarity index 97% rename from docs/apache.md rename to docs/recipes/apache.md index f694ca3e2..ac24113b2 100644 --- a/docs/apache.md +++ b/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" +++ @@ -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? diff --git a/docs/building.md b/docs/recipes/building.md similarity index 99% rename from docs/building.md rename to docs/recipes/building.md index 126a455a3..4d67593ae 100644 --- a/docs/building.md +++ b/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" +++ diff --git a/docs/recipes.md b/docs/recipes/index.md similarity index 89% rename from docs/recipes.md rename to docs/recipes/index.md index c9f64d535..df74ca2bf 100644 --- a/docs/recipes.md +++ b/docs/recipes/index.md @@ -1,11 +1,11 @@ @@ -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. diff --git a/docs/recipes/menu.md b/docs/recipes/menu.md new file mode 100644 index 000000000..5fdbec5b4 --- /dev/null +++ b/docs/recipes/menu.md @@ -0,0 +1,22 @@ + + +# 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) diff --git a/docs/mirror.md b/docs/recipes/mirror.md similarity index 99% rename from docs/mirror.md rename to docs/recipes/mirror.md index feb2630c0..ff437ba45 100644 --- a/docs/mirror.md +++ b/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" +++ diff --git a/docs/nginx.md b/docs/recipes/nginx.md similarity index 97% rename from docs/nginx.md rename to docs/recipes/nginx.md index 361a10630..f4a676791 100644 --- a/docs/nginx.md +++ b/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" +++ @@ -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? diff --git a/docs/osx-setup-guide.md b/docs/recipes/osx-setup-guide.md similarity index 94% rename from docs/osx-setup-guide.md rename to docs/recipes/osx-setup-guide.md index 15a26ff45..d47d31c10 100644 --- a/docs/osx-setup-guide.md +++ b/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" +++ @@ -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 diff --git a/docs/osx/com.docker.registry.plist b/docs/recipes/osx/com.docker.registry.plist similarity index 100% rename from docs/osx/com.docker.registry.plist rename to docs/recipes/osx/com.docker.registry.plist diff --git a/docs/osx/config.yml b/docs/recipes/osx/config.yml similarity index 100% rename from docs/osx/config.yml rename to docs/recipes/osx/config.yml diff --git a/docs/spec/auth/index.md b/docs/spec/auth/index.md index b123af1ae..f6ee8e1fa 100644 --- a/docs/spec/auth/index.md +++ b/docs/spec/auth/index.md @@ -3,6 +3,9 @@ title = "Docker Registry Token Authentication" description = "Docker Registry v2 authentication schema" keywords = ["registry, on-prem, images, tags, repository, distribution, authentication, advanced"] +[menu.main] +parent="smn_registry_ref" +weight=100 +++ diff --git a/docs/spec/auth/jwt.md b/docs/spec/auth/jwt.md index 87de62af1..c90bd6e86 100644 --- a/docs/spec/auth/jwt.md +++ b/docs/spec/auth/jwt.md @@ -5,6 +5,7 @@ description = "Describe the reference implementation of the Docker Registry v2 a keywords = ["registry, on-prem, images, tags, repository, distribution, JWT authentication, advanced"] [menu.main] parent="smn_registry_ref" +weight=101 +++ diff --git a/docs/spec/auth/oauth.md b/docs/spec/auth/oauth.md index 1311df5d1..3d1ae0aa4 100644 --- a/docs/spec/auth/oauth.md +++ b/docs/spec/auth/oauth.md @@ -5,6 +5,7 @@ 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 +++ diff --git a/docs/spec/auth/scope.md b/docs/spec/auth/scope.md index e626b6e14..a8f6c0628 100644 --- a/docs/spec/auth/scope.md +++ b/docs/spec/auth/scope.md @@ -5,6 +5,7 @@ description = "Describes the scope and access fields used for registry authoriza keywords = ["registry, on-prem, images, tags, repository, distribution, advanced, access, scope"] [menu.main] parent="smn_registry_ref" +weight=103 +++ diff --git a/docs/spec/auth/token.md b/docs/spec/auth/token.md index 654826992..12dfc6852 100644 --- a/docs/spec/auth/token.md +++ b/docs/spec/auth/token.md @@ -5,6 +5,7 @@ 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 +++ diff --git a/docs/spec/index.md b/docs/spec/index.md index dddaa5288..474bd455c 100644 --- a/docs/spec/index.md +++ b/docs/spec/index.md @@ -1,18 +1,17 @@ # Docker Registry Reference * [HTTP API V2](api.md) -* [Storage Driver](../storagedrivers.md) +* [Storage Driver](../storage-drivers/index.md) * [Token Authentication Specification](auth/token.md) * [Token Authentication Implementation](auth/jwt.md) diff --git a/docs/spec/menu.md b/docs/spec/menu.md new file mode 100644 index 000000000..ebc52327b --- /dev/null +++ b/docs/spec/menu.md @@ -0,0 +1,13 @@ + + diff --git a/docs/storage-drivers/azure.md b/docs/storage-drivers/azure.md index 2783c427e..a84888de8 100644 --- a/docs/storage-drivers/azure.md +++ b/docs/storage-drivers/azure.md @@ -3,6 +3,8 @@ title = "Microsoft Azure storage driver" description = "Explains how to use the Azure storage drivers" keywords = ["registry, service, driver, images, storage, azure"] +[menu.main] +parent = "smn_storagedrivers" +++ diff --git a/docs/storage-drivers/filesystem.md b/docs/storage-drivers/filesystem.md index fea7ce4a8..8e269cdbc 100644 --- a/docs/storage-drivers/filesystem.md +++ b/docs/storage-drivers/filesystem.md @@ -3,6 +3,8 @@ title = "Filesystem storage driver" description = "Explains how to use the filesystem storage drivers" keywords = ["registry, service, driver, images, storage, filesystem"] +[menu.main] +parent="smn_storagedrivers" +++ diff --git a/docs/storage-drivers/gcs.md b/docs/storage-drivers/gcs.md index 0aa9b30dd..1bc67f9ed 100644 --- a/docs/storage-drivers/gcs.md +++ b/docs/storage-drivers/gcs.md @@ -3,6 +3,8 @@ title = "GCS storage driver" description = "Explains how to use the Google Cloud Storage drivers" keywords = ["registry, service, driver, images, storage, gcs, google, cloud"] +[menu.main] +parent="smn_storagedrivers" +++ diff --git a/docs/storage-drivers/index.md b/docs/storage-drivers/index.md index 2de729ad1..89635bd37 100644 --- a/docs/storage-drivers/index.md +++ b/docs/storage-drivers/index.md @@ -1,7 +1,66 @@ + + +# Docker Registry Storage Driver + +This document describes the registry storage driver model, implementation, and explains how to contribute new storage drivers. + +## Provided Drivers + +This storage driver package comes bundled with several drivers: + +- [inmemory](inmemory.md): A temporary storage driver using a local inmemory map. This exists solely for reference and testing. +- [filesystem](filesystem.md): A local storage driver configured to use a directory tree in the local filesystem. +- [s3](s3.md): A driver storing objects in an Amazon Simple Storage Solution (S3) bucket. +- [azure](azure.md): A driver storing objects in [Microsoft Azure Blob Storage](http://azure.microsoft.com/en-us/services/storage/). +- [swift](swift.md): A driver storing objects in [Openstack Swift](http://docs.openstack.org/developer/swift/). +- [oss](oss.md): A driver storing objects in [Aliyun OSS](http://www.aliyun.com/product/oss). +- [gcs](gcs.md): A driver storing objects in a [Google Cloud Storage](https://cloud.google.com/storage/) bucket. + +## Storage Driver API + +The storage driver API is designed to model a filesystem-like key/value storage in a manner abstract enough to support a range of drivers from the local filesystem to Amazon S3 or other distributed object storage systems. + +Storage drivers are required to implement the `storagedriver.StorageDriver` interface provided in `storagedriver.go`, which includes methods for reading, writing, and deleting content, as well as listing child objects of a specified prefix key. + +Storage drivers are intended to be written in Go, providing compile-time +validation of the `storagedriver.StorageDriver` interface. + +## Driver Selection and Configuration + +The preferred method of selecting a storage driver is using the `StorageDriverFactory` interface in the `storagedriver/factory` package. These factories provide a common interface for constructing storage drivers with a parameters map. The factory model is based off of the [Register](http://golang.org/pkg/database/sql/#Register) and [Open](http://golang.org/pkg/database/sql/#Open) methods in the builtin [database/sql](http://golang.org/pkg/database/sql) package. + +Storage driver factories may be registered by name using the +`factory.Register` method, and then later invoked by calling `factory.Create` +with a driver name and parameters map. If no such storage driver can be found, +`factory.Create` will return an `InvalidStorageDriverError`. + +## 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` +function, which run the same set of tests for any registered drivers. diff --git a/docs/storage-drivers/inmemory.md b/docs/storage-drivers/inmemory.md index 3109891e2..1a14e77a2 100644 --- a/docs/storage-drivers/inmemory.md +++ b/docs/storage-drivers/inmemory.md @@ -3,6 +3,8 @@ title = "In-memory storage driver" description = "Explains how to use the in-memory storage drivers" keywords = ["registry, service, driver, images, storage, in-memory"] +[menu.main] +parent="smn_storagedrivers" +++ diff --git a/docs/storage-drivers/menu.md b/docs/storage-drivers/menu.md new file mode 100644 index 000000000..3638649fc --- /dev/null +++ b/docs/storage-drivers/menu.md @@ -0,0 +1,13 @@ + + diff --git a/docs/storage-drivers/oss.md b/docs/storage-drivers/oss.md index 2087c98d2..a85e315e2 100644 --- a/docs/storage-drivers/oss.md +++ b/docs/storage-drivers/oss.md @@ -3,6 +3,8 @@ title = "Aliyun OSS storage driver" description = "Explains how to use the Aliyun OSS storage driver" keywords = ["registry, service, driver, images, storage, OSS, aliyun"] +[menu.main] +parent="smn_storagedrivers" +++ diff --git a/docs/storage-drivers/s3.md b/docs/storage-drivers/s3.md index d78fc988c..97cfbfc18 100644 --- a/docs/storage-drivers/s3.md +++ b/docs/storage-drivers/s3.md @@ -3,6 +3,8 @@ title = "S3 storage driver" description = "Explains how to use the S3 storage drivers" keywords = ["registry, service, driver, images, storage, S3"] +[menu.main] +parent="smn_storagedrivers" +++ diff --git a/docs/storage-drivers/swift.md b/docs/storage-drivers/swift.md index cab0bbd20..0cf582d12 100644 --- a/docs/storage-drivers/swift.md +++ b/docs/storage-drivers/swift.md @@ -3,6 +3,8 @@ title = "Swift storage driver" description = "Explains how to use the OpenStack swift storage driver" keywords = ["registry, service, driver, images, storage, swift"] +[menu.main] +parent="smn_storagedrivers" +++ diff --git a/docs/storagedrivers.md b/docs/storagedrivers.md deleted file mode 100644 index ab475c32c..000000000 --- a/docs/storagedrivers.md +++ /dev/null @@ -1,64 +0,0 @@ - - - -# Docker Registry Storage Driver - -This document describes the registry storage driver model, implementation, and explains how to contribute new storage drivers. - -## Provided Drivers - -This storage driver package comes bundled with several drivers: - -- [inmemory](storage-drivers/inmemory.md): A temporary storage driver using a local inmemory map. This exists solely for reference and testing. -- [filesystem](storage-drivers/filesystem.md): A local storage driver configured to use a directory tree in the local filesystem. -- [s3](storage-drivers/s3.md): A driver storing objects in an Amazon Simple Storage Solution (S3) bucket. -- [azure](storage-drivers/azure.md): A driver storing objects in [Microsoft Azure Blob Storage](http://azure.microsoft.com/en-us/services/storage/). -- [swift](storage-drivers/swift.md): A driver storing objects in [Openstack Swift](http://docs.openstack.org/developer/swift/). -- [oss](storage-drivers/oss.md): A driver storing objects in [Aliyun OSS](http://www.aliyun.com/product/oss). -- [gcs](storage-drivers/gcs.md): A driver storing objects in a [Google Cloud Storage](https://cloud.google.com/storage/) bucket. - -## Storage Driver API - -The storage driver API is designed to model a filesystem-like key/value storage in a manner abstract enough to support a range of drivers from the local filesystem to Amazon S3 or other distributed object storage systems. - -Storage drivers are required to implement the `storagedriver.StorageDriver` interface provided in `storagedriver.go`, which includes methods for reading, writing, and deleting content, as well as listing child objects of a specified prefix key. - -Storage drivers are intended to be written in Go, providing compile-time -validation of the `storagedriver.StorageDriver` interface. - -## Driver Selection and Configuration - -The preferred method of selecting a storage driver is using the `StorageDriverFactory` interface in the `storagedriver/factory` package. These factories provide a common interface for constructing storage drivers with a parameters map. The factory model is based off of the [Register](http://golang.org/pkg/database/sql/#Register) and [Open](http://golang.org/pkg/database/sql/#Open) methods in the builtin [database/sql](http://golang.org/pkg/database/sql) package. - -Storage driver factories may be registered by name using the -`factory.Register` method, and then later invoked by calling `factory.Create` -with a driver name and parameters map. If no such storage driver can be found, -`factory.Create` will return an `InvalidStorageDriverError`. - -## 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` -function, which run the same set of tests for any registered drivers.