fcrozat/distribution
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
Documentation fixes
This commit is contained in:
Aaron Lehmann 2015-08-28 12:51:27 -07:00
commit bc010e506e
22 changed files with 245 additions and 264 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
contrib/apache/README.MD
View File

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

25
docs/apache.md
View File

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

128
docs/building.md
View File

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

10
docs/configuration.md
View File

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

56
docs/deploying.md
View File

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

2
docs/help.md
View File

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

1
docs/images/registry.gliffy
View File

File diff suppressed because one or more lines are too long

BIN
docs/images/registry.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 24 KiB

1
docs/images/registry.svg
View File

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

Before

Width:  |  Height:  |  Size: 20 KiB

8
docs/index.md
View File

@ -1,8 +1,8 @@
<!--[metadata]>
+++
title = "Docker Registry 2.0"
description = "Introduces the Docker Registry"
keywords = ["registry, images, repository"]
title = "Docker Registry"
description = "High-level overview of the Registry"
keywords = ["registry, on-prem, images, tags, repository, distribution"]
[menu.main]
parent="smn_registry"
+++
@ -32,7 +32,7 @@ Users looking for a commercially supported version of the Registry should look i
## Requirements
The Registry is compatible with Docker engine **version 1.6.0 or higher**.
If you really need to work with older Docker versions, you should look into the [old python registry](https://github.com/docker/docker-registry)
If you really need to work with older Docker versions, you should look into the [old python registry](https://github.com/docker/docker-registry).
## TL;DR

34
docs/insecure.md
View File

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

6
docs/introduction.md
View File

@ -1,8 +1,8 @@
<!--[metadata]>
+++
title = "Understanding the Registry"
description = "Explains what it is, basic use cases and requirements"
keywords = ["registry, service, images, repository, understand, use cases, requirements"]
description = "Explains what the Registry is, basic use cases and requirements"
keywords = ["registry, on-prem, images, tags, repository, distribution, use cases, requirements"]
[menu.main]
parent="smn_registry"
weight=2
@ -31,7 +31,7 @@ Finally, the Registry ships with a robust [notification system](notifications.md
Image names as used in typical docker commands reflect their origin:
* `docker pull ubuntu` instructs docker to pull an image named `ubuntu` from the official Docker Hub. This is simply a shortcut for the longer `docker pull registry-1.docker.io/library/ubuntu` command
* `docker pull ubuntu` instructs docker to pull an image named `ubuntu` from the official Docker Hub. This is simply a shortcut for the longer `docker pull docker.io/library/ubuntu` command
* `docker pull myregistrydomain:port/foo/bar` instructs docker to contact the registry located at `myregistrydomain:port` to find the image `foo/bar`
You can find out more about the various Docker commands dealing with images in the [official Docker engine documentation](https://docs.docker.com/reference/commandline/cli/).

60
docs/mirror.md
View File

@ -1,36 +1,48 @@
<!--[metadata]>
+++
draft = "true"
title = "Mirroring Docker Hub"
description = "Setting-up a local mirror for Docker Hub images"
keywords = ["registry, on-prem, images, tags, repository, distribution, mirror, Hub, recipe, advanced"]
+++
<![end-metadata]-->
# Registry as a pull through cache
A v2 Registry can be configured as a pull through cache. In this mode a Registry responds to all normal docker pull requests but stores all content locally.
## Use-case
NOTE: Currently this feature can only be used to proxy against the official Docker Hub.
If you have multiple instances of Docker running in your environment (e.g., multiple physical or virtual machines, all running the Docker daemon), each time one of them requires an image that it doesn’t have it will go out to the internet and fetch it from the public Docker registry. By running a local registry mirror, you can keep most of the redundant image fetch traffic on your local network.
## Why?
### Alternatives
If you have multiple instances of Docker running in your environment (e.g., multiple physical or virtual machines, all running the Docker daemon), each time one of them requires an image that it doesn’t have it will go out to the internet and fetch it from the public Docker registry. By running a local registry mirror, you can keep most of the image fetch traffic on your local network.
Alternatively, if the set of images you are using is well delimited, you can simply pull them manually and push them to a simple, local, private registry.
Furthermore, if your images are all built in-house, not using the Hub at all and relying entirely on your local registry is the simplest scenario.
### Gotcha
It's currently not possible to mirror another private registry. Only the central Hub can be mirrored.
### Solution
The Registry can be configured as a pull through cache. In this mode a Registry responds to all normal docker pull requests but stores all content locally.
## How does it work?
The first time you request an image from your local registry mirror, it pulls the image from the public Docker registry and stores it locally before handing it back to you. On subsequent requests, the local registry mirror is able to serve the image from its own storage.
## What if the content changes on the Hub?
### What if the content changes on the Hub?
When a pull is attempted with a tag, the Registry will check the remote to ensure if it has the latest version of the requested content. If it doesn't it will fetch the latest content and cache it.
## What about my disk?
### What about my disk?
In environments with high churn rates, stale data can build up in the cache. When running as a pull through cache the Registry will periodically remove old content to save disk space. Subsequent requests for removed content will cause a remote fetch and local re-caching.
In environments with high churn rates, stale data can build up in the cache. When running as a pull through cache the Registry will periodically remove old content to save disk space. Subsequent requests for removed content will cause a remote fetch and local re-caching.
To ensure best performance and guarantee correctness the Registry cache should be configured to use the `filesystem` driver for storage.
## Running a Registry as a pull through cache
The easiest way to run a registry as a pull through cache is to run the official Registry pull through cache official image.
The easiest way to run a registry as a pull through cache is to run the official Registry image.
Multiple registry caches can be deployed over the same back-end. A single registry cache will ensure that concurrent requests do not pull duplicate data, but this property will not hold true for a registry cache cluster.
@ -38,33 +50,23 @@ Multiple registry caches can be deployed over the same back-end. A single regis
To configure a Registry to run as a pull through cache, the addition of a `proxy` section is required to the config file.
In order to access private images on the Docker Hub the username and password can be supplied.
In order to access private images on the Docker Hub, a username and password can be supplied.
```
proxy:
remoteurl: https://registry-1.docker.io
username: [username]
password: [password]
```
proxy:
remoteurl: https://registry-1.docker.io
username: [username]
password: [password]
> :warn: if you specify a username and password, it's very important to understand that private resources that this user has access to on the Hub will be made available on your mirror. It's thus paramount that you secure your mirror by implementing authentication if you expect these resources to stay private!
## Configuring the Docker daemon
### Configuring the Docker daemon
You will need to pass the `--registry-mirror` option to your Docker daemon on startup:
```
docker --registry-mirror=https://<my-docker-mirror-host> -d
```
docker --registry-mirror=https://<my-docker-mirror-host> daemon
For example, if your mirror is serving on http://10.0.0.2:5000, you would run:
```
docker --registry-mirror=https://10.0.0.2:5000 -d
```
NOTE: Depending on your local host setup, you may be able to add the --registry-mirror options to the `DOCKER_OPTS` variable in `/etc/default/` docker.
docker --registry-mirror=https://10.0.0.2:5000 daemon
NOTE: Depending on your local host setup, you may be able to add the `--registry-mirror` option to the `DOCKER_OPTS` variable in `/etc/default/docker`.

18
docs/mkdocs.yml
View File

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

25
docs/nginx.md
View File

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

15
docs/notifications.md
View File

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

79
docs/osx-setup-guide.md
View File

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

7
docs/recipes.md
View File

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

8
docs/spec/api.md
View File

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

8
docs/spec/api.md.tmpl
View File

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

6
docs/spec/auth/token.md
View File

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

10
docs/storagedrivers.md
View File

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