alexvanin/distribution
1
0
Fork 0
forked from TrueCloudLab/distribution
Code Pull requests Activity

Merge pull request #325 from moxiegirl/docs-restructure

Browse source 
Breaking out README
This commit is contained in:
Stephen Day 2015-04-09 18:31:42 -07:00
commit 5dd885b311
25 changed files with 766 additions and 265 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

278
README.md
View file

@ -1,47 +1,37 @@
> **Notice:** *This repository hosts experimental components that are
> currently under heavy and fast-paced development, not-ready for public
> consumption. If you are looking for the stable registry, please head over to
> [docker/docker-registry](https://github.com/docker/docker-registry)
> instead.*
Distribution
============
# Distribution
The Docker toolset to pack, ship, store, and deliver content.
The main product of this repository is the new registry implementation for
storing and distributing docker images. It supersedes the [docker/docker-
This repository's main product is the Docker Registry Service 2.0 implementation
for storing and distributing Docker images. It supersedes the [docker/docker-
registry](https://github.com/docker/docker-registry) project with a new API
design, focused around security and performance.
The _Distribution_ project has the further long term goal of providing a
secure tool chain for distributing content. The specifications, APIs and tools
should be as useful with docker as they are without.
This repository contains the following components:
- **registry (beta):** An implementation of the [Docker Registry HTTP API
V2](doc/spec/api.md) for use with docker 1.5+.
- **libraries (unstable):** A rich set of libraries for interacting with
distribution components. Please see
[godoc](http://godoc.org/github.com/docker/distribution) for details. Note
that the libraries *are not* considered stable.
- **dist (experimental):** An experimental tool to provide distribution
oriented functionality without the docker daemon.
- **specifications**: _Distribution_ related specifications are available in
[doc/spec](doc/spec).
- **documentation:** Documentation is available in [doc](doc/overview.md).
|**Component** |Description |
|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **registry** | An implementation of the [Docker Registry HTTP API V2](docs/spec/api.md) for use with docker 1.5+. |
| **libraries** | A rich set of libraries for interacting with,distribution components. Please see [godoc](http://godoc.org/github.com/docker/distribution) for details. **Note**: These libraries are **unstable**. |
| **dist** | An _experimental_ tool to provide distribution, oriented functionality without the `docker` daemon. |
| **specifications** | _Distribution_ related specifications are available in [docs/spec](docs/spec) |
| **documentation** | Documentation is available in [doc](http://docs.docker.com/distribution). |
### How will this integrate with Docker engine?
### How does this integrate with Docker engine?
This project should provide an implementation to a V2 API for use in the
Docker core project. The API should be embeddable and simplify the process of
securely pulling and pushing content from docker daemons.
This project should provide an implementation to a V2 API for use in the [Docker
core project](https://github.com/docker/docker). The API should be embeddable
and simplify the process of securely pulling and pushing content from `docker`
daemons.
### What are the long term goals of the Distribution project?
Design a professional grade and extensible content distribution system, that
allow users to:
The _Distribution_ project has the further long term goal of providing a
secure tool chain for distributing content. The specifications, APIs and tools
should be as useful with Docker as they are without.
Our goal is to design a professional grade and extensible content distribution
system that allow users to:
* Enjoy an efficient, secured and reliable way to store, manage, package and
exchange content
@ -49,8 +39,7 @@ allow users to:
* Implement their own home made solution through good specs, and solid
extensions mechanism.
Features
--------
## More about Registry 2.0
The new registry implementation provides the following benefits:
@ -62,190 +51,67 @@ The new registry implementation provides the following benefits:
For information on upcoming functionality, please see [ROADMAP.md](ROADMAP.md).
Installation
------------
### Who needs to deploy a registry?
**TODO(stevvooe):** Add the following here:
- docker file
- binary builds for non-docker environment (test installations, etc.)
By default, Docker users pull images from Docker's public registry instance.
[Installing Docker](http://docs.docker.com/installation) gives users this
ability. Users can also push images to a repository on Docker's public registry,
if they have a [Docker Hub](https://hub.docker.com/) account.
Configuration
-------------
For some users and even companies, this default behavior is sufficient. For
others, it is not.
The registry server can be configured with a yaml file. The following is a
simple example that can used for local development:
For example, users with their own software products and may want to maintain an
registry for private, company images. Also, you may wish to deploy your own
image repository for images used to test or in continuous integration. For these
use cases and others, [deploying your own registry instance](docs/deploying.md)
may be the better choice.
```yaml
version: 0.1
loglevel: debug
storage:
filesystem:
rootdirectory: /tmp/registry-dev
http:
addr: localhost:5000
secret: asecretforlocaldevelopment
debug:
addr: localhost:5001
```
## Contribute
The above configures the registry instance to run on port 5000, binding to
"localhost", with the debug server enabled. Registry data will be stored in
"/tmp/registry-dev". Logging will be in "debug" mode, which is the most
verbose.
Please see [CONTRIBUTING.md](CONTRIBUTING.md).
A similar simple configuration is available at [cmd/registry/config.yml],
which is generally useful for local development.
**TODO(stevvooe): Need a "best practice" configuration overview. Perhaps, we
can point to a documentation section.
For full details about configuring a registry server, please see [the
documentation](doc/configuration.md).
### Upgrading
**TODO:** Add a section about upgrading from V1 registry along with link to
migrating in documentation.
Build
-----
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
```
The above will install the source repository into the `GOPATH`. The `registry`
binary can then be run with the following:
```
$ $GOPATH/bin/registry -version
$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
incantantation:
```
$ $GOPATH/bin/registry $GOPATH/src/github.com/docker/distribution/cmd/registry/config.yml
INFO[0000] endpoint local-8082 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] debug server listening localhost:5001
```
If it is working, one should see the above log messages.
### Repeatable Builds
For the full development experience, one should `cd` into
`$GOPATH/src/github.com/docker/distribution`. From there, the regular `go`
commands, such as `go test`, should work per package (please see
[Developing](#developing) if they don't work).
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
```
**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
+ clean
+ fmt
+ vet
+ lint
+ build
github.com/docker/docker/vendor/src/code.google.com/p/go/src/pkg/archive/tar
github.com/Sirupsen/logrus
github.com/docker/libtrust
...
github.com/yvasiyarov/gorelic
github.com/docker/distribution/registry/handlers
github.com/docker/distribution/cmd/registry
+ test
...
ok github.com/docker/distribution/digest 7.875s
ok github.com/docker/distribution/manifest 0.028s
ok github.com/docker/distribution/notifications 17.322s
? github.com/docker/distribution/registry [no test files]
ok github.com/docker/distribution/registry/api/v2 0.101s
? github.com/docker/distribution/registry/auth [no test files]
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-api-descriptor-template
+ /Users/sday/go/src/github.com/docker/distribution/bin/dist
+ 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 github.com/docker/distribution v2.0.0-alpha.2-80-g16d8b2c.m
```
### Developing
The above approaches are helpful for small experimentation. If more complex
tasks are at hand, it is recommended to employ the full power of `godep`.
The Makefile is designed to have its `GOPATH` defined externally. This allows
one to experiment with various development environment setups. This is
primarily useful when testing upstream bugfixes, by modifying local code. This
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
```
> **WARNING:** This command will checkout versions of the code specified in
> Godeps/Godeps.json, modifying the contents of `GOPATH`. If this is
> undesired, it is recommended to create a workspace devoted to work on the
> _Distribution_ project.
With a successful run of the above command, one can now use `make` without
specifying the `GOPATH`:
```sh
$ make
```
If that is successful, standard `go` commands, such as `go test` should work,
per package, without issue.
Support
-------
## Support
If any issues are encountered while using the _Distribution_ project, several
avenues are available for support:
IRC: #docker-distribution on FreeNode
Issue Tracker: github.com/docker/distribution/issues
Google Groups: https://groups.google.com/a/dockerproject.org/forum/#!forum/distribution
Mailing List: docker@dockerproject.org
<table>
<tr>
<th align="left">
IRC
</th>
<td>
#docker-distribution on FreeNode
</td>
</tr>
<tr>
<th align="left">
Issue Tracker
</th>
<td>
github.com/docker/distribution/issues
</td>
</tr>
<tr>
<th align="left">
Google Groups
</th>
<td>
https://groups.google.com/a/dockerproject.org/forum/#!forum/distribution
</td>
</tr>
<tr>
<th align="left">
Mailing List
</th>
<td>
docker@dockerproject.org
</td>
</tr>
</table>
Contribute
----------
Please see [CONTRIBUTING.md](CONTRIBUTING.md).
License
-------
## License
This project is distributed under [Apache License, Version 2.0](LICENSE.md).

11
docs/Dockerfile
View file

@ -7,11 +7,18 @@ 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 git describe --match 'v[0-9]*' --dirty='.m' --always > /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/distribution/
COPY docs/images/* /docs/sources/distribution/images/
COPY docs/spec/* /docs/sources/distribution/spec/
COPY docs/spec/auth/* /docs/sources/distribution/spec/auth/
COPY docs/storage-drivers/* /docs/sources/distribution/storage-drivers/
COPY docs/mkdocs.yml /docs/mkdocs-distribution.yml
# Then build everything together, ready for mkdocs
RUN /docs/build.sh

4
docs/architecture.md
View file

@ -1,9 +1,7 @@
# Architecture
**TODO(stevvooe):** Discuss the architecture of the registry, internally and
externally, in a few different deployment scenarios.
## Design
**TODO(stevvooe):** Discuss the architecture of the registry, internally and externally, in a few different deployment scenarios.
### Eventual Consistency

123
docs/building.md Normal file
View file

@ -0,0 +1,123 @@
page_title: Build the development environment
page_description: Explains how to build the distribution project
page_keywords: registry, service, images, repository
# Build the development 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
```
The above will install the source repository into the `GOPATH`. The `registry`
binary can then be run with the following:
```
$ $GOPATH/bin/registry -version
$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
incantantation:
```
$ $GOPATH/bin/registry $GOPATH/src/github.com/docker/distribution/cmd/registry/config.yml
INFO[0000] endpoint local-8082 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] debug server listening localhost:5001
```
If it is working, one should see the above log messages.
### Repeatable Builds
For the full development experience, one should `cd` into
`$GOPATH/src/github.com/docker/distribution`. From there, the regular `go`
commands, such as `go test`, should work per package (please see
[Developing](#developing) if they don't work).
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
```
**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
+ clean
+ fmt
+ vet
+ lint
+ build
github.com/docker/docker/vendor/src/code.google.com/p/go/src/pkg/archive/tar
github.com/Sirupsen/logrus
github.com/docker/libtrust
...
github.com/yvasiyarov/gorelic
github.com/docker/distribution/registry/handlers
github.com/docker/distribution/cmd/registry
+ test
...
ok github.com/docker/distribution/digest 7.875s
ok github.com/docker/distribution/manifest 0.028s
ok github.com/docker/distribution/notifications 17.322s
? github.com/docker/distribution/registry [no test files]
ok github.com/docker/distribution/registry/api/v2 0.101s
? github.com/docker/distribution/registry/auth [no test files]
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-api-descriptor-template
+ /Users/sday/go/src/github.com/docker/distribution/bin/dist
+ 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 github.com/docker/distribution v2.0.0-alpha.2-80-g16d8b2c.m
```
### Developing
The above approaches are helpful for small experimentation. If more complex
tasks are at hand, it is recommended to employ the full power of `godep`.
The Makefile is designed to have its `GOPATH` defined externally. This allows
one to experiment with various development environment setups. This is
primarily useful when testing upstream bugfixes, by modifying local code. This
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
```
> **WARNING:** This command will checkout versions of the code specified in
> Godeps/Godeps.json, modifying the contents of `GOPATH`. If this is
> undesired, it is recommended to create a workspace devoted to work on the
> _Distribution_ project.
With a successful run of the above command, one can now use `make` without
specifying the `GOPATH`:
```sh
$ make
```
If that is successful, standard `go` commands, such as `go test` should work,
per package, without issue.

41
docs/configuration.md
View file

@ -1,4 +1,41 @@
# Configuration
page_title: Configure a Registry
page_description: Explains how to deploy a registry service
page_keywords: registry, service, images, repository
# Configure a Registry
The registry server can be configured with a YAML file. This section provides a
simple example and a complete reference.
## A simple development configuration
The following is a simple example that can used for local development:
```yaml
version: 0.1
log:
level: debug
storage:
filesystem:
rootdirectory: /tmp/registry-dev
http:
addr: localhost:5000
secret: asecretforlocaldevelopment
debug:
addr: localhost:5001
```
The above configures the registry instance to run on port 5000, binding to
"localhost", with the debug server enabled. Registry data will be stored in
"/tmp/registry-dev". Logging will be in "debug" mode, which is the most
verbose.
A similar simple configuration is available at
[config.yml](https://github.com/docker/distribution/blob/master/cmd/registry/config.yml), which is generally useful for local development.
## Configuration Reference
Below is a comprehensive example of all possible configuration options for the registry. Some options are mutually exclusive, and each section is explained in more detail below, but this is a good starting point from which you may delete the sections you do not need to create your own configuration. A copy of this configuration can be found at config.sample.yml.
@ -242,7 +279,7 @@ Token based authentication allows the authentication system to be decoupled from
- issuer: **Required** - The name of the token issuer. The issuer inserts this into the token so it must match the value configured for the issuer.
- rootcertbundle: **Required** - The absolute path to the root certificate bundle containing the public part of the certificates that will be used to sign authentication tokens.
For more information about Token based authentication configuration, see the [specification.](spec/auth/token.md)
For more information about Token based authentication configuration, see the [specification.]
## middleware

402
docs/deploying.md
View file

@ -1,35 +1,389 @@
# Deploying
page_title: Deploying a registry service
page_description: Explains how to deploy a registry service
page_keywords: registry, service, images, repository
**TODO(stevvooe):** This should discuss various deployment scenarios for
production-ready deployments. These may be backed by ready-made docker images
but this should explain how they were created and what considerations were
present.
# Deploying a registry service
This section explains how to deploy a Docker Registry Service either privately
for your own company or publicly for other users. For example, your company may
require a private registry to support your continuous integration (CI) system as
it builds new releases or test servers. Alternatively, your company may have a
large number of products or services with images you wish to server in a branded
manner.
Docker's public registry maintains a default `registry` image to assist you in the
deployment process. This registry image is sufficient for running local tests
but is insufficient for production. For production you should configure and
build your own custom registry image from the `docker/distribution` code.
# Middleware Configuration
## Simple example with the official image
This section describes how to configure storage middleware in the registry to enable layers to be served via a CDN, thus reducing requests to the storage layer. Currently [Amazon Cloudfront](http://aws.amazon.com/cloudfront/) is supported and must be used in conjunction with the S3 storage driver.
In this section, you create a local registry using Docker's official image. You
push an image to, and then pull the same image from, the registry. This a good
exercise for understanding the basic interactions a client has with a
local registry.
## Cloudfront
1. Install Docker.
## Parameters
2. Run the `hello-world` image from the Docker public registry.
`name`: The name of the storage middleware. Currently `cloudfront` is an accepted value.
$ docker run hello-world
The `run` command automatically pulls the image from Docker's official images.
`disabled`: This can be set to false to easily disable the middleware.
3. Start a registry service on your localhost.
`options` : A set of key/value options to configure the middleware:
$ docker run -p 5000:5000 registry
This starts a registry on your `DOCKER_HOST` running on port `5000`.
3. List your images.
$ docker images
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
registry 2.0 bbf0b6ffe923 3 days ago 545.1 MB
golang 1.4 121a93c90463 5 days ago 514.9 MB
hello-world latest e45a5af57b00 3 months ago 910 B
Your list should include a `hello-world` image from the earlier run.
* `baseurl` : The cloudfront base URL
* `privatekey` : The location of your AWS private key on the filesystem
* `keypairid` : The ID of your Cloudfront keypair.
* `duration` : The duration in minutes for which the URL is valid. Default is 20.
4. Retag the `hello-world` image for your local repoistory.
Note: Cloudfront keys exist separately to other AWS keys. See [here](http://docs.aws.amazon.com/AWSSecurityCredentials/1.0/AboutAWSCredentials.html#KeyPairs) for more information.
$ docker tag hello-world:latest localhost:5000/hello-mine:latest
## Example
The command labels a `hello-world:latest` using a new tag in the
`[REGISTRYHOST/]NAME[:TAG]` format. The `REGISTRYHOST` is this case is
`localhost`. In a Mac OSX environment, you'd substitute `$(boot2docker
ip):5000` for the `localhost`.
5. List your new image.
$ docker images
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
registry 2.0 bbf0b6ffe923 3 days ago 545.1 MB
golang 1.4 121a93c90463 5 days ago 514.9 MB
hello-world latest e45a5af57b00 3 months ago 910 B
localhost:5000/hello-mine latest ef5a5gf57b01 3 months ago 910 B
You should see your new image in your listing.
5. Push this new image to your local registry.
$ docker push localhost:5000/hello-mine:latest
6. Remove all the unused images from your local environment:
$ docker rmi -f $(docker images -q -a )
This command is for illustrative purposes; removing the image forces any `run`
to pull from a registry rather than a local cache. If you run `docker images`
after this you should not see any instance of `hello-world` or `hello-mine` in
your images list.
$ docker images
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
registry 2.0 bbf0b6ffe923 3 days ago 545.1 MB
golang 1.4 121a93c90463 5 days ago 514.9 MB
7. Try running `hello-mine`.
$ docker run hello-mine
Unable to find image 'hello-mine:latest' locally
Pulling repository hello-mine
FATA[0001] Error: image library/hello-mine:latest not found
The `run` command fails because your new image doesn't exist in the Docker public
registry.
8. Now, try running the image but specifying the image's registry:
$ docker run localhost:5000/hello-mine
If you run `docker images` after this you'll fine a `hello-mine` instance.
### Making Docker's official registry image production ready
Docker's official image is for simple tests or debugging. Its configuration is
unsuitable for most production instances. For example, any client with access to
the server's IP can push and pull images to it. See the next section for
information on making this image production ready.
## Understand production deployment
When deploying a registry for a production deployment you should consider these
factors:
<table>
<tr>
<th align="left">
backend storage
</th>
<td>
Where should you store the images?
</td>
</tr>
<tr>
<th align="left">
access and/or authentication
</th>
<td>
Do users should have full or controlled access? This can depend on whether
you are serving images to the public or internally to your company only.
</td>
</tr>
<tr>
<th align="left">
debugging
</th>
<td>
When problems or issues arise, do you have the means of solving them. Logs
are useful as is reporting to see trends.
</td>
</tr>
<tr>
<th align="left">
caching
</th>
<td>
Quickly retrieving images can be crucial if you are relying on images for
tests, builds, or other automated systems.
</td>
</tr>
</table>
You can configure your registry features to adjust for these factors. You do
this by specifying options on the command line or, more typically, by writing a
registry configuration file. The configuration file is in YAML format.
Docker's official repository image it is preconfigured using the following
configuration file:
```yaml
version: 0.1
log:
level: debug
fields:
service: registry
environment: development
storage:
cache:
layerinfo: inmemory
filesystem:
rootdirectory: /tmp/registry-dev
http:
addr: :5000
secret: asecretforlocaldevelopment
debug:
addr: localhost:5001
redis:
addr: localhost:6379
pool:
maxidle: 16
maxactive: 64
idletimeout: 300s
dialtimeout: 10ms
readtimeout: 10ms
writetimeout: 10ms
notifications:
endpoints:
- name: local-8082
url: http://localhost:5003/callback
headers:
Authorization: [Bearer <an example token>]
timeout: 1s
threshold: 10
backoff: 1s
disabled: true
- name: local-8083
url: http://localhost:8083/callback
timeout: 1s
threshold: 10
backoff: 1s
disabled: true
```
This configuration is very basic and you can see it would present some problems
in a production. For example, the `http` section details the configuration for
the HTTP server that hosts the registry. The server is not using even the most
minimal transport layer security (TLS). Let's configure that in the next section.
## Configure TLS on a registry server
In this section, you configure TLS on the server to enable communication through
the `https` protocol. Enabling TLS on the server is the minimum layer of
security recommended for running a registry behind a corporate firewall. The
easiest way to do this is to build your own registry image.
### Download the registry source and generated certificates
1. [Download the registry
source](https://github.com/docker/distribution/releases/tag/v2.0.0).
Alternatively, use the `git clone` command if you are more comfortable with that.
2. Unpack the the downloaded package into a local directory.
The package creates a `distribution` directory.
3. Change to the root of the new `distribution` directory.
$ cd distribution
4. Make a `certs` subdirectory.
$ mkdir certs
5. Use SSL to generate some self-signed certificates.
$ openssl req \
-newkey rsa:2048 -nodes -keyout certs/domain.key \
-x509 -days 365 -out certs/domain.crt
### Add the certificates to the image
In this section, you copy the certifications from your `certs` directory into
your base image.
1. Edit the `Dockerfile` and add a `CERTS_PATH` environment variable.
ENV CERTS_PATH /etc/docker/registry/certs
2. Add a line to make the `CERTS_PATH` in the filesystem.
RUN mkdir -v $CERTS_PATH
3. Add `RUN` instructions to hard link your new certifications into this path:
RUN cp -lv ./certs/domain.crt $CERTS_PATH
RUN cp -lv ./certs/domain.key $CERTS_PATH
This copies your certifications into your container.
4. Save your work.
At this point your Dockerfile should look like the following:
FROM golang:1.4
ENV CONFIG_PATH /etc/docker/registry/config.yml
ENV CERTS_PATH /etc/docker/registry/certs
ENV DISTRIBUTION_DIR /go/src/github.com/docker/distribution
ENV GOPATH $DISTRIBUTION_DIR/Godeps/_workspace:$GOPATH
WORKDIR $DISTRIBUTION_DIR
COPY . $DISTRIBUTION_DIR
RUN make PREFIX=/go clean binaries
RUN mkdir -pv "$(dirname $CONFIG_PATH)"
RUN mkdir -v $CERTS_PATH
RUN cp -lv ./certs/domain.crt $CERTS_PATH
RUN cp -lv ./certs/domain.key $CERTS_PATH
RUN cp -lv ./cmd/registry/config.yml $CONFIG_PATH
5. Before you close the Dockerfile look for an instruction to copy the `config.yml` file.
RUN cp -lv ./cmd/registry/config.yml $CONFIG_PATH
This is the default registry configuration file. You'll need to edit the file
to add TLS.
### Add TLS to the registry configuration
1. Edit the `./cmd/registry/config.yml` file.
$ vi ./cmd/registry/config.yml
2. Locate the `http` block.
http:
addr: :5000
secret: asecretforlocaldevelopment
debug:
addr: localhost:5001
3. Add a `tls` block for the server's self-signed certificates:
http:
addr: :5000
secret: asecretforlocaldevelopment
debug:
addr: localhost:5001
tls:
certificate: /etc/docker/registry/certs/domain.crt
key: /etc/docker/registry/certs/domain.key
You provide the paths to the certificates in the container. If you want
two-way authentication across the layer, you can add an optional `clientcas`
section.
4. Save and close the file.
### Run your new image
1. Build your registry image.
$ docker build -t secure_registry .
2. Run your new image.
$ docker run -p 5000:5000 secure_registry
Watch the messages at startup. You should see that `tls` is running:
ubuntu@ip-172-31-34-181:~/repos/distribution$ docker run -p 5000:5000 secure_registry
time="2015-04-05T23:56:47Z" level=info msg="endpoint local-8082 disabled, skipping" app.id=3dd802ad-3bd4-4413-b56d-90c4acff41c7 environment=development service=registry
time="2015-04-05T23:56:47Z" level=info msg="endpoint local-8083 disabled, skipping" app.id=3dd802ad-3bd4-4413-b56d-90c4acff41c7 environment=development service=registry
time="2015-04-05T23:56:47Z" level=info msg="using inmemory layerinfo cache" app.id=3dd802ad-3bd4-4413-b56d-90c4acff41c7 environment=development service=registry
time="2015-04-05T23:56:47Z" level=info msg="listening on :5000, tls" app.id=3dd802ad-3bd4-4413-b56d-90c4acff41c7 environment=development service=registry
time="2015-04-05T23:56:47Z" level=info msg="debug server listening localhost:5001"
2015/04/05 23:57:23 http: TLS handshake error from 172.17.42.1:52057: remote error: unknown certificate authority
3. Use `curl` to verify that you can connect over `https`.
$ curl https://localhost:5000
## Adding a middleware configuration
This section describes how to configure storage middleware in a registry.
Middleware allows the registry to server layers via a content delivery network
(CDN). This is useful for reducing requests to the storage layer.
Currently, the registry supports [Amazon
Cloudfront](http://aws.amazon.com/cloudfront/). You can only use Cloudfront in
conjunction with the S3 storage driver.
<table>
<tr>
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td><code>name</code></td>
<td>The storage middleware name. Currently <code>cloudfront</code> is an accepted value.</td>
</tr>
<tr>
<td><code>disabled<code></td>
<td>Set to <code>false</code> to easily disable the middleware.</td>
</tr>
<tr>
<td><code>options:</code></td>
<td>
A set of key/value options to configure the middleware.
<ul>
<li><code>baseurl:</code> The Cloudfront base URL.</li>
<li><code>privatekey:</code> The location of your AWS private key on the filesystem. </li>
<li><code>keypairid:</code> The ID of your Cloudfront keypair. </li>
<li><code>duration:</code> The duration in minutes for which the URL is valid. Default is 20. </li>
</ul>
</td>
</tr>
</table>
The following example illustrates these values:
```
middleware:
@ -41,4 +395,14 @@ middleware:
privatekey: /path/to/asecret.pem
keypairid: asecret
duration: 60
```
```
>**Note**: Cloudfront keys exist separately to other AWS keys. See
>[the documentation on AWS credentials](http://docs.aws.amazon.com/AWSSecurityCredentials/1.0/
>AboutAWSCredentials.html#KeyPairs) for more information.
**TODO(stevvooe): Need a "best practice" configuration overview. Perhaps, we can point to a documentation section.

17
docs/distribution.md Normal file
View file

@ -0,0 +1,17 @@
# Project
## Contents
-[Docker Registry Service 2.0](overview.md)
-[Architecture](architecture.md)
-[Build the development environment](building.md)
-[Configure a registry](configuration.md)
-[Deploying a registry service](deploying.md)
-[Microsoft Azure storage driver](storage-drivers/azure.md)
-[Filesystem storage driver](storage-drivers/filesystem.md)
-[In-memory storage driver](storage-drivers/inmemory.md)
-[S3 storage driver](storage-drivers/s3.md)
-[Notifications](notifications.md)
-[Docker Registry HTTP API V2](spec/api.md)
-[Docker Registry v2 authentication via central service](spec/auth/token.md)
-[Docker Distribution JSON Canonicalization](spec/json.md)
-[Docker-Registry Storage Driver](storagedrivers.md)

7
docs/glossary.md
View file

@ -1,10 +1,7 @@
# Glossary
**TODO(stevvooe):** Define and describe distribution related terms. Ideally,
we reference back to the actual documentation and specifications where
appropriate.
**TODO(stevvooe):** The following list is a start but woefully incomplete.
This page contains distribution related terms. For a complete Docker glossary,
see the [glossary in the full documentation set](http://docs.docker.com/reference/glossary/).
<dl>
<dt>Blob</dt>

1
docs/images/notifications.gliffy Normal file
View file

File diff suppressed because one or more lines are too long

BIN
docs/images/notifications.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 37 KiB

1
docs/images/notifications.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 31 KiB

1
docs/images/registry.gliffy Normal file
View file

File diff suppressed because one or more lines are too long

BIN
docs/images/registry.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 24 KiB

1
docs/images/registry.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 20 KiB

0
docs/install.md
View file

24
docs/migration.md Normal file
View file

@ -0,0 +1,24 @@
# Migrating a 1.0 registry to 2.0
TODO: This needs to be revised in light of Olivier's work
A few thoughts here:
There was no "1.0". There was an implementation of the Registry API V1 but only a version 0.9 of the service was released.
The image formats are not compatible in any way. One must convert v1 images to v2 images using a docker client or other tool.
One can migrate images from one version to the other by pulling images from the old registry and pushing them to the v2 registry.
-----
The Docker Registry Service 2.0 is backward compatible with images created by the earlier specification. If you are migrating a private registry to version 2.0, you should use the following process:
1. Configure and test a 2.0 registry image in a sandbox environment.
2. Back up up your production image storage.
Your production image storage should reside on a volume or storage backend.
Make sure you have a backup of its contents.
3. Stop your existing registry service.
4. Restart your registry with your tested 2.0 image.

13
docs/mkdocs.yml
View file

@ -1,6 +1,9 @@
- ['distribution/overview.md', 'User Guide', 'Docker Distribution' ]
- ['distribution/install.md', 'Installation', 'Docker Distribution']
- ['distribution/architecture.md', 'Reference', 'Distribution Architecture']
- ['distribution/overview.md', 'Reference', 'Docker Registry Service 2.0']
- ['distribution/deploying.md', 'Reference', '-- Deploy a registry' ]
- ['distribution/configuration.md', 'Reference', '-- Configure a registry' ]
- ['distribution/storagedrivers.md', 'Reference', '-- Storage driver model' ]
- ['distribution/notifications.md', 'Reference', '-- Work with notifications' ]
- ['distribution/spec/api.md', 'Reference', '-- Registry Service API v2' ]
- ['distribution/spec/json.md', 'Reference', '-- JSON format' ]
- ['distribution/spec/auth/token.md', 'Reference', '-- Authenticate via central service' ]

10
docs/notifications.md
View file

@ -1,6 +1,8 @@
# Notifications
page_title: Work with Notifications
page_description: Explains how to deploy a registry service
page_keywords: registry, service, images, repository
> **TODO:** Link out to the architecture document on notification support.
# Notifications
The Registry supports sending webhook notifications in response to events
happening within the registry. Notifications are sent in response to manifest
@ -8,7 +10,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).
> **TODO:** Insert diagram of event system.
![](/distribution/images/notifications.png)
## Endpoints
@ -63,7 +65,7 @@ _target, identifying the object mutated during the event.
The fields available in an event are described in detail in the
[godoc](http://godoc.org/github.com/docker/distribution/notifications#Event).
> **TODO:** Let's break out the fields here rather than rely on the godoc.
**TODO:** Let's break out the fields here rather than rely on the godoc.
The following is an example of a JSON event, sent in response to the push of a
manifest:

72
docs/overview.md
View file

@ -1,6 +1,70 @@
# Overview
page_title: Docker Registry Service 2.0
page_description: Introduces the docker registry service
page_keywords: registry, service, images, repository
**TODO(stevvooe):** Table of contents.
# Docker Registry Service 2.0
**TODO(stevvooe):** Include a full overview of each component and dispatch the
user to the correct documentation.
The Docker Registry Service stores and distributes Docker images. The majority
of Docker users pull images from Docker's own public registry instance.
Installing Docker gives users this ability. Users with a Docker Hub account can
also push images to this registry.
A subset of Docker users may wish to deploy a Docker Registry Service of their own. For example, users with their own software products and may want to maintain an image store for private, company use. Some companies also maintain a registry instance for release of their software images to the public.
This documentation introduces the registry for users deploying their own instances. You can use this documentation to understand how to configure capabilities into a registry instance or how to write your own custom software to extend the existing service.
## Understanding the registry service
A registry is, at its heart, a collection of repositories. In turn, a repository is collection of images. Users interact with the registry by pushing images to or pulling images from the registry. The Docker Registry Service includes several optional features that you can configure according to your needs.
![](/distribution/images/registry.png)
The architecture supports a configurable storage backend. You can store images on a file system or on a service such as Amazon S3 or Microsoft Azure. The default storage system is the local disk; this is suitable for development or some small deployments.
Securing access to images is a concern for even the simplest deployment. The registry service supports transport layer security (TLS) natively. You must configure it in your instance to make use of it. You can also use a proxy server such as Nginx and basic authentication to extend the security of a deployment.
The registry repository includes reference implementations for additional authentication and authorization support. Only very large or public registry deployments are expected to extend the registry in this way.
Docker Registry Service architecture includes a robust notification system. This system sends webhook notifications in response to registry activity. The registry also includes features for both logging and reporting as well. Reporting is useful for large installations that want to collect metrics. Currently, the feature supports both New Relic and Bugsnag.
## Support
If any issues are encountered while using the _Distribution_ project, several
avenues are available for support:
<table>
<tr>
<th align="left">
IRC
</th>
<td>
#docker-distribution on FreeNode
</td>
</tr>
<tr>
<th align="left">
Issue Tracker
</th>
<td>
github.com/docker/distribution/issues
</td>
</tr>
<tr>
<th align="left">
Google Groups
</th>
<td>
https://groups.google.com/a/dockerproject.org/forum/#!forum/distribution
</td>
</tr>
<tr>
<th align="left">
Mailing List
</th>
<td>
docker@dockerproject.org
</td>
</tr>
</table>

6
docs/spec/json.md
View file

@ -1,10 +1,8 @@
# Docker Distribution JSON Canonicalization
## Introduction
To provide consistent content hashing of JSON objects throughout Docker
Distribution APIs, a canonical JSON format has been defined. Adopting such a
canonicalization also aids in caching JSON responses.
Distribution APIs, the specification defines a canonical JSON format. Adopting
such a canonicalization also aids in caching JSON responses.
## Rules

2
docs/storagedriver/azure.md → docs/storage-drivers/azure.md
View file

@ -1,4 +1,4 @@
# Docker Registry Microsoft Azure Blob 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.

3
docs/storagedriver/filesystem.md → docs/storage-drivers/filesystem.md
View file

@ -1,5 +1,4 @@
Docker-Registry Filesystem Storage Driver
=========================================
# Filesystem storage driver
An implementation of the `storagedriver.StorageDriver` interface which uses the local filesystem.

3
docs/storagedriver/inmemory.md → docs/storage-drivers/inmemory.md
View file

@ -1,5 +1,4 @@
Docker-Registry In-Memory Storage Driver
=========================================
# In-memory storage driver
An implementation of the `storagedriver.StorageDriver` interface which uses local memory for object storage.

3
docs/storagedriver/s3.md → docs/storage-drivers/s3.md
View file

@ -1,5 +1,4 @@
Docker-Registry S3 Storage Driver
=========================================
# S3 storage driver
An implementation of the `storagedriver.StorageDriver` interface which uses Amazon S3 for object storage.

8
docs/storagedrivers.md
View file

@ -8,10 +8,10 @@ Provided Drivers
This storage driver package comes bundled with several drivers:
- [inmemory](storagedriver/inmemory.md): A temporary storage driver using a local inmemory map. This exists solely for reference and testing.
- [filesystem](storagedriver/filesystem.md): A local storage driver configured to use a directory tree in the local filesystem.
- [s3](storagedriver/s3.md): A driver storing objects in an Amazon Simple Storage Solution (S3) bucket.
- [azure](storagedriver/azure.md): A driver storing objects in [Microsoft Azure Blob Storage](http://azure.microsoft.com/en-us/services/storage/).
- [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/).
Storage Driver API
==================