Merge pull request #931 from dmp42/5.all-ur-proxy-are-belong-to-us
Documentation fixes
This commit is contained in:
Aaron Lehmann
commit
bc010e506e
22 changed files with 245 additions and 264 deletions
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
... 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
|
||||
```
|
||||
|
||||
> __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
|
||||
$ $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,16 +78,13 @@ 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
|
||||
```
|
||||
|
||||
**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
|
||||
|
|
@ -100,17 +111,14 @@ 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
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
> **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'
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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,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
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
Binary file not shown.
|
Before Width: | Height: | Size: 24 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 20 KiB |
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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/).
|
||||
|
|
|
|||
|
|
@ -1,28 +1,40 @@
|
|||
<!--[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.
|
||||
|
||||
|
|
@ -30,7 +42,7 @@ To ensure best performance and guarantee correctness the Registry cache should b
|
|||
|
||||
## 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]
|
||||
```
|
||||
|
||||
> :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`.
|
||||
|
|
|
|||
|
|
@ -1,18 +0,0 @@
|
|||
- ['registry/index.md', 'Reference', 'Docker Registry 2.0']
|
||||
- ['registry/introduction.md', 'Reference', ' ▪ Introduction' ]
|
||||
- ['registry/deploying.md', 'Reference', ' ▪ Deploy a registry' ]
|
||||
- ['registry/configuration.md', 'Reference', ' ▪ Configure a registry' ]
|
||||
- ['registry/authentication.md', 'Reference', ' ▪ Authentication' ]
|
||||
- ['registry/glossary.md', 'Reference', ' ▪ Glossary' ]
|
||||
- ['registry/help.md', 'Reference', ' ▪ Getting help' ]
|
||||
- ['registry/storagedrivers.md', 'Reference', ' ▪ Storage driver model' ]
|
||||
- ['registry/notifications.md', 'Reference', ' ▪ Work with notifications' ]
|
||||
- ['registry/spec/api.md', 'Reference', ' ▪ 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**' ]
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
||||
## Build the registry binary
|
||||
## Build the binary
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
Start the Docker registry:
|
||||
|
||||
```
|
||||
launchctl load ~/Library/LaunchAgents/com.docker.registry.plist
|
||||
```
|
||||
|
||||
### Restarting the docker registry service
|
||||
|
||||
```
|
||||
launchctl stop com.docker.registry
|
||||
launchctl start com.docker.registry
|
||||
```
|
||||
|
||||
### Unloading the docker registry service
|
||||
|
||||
```
|
||||
launchctl unload ~/Library/LaunchAgents/com.docker.registry.plist
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
Loading…
Reference in a new issue