From d58bf9ed47f962d8d337f18e10975b29707acd22 Mon Sep 17 00:00:00 2001 From: Ian Babrou Date: Mon, 20 Apr 2015 10:41:32 +0300 Subject: [PATCH] docs: fixed links for storage drivers Signed-off-by: Ian Babrou (cherry picked from commit 824e7e8ae25299b5953e38088c085198774f945f) Conflicts: docs/mkdocs.yml Add environment variable override instructions Signed-off-by: Richard Scothern (cherry picked from commit 937c3565856344e85ee93ba282916f76bccbb21b) Fixing headings Signed-off-by: Mary Anthony (cherry picked from commit 7c93c8c265fe7cf1c59f857d7049c39902e854a0) Fixes Issue #471 with Publish - Add sed to Dockerfile; this sed exists on publish script; breaks headings/nav in files without metadata - Ensure sed runs over storage-driver/ subdir - Add metadata to all the files (including specs) that don't have it; this ensures they display correctly on publish - Implement the fix for the showing up in Github - Update template with GITHUB IGNORES Signed-off-by: Mary Anthony (cherry picked from commit 68c0682e0005193a83303125441eea1cb042bb4c) --- docs/Dockerfile | 15 ++++++++++++- docs/configuration.md | 14 ++++++++++++ docs/deploying.md | 3 +++ docs/index.md | 2 ++ docs/mkdocs.yml | 3 --- docs/notifications.md | 3 +++ docs/spec/api.md | 6 +++++ docs/spec/api.md.tmpl | 6 +++++ docs/spec/auth/token.md | 7 ++++++ docs/spec/json.md | 7 ++++++ docs/storage-drivers/azure.md | 7 +++++- docs/storage-drivers/filesystem.md | 6 +++++ docs/storage-drivers/inmemory.md | 6 +++++ docs/storage-drivers/s3.md | 6 +++++ docs/storagedrivers.md | 35 +++++++++++++++--------------- 15 files changed, 104 insertions(+), 22 deletions(-) diff --git a/docs/Dockerfile b/docs/Dockerfile index 1613e13aa..d4e60012c 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -7,11 +7,13 @@ COPY . /src # Reset the /docs dir so we can replace the theme meta with the new repo's git info RUN git reset --hard +RUN grep "VERSION =" /src/version/version.go | sed 's/.*"\(.*\)".*/\1/' > /docs/VERSION + + # # RUN git describe --match 'v[0-9]*' --dirty='.m' --always > /docs/VERSION # The above line causes a floating point error in our tools # -RUN grep "VERSION =" /src/version/version.go | sed 's/.*"\(.*\)".*/\1/' > /docs/VERSION COPY docs/* /docs/sources/registry/ COPY docs/images/* /docs/sources/registry/images/ COPY docs/spec/* /docs/sources/registry/spec/ @@ -19,6 +21,17 @@ COPY docs/spec/auth/* /docs/sources/registry/spec/auth/ COPY docs/storage-drivers/* /docs/sources/registry/storage-drivers/ COPY docs/mkdocs.yml /docs/mkdocs-distribution.yml +RUN sed -i.old '1s;^;no_version_dropdown: true;' \ + /docs/sources/registry/*.md \ + /docs/sources/registry/spec/*.md \ + /docs/sources/registry/spec/auth/*.md \ + /docs/sources/registry/storage-drivers/*.md + +RUN sed -i.old -e '/^/g'\ + /docs/sources/registry/*.md \ + /docs/sources/registry/spec/*.md \ + /docs/sources/registry/spec/auth/*.md \ + /docs/sources/registry/storage-drivers/*.md # Then build everything together, ready for mkdocs RUN /docs/build.sh diff --git a/docs/configuration.md b/docs/configuration.md index 0b59f41b9..b3105b3f5 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,6 +1,8 @@ + # Registry Configuration Reference @@ -9,6 +11,18 @@ You configure a registry server using a YAML file. This page explains the configuration options and the values they can take. You'll also find examples of middleware and development environment configurations. +## Overriding configuration options +Environment variables may be used to override configuration parameters other than +version. To override a configuration option, create an environment variable named +REGISTRY\_variable_ where *variable* is the name of the configuration option. + +e.g +``` +REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/tmp/registry/test +``` + +will set the storage root directory to `/tmp/registry/test` + ## List of configuration options This section lists all the registry configuration options. Some options in diff --git a/docs/deploying.md b/docs/deploying.md index c7d3d17cf..7aa5b9055 100644 --- a/docs/deploying.md +++ b/docs/deploying.md @@ -1,6 +1,9 @@ + + # Deploying a registry server diff --git a/docs/index.md b/docs/index.md index 7c21d17ff..f8f9c8b06 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,8 @@ + # Docker Registry 2.0 diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 73eefec41..844658206 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -7,10 +7,7 @@ - ['registry/spec/json.md', 'Reference', '    ▪  JSON format' ] - ['registry/spec/auth/token.md', 'Reference', '    ▪  Authenticate via central service' ] -<<<<<<< HEAD -======= - ['registry/storage-drivers/azure.md', '**HIDDEN**' ] - ['registry/storage-drivers/filesystem.md', '**HIDDEN**' ] - ['registry/storage-drivers/inmemory.md', '**HIDDEN**' ] - ['registry/storage-drivers/s3.md','**HIDDEN**' ] ->>>>>>> d5c0300... Pushing fix for mkdocs.yml introduced diff --git a/docs/notifications.md b/docs/notifications.md index b8fdf3716..fb5897fc9 100644 --- a/docs/notifications.md +++ b/docs/notifications.md @@ -1,6 +1,9 @@ + + # Notifications diff --git a/docs/spec/api.md b/docs/spec/api.md index 032ddcf3c..2c3acabf7 100644 --- a/docs/spec/api.md +++ b/docs/spec/api.md @@ -1,3 +1,9 @@ + + # Docker Registry HTTP API V2 ## Introduction diff --git a/docs/spec/api.md.tmpl b/docs/spec/api.md.tmpl index 1a68a4744..68a7dff9c 100644 --- a/docs/spec/api.md.tmpl +++ b/docs/spec/api.md.tmpl @@ -1,3 +1,9 @@ + + # Docker Registry HTTP API V2 ## Introduction diff --git a/docs/spec/auth/token.md b/docs/spec/auth/token.md index 921622578..5a394cbe4 100644 --- a/docs/spec/auth/token.md +++ b/docs/spec/auth/token.md @@ -1,3 +1,10 @@ + + + # Docker Registry v2 authentication via central service Today a Docker Registry can run in standalone mode in which there are no diff --git a/docs/spec/json.md b/docs/spec/json.md index 5504a40bf..34440c717 100644 --- a/docs/spec/json.md +++ b/docs/spec/json.md @@ -1,3 +1,10 @@ + + + # Docker Distribution JSON Canonicalization To provide consistent content hashing of JSON objects throughout Docker diff --git a/docs/storage-drivers/azure.md b/docs/storage-drivers/azure.md index 630034dbf..fd46ece39 100644 --- a/docs/storage-drivers/azure.md +++ b/docs/storage-drivers/azure.md @@ -1,5 +1,10 @@ -# Microsoft Azure storage driver + +# Microsoft Azure storage driver An implementation of the `storagedriver.StorageDriver` interface which uses [Microsoft Azure Blob Storage][azure-blob-storage] for object storage. diff --git a/docs/storage-drivers/filesystem.md b/docs/storage-drivers/filesystem.md index e5620913c..fa9f8259e 100644 --- a/docs/storage-drivers/filesystem.md +++ b/docs/storage-drivers/filesystem.md @@ -1,3 +1,9 @@ + + # Filesystem storage driver An implementation of the `storagedriver.StorageDriver` interface which uses the local filesystem. diff --git a/docs/storage-drivers/inmemory.md b/docs/storage-drivers/inmemory.md index a2ebc9e88..948cd5bcb 100644 --- a/docs/storage-drivers/inmemory.md +++ b/docs/storage-drivers/inmemory.md @@ -1,3 +1,9 @@ + + # In-memory storage driver An implementation of the `storagedriver.StorageDriver` interface which uses local memory for object storage. diff --git a/docs/storage-drivers/s3.md b/docs/storage-drivers/s3.md index e2714a4b3..e6c113485 100644 --- a/docs/storage-drivers/s3.md +++ b/docs/storage-drivers/s3.md @@ -1,3 +1,9 @@ + + # S3 storage driver An implementation of the `storagedriver.StorageDriver` interface which uses Amazon S3 for object storage. diff --git a/docs/storagedrivers.md b/docs/storagedrivers.md index 788bdd0d7..e476457d3 100644 --- a/docs/storagedrivers.md +++ b/docs/storagedrivers.md @@ -1,20 +1,23 @@ -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 -================ +## Provided Drivers This storage driver package comes bundled with several drivers: -- [inmemory](storage-drivers/inmemory): A temporary storage driver using a local inmemory map. This exists solely for reference and testing. -- [filesystem](storage-drivers/filesystem): A local storage driver configured to use a directory tree in the local filesystem. -- [s3](storage-drivers/s3): A driver storing objects in an Amazon Simple Storage Solution (S3) bucket. -- [azure](storage-drivers/azure): A driver storing objects in [Microsoft Azure Blob Storage](http://azure.microsoft.com/en-us/services/storage/). +- [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/). -Storage Driver API -================== +## 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. @@ -22,23 +25,21 @@ Storage drivers are required to implement the `storagedriver.StorageDriver` inte Storage drivers are intended (but not required) to be written in go, providing compile-time validation of the `storagedriver.StorageDriver` interface, although an IPC driver wrapper means that it is not required for drivers to be included in the compiled registry. The `storagedriver/ipc` package provides a client/server protocol for running storage drivers provided in external executables as a managed child server process. -Driver Selection and Configuration -================================== +## 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 driver is registered with the given name, this factory will attempt to find an executable storage driver with the executable name "registry-storage-\" and return an IPC storage driver wrapper managing the driver subprocess. If no such storage driver can be found, `factory.Create` will return an `InvalidStorageDriverError`. -Driver Contribution -=================== +## Driver Contribution -## Writing new storage drivers +### 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 and as a distributable IPC server executable. -### In-process drivers +#### In-process drivers 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. -### Out-of-process drivers +#### Out-of-process drivers As many users will run the registry as a pre-constructed docker container, storage drivers should also be distributable as IPC server executables. Drivers written in go should model the main method provided in `storagedriver/filesystem/registry-storage-filesystem/filesystem.go`. Parameters to IPC drivers will be provided as a JSON-serialized map in the first argument to the process. These parameters should be validated and then a blocking call to `ipc.StorageDriverServer` should be made with a new storage driver. Out-of-process drivers must also implement the `ipc.IPCStorageDriver` interface, which exposes a `Version` check for the storage driver. This is used to validate storage driver api compatibility at driver load-time.