vbatts/registry
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Converges titles to imperative-form, front-matter based, and sentence-case (#438)

Browse source 
Multiple title fixes, consistency fixes, convergence into metadata-based titles.
This commit is contained in:
John Mulhausen 2016-11-04 15:38:40 -07:00 • committed by GitHub
parent f864c74d0d
commit 908a1f14f5
33 changed files with 193 additions and 288 deletions
Download patch file Download diff file Expand all files Collapse all files

16
docs/recipes/apache.md
View file

@ -1,16 +1,10 @@
---
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
menu:
main:
parent: smn_recipes
title: Authenticating proxy with apache
- registry, on-prem, images, tags, repository, distribution, authentication, proxy, apache, httpd, TLS, recipe, advanced
title: Authenticate proxy with apache
---
# Authenticating proxy with apache
## Use-case
People already relying on an apache proxy to authenticate their users to other services might want to leverage it and have Registry communications tunneled through the same pipeline.
@ -19,7 +13,7 @@ Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO
### Alternatives
If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](../deploying.md#native-basic-auth).
If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](../deploying.md#native-basic-auth).
### Solution
@ -27,7 +21,7 @@ With the method presented here, you implement basic authentication for docker en
While we use a simple htpasswd file as an example, any other apache authentication backend should be fairly easy to implement once you are done with the example.
We also implement push restriction (to a limited user group) for the sake of the example. Again, you should modify this to fit your mileage.
We also implement push restriction (to a limited user group) for the sake of the example. Again, you should modify this to fit your mileage.
### Gotchas
@ -200,7 +194,7 @@ Now, start your stack:
docker-compose up -d
Login with a "push" authorized user (using `testuserpush` and `testpasswordpush`), then tag and push your first image:
Login with a "push" authorized user (using `testuserpush` and `testpasswordpush`), then tag and push your first image:
docker login myregistrydomain.com:5043
docker tag ubuntu myregistrydomain.com:5043/test

6
docs/recipes/index.md
View file

@ -2,15 +2,9 @@
description: Fun stuff to do with your registry
keywords:
- registry, on-prem, images, tags, repository, distribution, recipes, advanced
menu:
main:
parent: smn_recipes
weight: -10
title: Recipes Overview
---
# Recipes
You will find here a list of "recipes", end-to-end scenarios for exotic or otherwise advanced use-cases.
Most users are not expected to have a use for these.

66
docs/recipes/mirror.md
View file

@ -1,59 +1,76 @@
---
description: Setting-up a local mirror for Docker Hub images
keywords:
- registry, on-prem, images, tags, repository, distribution, mirror, Hub, recipe,
advanced
menu:
main:
parent: smn_recipes
title: Mirroring Docker Hub
- registry, on-prem, images, tags, repository, distribution, mirror, Hub, recipe, advanced
title: Registry as a pull through cache
---
# Registry as a pull through cache
## Use-case
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.
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.
### Alternatives
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.
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.
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.
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.
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.
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?
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.
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?
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.
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 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.
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.
### Configuring the cache
To configure a Registry to run as a pull through cache, the addition of a `proxy` section is required to the config file.
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, a 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
@ -66,7 +83,8 @@ In order to access private images on the Docker Hub, a username and password can
### Configuring the Docker daemon
You will need to pass the `--registry-mirror` option to your Docker daemon on startup:
You will need to pass the `--registry-mirror` option to your Docker daemon on
startup:
docker --registry-mirror=https://<my-docker-mirror-host> daemon
@ -74,4 +92,6 @@ 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 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`.
> 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`.

54
docs/recipes/nginx.md
View file

@ -1,42 +1,50 @@
---
description: Restricting access to your registry using a nginx proxy
keywords:
- registry, on-prem, images, tags, repository, distribution, nginx, proxy, authentication,
TLS, recipe, advanced
menu:
main:
parent: smn_recipes
title: Authenticating proxy with nginx
- registry, on-prem, images, tags, repository, distribution, nginx, proxy, authentication, TLS, recipe, advanced
title: Authenticate proxy with nginx
---
# Authenticating proxy with nginx
## Use-case
People already relying on a nginx proxy to authenticate their users to other services might want to leverage it and have Registry communications tunneled through the same pipeline.
People already relying on a nginx proxy to authenticate their users to other
services might want to leverage it and have Registry communications tunneled
through the same pipeline.
Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO mechanism fronting their internal http portal.
Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO
mechanism fronting their internal http portal.
### Alternatives
If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](../deploying.md#native-basic-auth).
If you just want authentication for your registry, and are happy maintaining
users access separately, you should really consider sticking with the native
[basic auth registry feature](../deploying.md#native-basic-auth).
### Solution
With the method presented here, you implement basic authentication for docker engines in a reverse proxy that sits in front of your registry.
With the method presented here, you implement basic authentication for docker
engines in a reverse proxy that sits in front of your registry.
While we use a simple htpasswd file as an example, any other nginx authentication backend should be fairly easy to implement once you are done with the example.
While we use a simple htpasswd file as an example, any other nginx
authentication backend should be fairly easy to implement once you are done with
the example.
We also implement push restriction (to a limited user group) for the sake of the example. Again, you should modify this to fit your mileage.
We also implement push restriction (to a limited user group) for the sake of the
example. Again, you should modify this to fit your mileage.
### Gotchas
While this model gives you the ability to use whatever authentication backend you want through the secondary authentication mechanism implemented inside your proxy, it also requires that you move TLS termination from the Registry to the proxy itself.
While this model gives you the ability to use whatever authentication backend
you want through the secondary authentication mechanism implemented inside your
proxy, it also requires that you move TLS termination from the Registry to the
proxy itself.
Furthermore, introducing an extra http layer in your communication pipeline will make it more complex to deploy, maintain, and debug, and will possibly create issues. Make sure the extra complexity is required.
Furthermore, introducing an extra http layer in your communication pipeline will
make it more complex to deploy, maintain, and debug, and will possibly create
issues. Make sure the extra complexity is required.
For instance, Amazon's Elastic Load Balancer (ELB) in HTTPS mode already sets the following client header:
For instance, Amazon's Elastic Load Balancer (ELB) in HTTPS mode already sets
the following client header:
```
X-Real-IP
@ -44,7 +52,8 @@ X-Forwarded-For
X-Forwarded-Proto
```
So if you have an nginx sitting behind it, should remove these lines from the example config below:
So if you have an nginx sitting behind it, should remove these lines from the
example config below:
```
X-Real-IP $remote_addr; # pass on real client's IP
@ -52,7 +61,9 @@ X-Forwarded-For $proxy_add_x_forwarded_for;
X-Forwarded-Proto $scheme;
```
Otherwise nginx will reset the ELB's values, and the requests will not be routed properly. For more information, see [#970](https://github.com/docker/distribution/issues/970).
Otherwise nginx will reset the ELB's values, and the requests will not be routed
properly. For more information, see
[#970](https://github.com/docker/distribution/issues/970).
## Setting things up
@ -183,7 +194,8 @@ Now, start your stack:
docker-compose up -d
Login with a "push" authorized user (using `testuser` and `testpassword`), then tag and push your first image:
Login with a "push" authorized user (using `testuser` and `testpassword`), then
tag and push your first image:
docker login -u=testuser -p=testpassword -e=root@example.ch myregistrydomain.com:5043
docker tag ubuntu myregistrydomain.com:5043/test

7
docs/recipes/osx-setup-guide.md
View file

@ -2,14 +2,9 @@
description: Explains how to run a registry on macOS
keywords:
- registry, on-prem, images, tags, repository, distribution, macOS, recipe, advanced
menu:
main:
parent: smn_recipes
title: Running on macOS
title: macOS Setup Guide
---
# macOS Setup Guide
## Use-case
This is useful if you intend to run a registry server natively on macOS.