Documentation enhancements

Making metadata:
- more consistent
- more specific (fixed copy pasting)
- refine coverage

Insecure information cleanup

Removing no longer used files:
- mkdocs is gone
- the registry diagram is not used, and is a bit silly :)

Minor fixes

Fixing links

Recipes:
- harmonized code sections style to the rest of the docs
- harmonized recipe "style"
- listing new recipes

Enhance deploying

Signed-off-by: Olivier Gambier <olivier@docker.com>
This commit is contained in:
Olivier Gambier 2015-08-26 11:08:13 -07:00
parent 1927c6c0f2
commit 5df53c0681
21 changed files with 214 additions and 236 deletions

View file

@ -28,7 +28,7 @@ HTTP for mirror and HTTPS for v1 & v2
### Registry 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 # For Hosting mode access

View file

@ -1,8 +1,8 @@
<!--[metadata]> <!--[metadata]>
+++ +++
title = "Authenticating proxy with apache" title = "Authenticating proxy with apache"
description = "Restricting access to your registry using a proxy" description = "Restricting access to your registry using an apache proxy"
keywords = ["registry, service, images, repository, authentication"] keywords = ["registry, on-prem, images, tags, repository, distribution, authentication, proxy, apache, httpd, TLS, recipe, advanced"]
+++ +++
<![end-metadata]--> <![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: Verify that the "pull-only" can NOT push:
docker push myregistrydomain.com:5043/test 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

View file

@ -1,10 +1,32 @@
<!--[metadata]> <!--[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]--> <![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`.
OSX 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 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 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) development environment setup. Please follow [How to Write Go Code](https://golang.org/doc/code.html)
@ -12,29 +34,23 @@ for proper setup. If done correctly, you should have a GOROOT and GOPATH set in
environment. environment.
If a Go development environment is setup, one can use `go get` to install the If a Go development environment is setup, one can use `go get` to install the
`registry` command from the current latest: `registry` source code 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`. 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) 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. ... or alternatively `export REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere` if you want to store data into another location.
The `registry` The `registry`
binary can then be run with the following: binary can then be run with the following:
``` $ $GOPATH/bin/registry -version
$ $GOPATH/bin/registry -version $GOPATH/bin/registry github.com/docker/distribution v2.0.0-alpha.1+unknown
$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 > __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 > 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 The registry can be run with the default config using the following
incantation: incantation:
``` $ $GOPATH/bin/registry $GOPATH/src/github.com/docker/distribution/cmd/registry/config-example.yml
$ $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-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] 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] listening on :5000 app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown INFO[0000] debug server listening localhost:5001
INFO[0000] debug server listening localhost:5001
```
If it is working, one should see the above log messages. 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. A `Makefile` has been provided as a convenience to support repeatable builds.
Please install the following into `GOPATH` for it to work: 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. **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 Once these commands are available in the `GOPATH`, run `make` to get a full
build: build:
``` $ GOPATH=`godep path`:$GOPATH make
$ GOPATH=`godep path`:$GOPATH make + clean
+ clean + fmt
+ fmt + vet
+ vet + lint
+ lint + build
+ build github.com/docker/docker/vendor/src/code.google.com/p/go/src/pkg/archive/tar
github.com/docker/docker/vendor/src/code.google.com/p/go/src/pkg/archive/tar github.com/Sirupsen/logrus
github.com/Sirupsen/logrus github.com/docker/libtrust
github.com/docker/libtrust ...
... github.com/yvasiyarov/gorelic
github.com/yvasiyarov/gorelic github.com/docker/distribution/registry/handlers
github.com/docker/distribution/registry/handlers github.com/docker/distribution/cmd/registry
github.com/docker/distribution/cmd/registry + test
+ test ...
... ok github.com/docker/distribution/digest 7.875s
ok github.com/docker/distribution/digest 7.875s ok github.com/docker/distribution/manifest 0.028s
ok github.com/docker/distribution/manifest 0.028s ok github.com/docker/distribution/notifications 17.322s
ok github.com/docker/distribution/notifications 17.322s ? github.com/docker/distribution/registry [no test files]
? github.com/docker/distribution/registry [no test files] ok github.com/docker/distribution/registry/api/v2 0.101s
ok github.com/docker/distribution/registry/api/v2 0.101s ? github.com/docker/distribution/registry/auth [no test files]
? github.com/docker/distribution/registry/auth [no test files] ok github.com/docker/distribution/registry/auth/silly 0.011s
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 + /Users/sday/go/src/github.com/docker/distribution/bin/registry-api-descriptor-template
+ /Users/sday/go/src/github.com/docker/distribution/bin/registry-api-descriptor-template + binaries
+ binaries
```
The above provides a repeatable build using the contents of the vendored The above provides a repeatable build using the contents of the vendored
Godeps directory. This includes formatting, vetting, linting, building, Godeps directory. This includes formatting, vetting, linting, building,
testing and generating tagged binaries. We can verify this worked by running testing and generating tagged binaries. We can verify this worked by running
the registry binary generated in the "./bin" directory: the registry binary generated in the "./bin" directory:
```sh $ ./bin/registry -version
$ ./bin/registry -version ./bin/registry github.com/docker/distribution v2.0.0-alpha.2-80-g16d8b2c.m
./bin/registry github.com/docker/distribution v2.0.0-alpha.2-80-g16d8b2c.m
```
### Developing ### 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 dependencies. The `GOPATH` can be migrated to the current package versions
declared in `Godeps` with the following command: declared in `Godeps` with the following command:
```sh godep restore
godep restore
```
> **WARNING:** This command will checkout versions of the code specified in > **WARNING:** This command will checkout versions of the code specified in
> Godeps/Godeps.json, modifying the contents of `GOPATH`. If this is > 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 With a successful run of the above command, one can now use `make` without
specifying the `GOPATH`: specifying the `GOPATH`:
```sh make
$ make
```
If that is successful, standard `go` commands, such as `go test` should work, If that is successful, standard `go` commands, such as `go test` should work,
per package, without issue. per package, without issue.
@ -151,6 +155,4 @@ the environment variable `DOCKER_BUILDTAGS`.
To enable the [Ceph RADOS storage driver](storage-drivers/rados.md) To enable the [Ceph RADOS storage driver](storage-drivers/rados.md)
(librados-dev and librbd-dev will be required to build the bindings): (librados-dev and librbd-dev will be required to build the bindings):
```sh export DOCKER_BUILDTAGS='include_rados'
export DOCKER_BUILDTAGS='include_rados'
```

View file

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

View file

@ -1,8 +1,8 @@
<!--[metadata]> <!--[metadata]>
+++ +++
title = "Deploying a registry server" title = "Deploying a registry server"
description = "Explains how to deploy a registry server" description = "Explains how to deploy a registry"
keywords = ["registry, service, images, repository"] keywords = ["registry, on-prem, images, tags, repository, distribution, deployment"]
[menu.main] [menu.main]
parent="smn_registry" parent="smn_registry"
weight=3 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. 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: 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: 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 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 provide high availability. While a full load balancing setup is outside the
scope this document, there are a few considerations that can make the process scope of this document, there are a few considerations that can make the process
smoother. smoother.
The most important aspect is that a load balanced cluster of registries must 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 - HTTP Secret
- Redis Cache (if configured) - 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 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 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 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. accessing the same resource, and will likely share an identical configuration.
The _HTTP Secret_ coordinates uploads, so also must be the same across 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 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 Getting the headers correct is very important. For all responses to any
request under the "/v2/" url space, the `Docker-Distribution-API-Version` 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 and fallback to version 1 registries, if necessary. Confirming this is setup
correctly can help avoid problems with fallback. 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 A properly secured registry should return 401 when the "/v2/" endpoint is hit
without credentials. The response should include a `WWW-Authenticate` without credentials. The response should include a `WWW-Authenticate`
challenge, providing guidance on how to authenticate, such as with basic auth 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 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 This will secure your registry by ensuring that configuration problems with
authentication don't accidentally expose an unprotected registry. If you're authentication don't accidentally expose an unprotected registry. If you're
using a less sophisticated load balancer, such as Amazon's Elastic Load 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 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. 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 ## Restricting access
Except for registries running on secure local networks, registries should always implement access restrictions. 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. 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 ### Alternatives
1. You may want to leverage more advanced basic auth implementations through a proxy design, in front of the registry. You will find examples of such patterns in the [recipes list](recipes.md). 1. You may want to leverage more advanced basic auth implementations through a proxy design, in front of the registry. You will find examples of such patterns in the [recipes list](recipes.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). 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 ## Managing with Compose
@ -191,7 +204,6 @@ registry:
environment: environment:
REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt
REGISTRY_HTTP_TLS_KEY: /certs/domain.key REGISTRY_HTTP_TLS_KEY: /certs/domain.key
REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /var/lib/registry
REGISTRY_AUTH: htpasswd REGISTRY_AUTH: htpasswd
REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm 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) - [Advanced "recipes"](recipes.md)
- [Registry API](spec/api.md) - [Registry API](spec/api.md)
- [Storage driver model](storagedrivers.md) - [Storage driver model](storagedrivers.md)
- [Token authentication](spec/auth/token.md)
<!--
- [Glossary](glossary.md)
### Development resources
- [Building the registry](building.md)
- [Architecture notes](architecture.md)
-->

View file

@ -2,7 +2,7 @@
+++ +++
title = "Getting help" title = "Getting help"
description = "Getting help with the Registry" 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] [menu.main]
parent="smn_registry" parent="smn_registry"
weight=9 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

View file

@ -1,8 +1,8 @@
<!--[metadata]> <!--[metadata]>
+++ +++
title = "Docker Registry 2.0" title = "Docker Registry"
description = "Introduces the Docker Registry" description = "High-level overview of the Registry"
keywords = ["registry, images, repository"] keywords = ["registry, on-prem, images, tags, repository, distribution"]
[menu.main] [menu.main]
parent="smn_registry" parent="smn_registry"
+++ +++
@ -32,7 +32,7 @@ Users looking for a commercially supported version of the Registry should look i
## Requirements ## Requirements
The Registry is compatible with Docker engine **version 1.6.0 or higher**. 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 ## TL;DR

View file

@ -1,8 +1,8 @@
<!--[metadata]> <!--[metadata]>
+++ +++
title = "Insecure Registry" title = "Testing an insecure registry"
description = "Deploying an insecure Registry" description = "Deploying a Registry in an insecure fashion"
keywords = ["registry, images, repository"] keywords = ["registry, on-prem, images, tags, repository, distribution, insecure"]
+++ +++
<![end-metadata]--> <![end-metadata]-->
@ -23,16 +23,16 @@ This basically tells Docker to entirely disregard security for your registry.
**Pros:** **Pros:**
- easy to configure - relatively easy to configure
**Cons:** **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 - you have to configure every docker daemon that wants to access your registry
## Using self-signed certificates ## 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: Generate your own certificate:
@ -42,11 +42,11 @@ Generate your own certificate:
Be sure to use the name `myregistrydomain.com` as a CN. 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:** **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; 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 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).

View file

@ -1,8 +1,8 @@
<!--[metadata]> <!--[metadata]>
+++ +++
title = "Understanding the Registry" title = "Understanding the Registry"
description = "Explains what it is, basic use cases and requirements" description = "Explains what the Registry is, basic use cases and requirements"
keywords = ["registry, service, images, repository, understand, use cases, requirements"] keywords = ["registry, on-prem, images, tags, repository, distribution, use cases, requirements"]
[menu.main] [menu.main]
parent="smn_registry" parent="smn_registry"
weight=2 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: 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` * `docker pull myregistrydomain:port/foo/bar` instructs docker to contact the registry located at `myregistrydomain:port` to find the image `foo/bar`
You can find out more about the various Docker commands dealing with images in the [official Docker engine documentation](https://docs.docker.com/reference/commandline/cli/). You can find out more about the various Docker commands dealing with images in the [official Docker engine documentation](https://docs.docker.com/reference/commandline/cli/).

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**' ]

View file

@ -1,8 +1,8 @@
<!--[metadata]> <!--[metadata]>
+++ +++
title = "Authenticating proxy with nginx" title = "Authenticating proxy with nginx"
description = "Restricting access to your registry using a proxy" description = "Restricting access to your registry using a nginx proxy"
keywords = ["registry, service, images, repository, authentication"] keywords = ["registry, on-prem, images, tags, repository, distribution, nginx, proxy, authentication, TLS, recipe, advanced"]
+++ +++
<![end-metadata]--> <![end-metadata]-->
@ -133,24 +133,3 @@ Login with a "push" authorized user (using `testuserpush` and `testpasswordpush`
docker tag ubuntu myregistrydomain.com:5043/test docker tag ubuntu myregistrydomain.com:5043/test
docker push myregistrydomain.com:5043/test docker push myregistrydomain.com:5043/test
docker pull 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

View file

@ -1,8 +1,8 @@
<!--[metadata]> <!--[metadata]>
+++ +++
title = "Work with Notifications" title = "Working with notifications"
description = "Explains work with registry notifications" description = "Explains how to work with registry notifications"
keywords = ["registry, service, images, notifications, repository"] keywords = ["registry, on-prem, images, tags, repository, distribution, notifications, advanced"]
[menu.main] [menu.main]
parent="smn_registry" parent="smn_registry"
weight=5 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 events. The events are queued into a registry-internal broadcast system which
queues and dispatches events to [_Endpoints_](#endpoints). queues and dispatches events to [_Endpoints_](#endpoints).
![](../images/notifications.png) ![](images/notifications.png)
## 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 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 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 uniquify incoming
requests, if required. Along with that, an _action_ is provided with a requests, if required. Along with that, an _action_ is provided with a
_target, identifying the object mutated during the event. _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 > is being deprecated for the `size` field, bringing the target in line with
> common nomenclature. Both will continue to be set for the foreseeable > common nomenclature. Both will continue to be set for the foreseeable
> future. Newer code should favor `size` but accept either. > 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 usually configured to "http://localhost:5001/debug/vars". Information such as
configuration and metrics are available by endpoint. 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: several failures and have since recovered:
```json ```json
@ -318,4 +318,3 @@ is a possibility, although it may have an effect on request service time.
Please see the Please see the
[godoc](http://godoc.org/github.com/docker/distribution/notifications#Sink) [godoc](http://godoc.org/github.com/docker/distribution/notifications#Sink)
for more information. for more information.

View file

@ -1,62 +1,79 @@
<!--[metadata]> <!--[metadata]>
+++ +++
draft = "true" title = "Running on OSX"
description = "Explains how to run a registry on OSX"
keywords = ["registry, on-prem, images, tags, repository, distribution, osx, recipe, advanced"]
+++ +++
<![end-metadata]--> <![end-metadata]-->
# OS X Setup Guide # 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 OSX.
### Alternatives
You can start a VM on OSX, 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 OSX agent.
### Gotchas
Production services operation on OSX 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 ## Checkout the Docker Distribution source tree
``` mkdir -p $GOPATH/src/github.com/docker
mkdir -p $GOPATH/src/github.com/docker git clone https://github.com/docker/distribution.git $GOPATH/src/github.com/docker/distribution
git clone https://github.com/docker/distribution.git $GOPATH/src/github.com/docker/distribution cd $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
GOPATH=$(PWD)/Godeps/_workspace:$GOPATH make binaries sudo cp bin/registry /usr/local/libexec/registry
sudo cp bin/registry /usr/local/libexec/registry
```
## Setup ## Setup
Copy the registry configuration file in place: Copy the registry configuration file in place:
``` mkdir /Users/Shared/Registry
mkdir /Users/Shared/Registry cp docs/osx/config.yml /Users/Shared/Registry/config.yml
cp docs/osx/config.yml /Users/Shared/Registry/config.yml
```
## Running the Docker Registry under launchd ## Running the Docker Registry under launchd
Copy the Docker registry plist into place: Copy the Docker registry plist into place:
``` plutil -lint docs/osx/com.docker.registry.plist
plutil -lint docs/osx/com.docker.registry.plist cp docs/osx/com.docker.registry.plist ~/Library/LaunchAgents/
cp docs/osx/com.docker.registry.plist ~/Library/LaunchAgents/ chmod 644 ~/Library/LaunchAgents/com.docker.registry.plist
chmod 644 ~/Library/LaunchAgents/com.docker.registry.plist
```
Start the Docker registry: 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 ### Restarting the docker registry service
``` launchctl stop com.docker.registry
launchctl stop com.docker.registry launchctl start com.docker.registry
launchctl start com.docker.registry
```
### Unloading the docker registry service ### Unloading the docker registry service
``` launchctl unload ~/Library/LaunchAgents/com.docker.registry.plist
launchctl unload ~/Library/LaunchAgents/com.docker.registry.plist
```

View file

@ -1,8 +1,8 @@
<!--[metadata]> <!--[metadata]>
+++ +++
title = "Recipes for Registry" title = "Recipes"
description = "Fun stuff to do with your registry" 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]--> <![end-metadata]-->
@ -30,3 +30,5 @@ At this point, it's assumed that:
* [using Apache as an authenticating proxy](apache.md) * [using Apache as an authenticating proxy](apache.md)
* [using Nginx as an authenticating proxy](nginx.md) * [using Nginx as an authenticating proxy](nginx.md)
* [running a Registry on OSX](osx-setup-guide.md)
* [hacking the registry: build instructions](building.md)

View file

@ -1,8 +1,8 @@
<!--[metadata]> <!--[metadata]>
+++ +++
title = "Docker Registry HTTP API V2" title = "HTTP API V2"
description = "This is a specification for the API." description = "Specification for the Registry API."
keywords = ["registry, service, driver, images, storage, api"] keywords = ["registry, on-prem, images, tags, repository, distribution, api, advanced"]
[menu.main] [menu.main]
parent="smn_registry_ref" 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 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 architecture that have led to this new version. The main driver of this
specification these changes to the docker the image format, covered in 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, definition and improves security. This specification will build on that work,
leveraging new properties of the manifest format to improve performance, leveraging new properties of the manifest format to improve performance,
reduce bandwidth usage and decrease the likelihood of backend corruption. reduce bandwidth usage and decrease the likelihood of backend corruption.

View file

@ -1,8 +1,8 @@
<!--[metadata]> <!--[metadata]>
+++ +++
title = "Docker Registry HTTP API V2" title = "HTTP API V2"
description = "This is a specification for the API." description = "Specification for the Registry API."
keywords = ["registry, service, driver, images, storage, api"] keywords = ["registry, on-prem, images, tags, repository, distribution, api, advanced"]
[menu.main] [menu.main]
parent="smn_registry_ref" 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 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 architecture that have led to this new version. The main driver of this
specification these changes to the docker the image format, covered in 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, definition and improves security. This specification will build on that work,
leveraging new properties of the manifest format to improve performance, leveraging new properties of the manifest format to improve performance,
reduce bandwidth usage and decrease the likelihood of backend corruption. reduce bandwidth usage and decrease the likelihood of backend corruption.

View file

@ -1,15 +1,13 @@
<!--[metadata]> <!--[metadata]>
+++ +++
title = "Docker Registry v2 Authentication" title = "Token Authentication"
description = "Introduces the Docker Registry v2 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] [menu.main]
parent="smn_registry_ref" parent="smn_registry_ref"
+++ +++
<![end-metadata]--> <![end-metadata]-->
# Docker Registry v2 authentication via central service # Docker Registry v2 authentication via central service
Today a Docker Registry can run in standalone mode in which there are no Today a Docker Registry can run in standalone mode in which there are no

View file

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