2016-09-29 21:21:06 +02:00
---
description: Setting-up a local mirror for Docker Hub images
2016-11-10 20:54:25 +01:00
keywords: registry, on-prem, images, tags, repository, distribution, mirror, Hub, recipe, advanced
2016-11-04 23:38:40 +01:00
title: Registry as a pull through cache
2017-06-28 01:33:43 +02:00
redirect_from:
- /engine/admin/registry_mirror/
2016-09-29 21:21:06 +02:00
---
2016-09-28 23:46:28 +02:00
## Use-case
2018-01-26 02:37:23 +01:00
If you have multiple instances of Docker running in your environment, such as
multiple physical or virtual machines all running Docker, each daemon goes out
to the internet and fetches an image it doesn't have locally, from the Docker
repository. You can run a local registry mirror and point all your daemons
there, to avoid this extra internet traffic.
2016-09-28 23:46:28 +02:00
2021-04-20 12:39:12 +02:00
> **Note**
>
2022-01-12 18:38:26 +01:00
> Docker Official Images are an intellectual property of Docker.
2021-04-20 12:39:12 +02:00
2016-09-28 23:46:28 +02:00
### Alternatives
2016-11-04 23:38:40 +01:00
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.
2016-09-28 23:46:28 +02:00
2016-11-04 23:38:40 +01:00
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.
2016-09-28 23:46:28 +02:00
### Gotcha
2016-11-04 23:38:40 +01:00
It's currently not possible to mirror another private registry. Only the central
Hub can be mirrored.
2016-09-28 23:46:28 +02:00
2021-04-20 12:39:12 +02:00
> **Note**
>
2021-06-04 19:45:50 +02:00
> Mirrors of Docker Hub are still subject to Docker's [fair usage policy](https://www.docker.com/pricing/resource-consumption-updates){: target="blank" rel="noopener" class=“”}.
2021-04-20 12:39:12 +02:00
2016-09-28 23:46:28 +02:00
### Solution
2018-01-26 02:37:23 +01:00
The Registry can be configured as a pull through cache. In this mode a Registry
2016-11-04 23:38:40 +01:00
responds to all normal docker pull requests but stores all content locally.
2016-09-28 23:46:28 +02:00
## How does it work?
2016-11-04 23:38:40 +01:00
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.
2016-09-28 23:46:28 +02:00
### What if the content changes on the Hub?
2018-01-26 02:37:23 +01:00
When a pull is attempted with a tag, the Registry checks the remote to
ensure if it has the latest version of the requested content. Otherwise, it
fetches and caches the latest content.
2016-09-28 23:46:28 +02:00
### What about my disk?
2016-11-04 23:38:40 +01:00
In environments with high churn rates, stale data can build up in the cache.
2018-01-26 02:37:23 +01:00
When running as a pull through cache the Registry periodically removes old
content to save disk space. Subsequent requests for removed content causes a
2016-11-04 23:38:40 +01:00
remote fetch and local re-caching.
2016-09-28 23:46:28 +02:00
2016-11-04 23:38:40 +01:00
To ensure best performance and guarantee correctness the Registry cache should
be configured to use the `filesystem` driver for storage.
2016-09-28 23:46:28 +02:00
2017-05-15 19:44:40 +02:00
## Run a Registry as a pull-through cache
2016-09-28 23:46:28 +02:00
2016-11-04 23:38:40 +01:00
The easiest way to run a registry as a pull through cache is to run the official
Registry image.
2018-02-14 09:23:34 +01:00
At least, you need to specify `proxy.remoteurl` within `/etc/docker/registry/config.yml`
as described in the following subsection.
2016-09-28 23:46:28 +02:00
2018-01-26 02:37:23 +01:00
Multiple registry caches can be deployed over the same back-end. A single
registry cache ensures that concurrent requests do not pull duplicate data,
but this property does not hold true for a registry cache cluster.
2016-09-28 23:46:28 +02:00
2021-09-02 23:00:07 +02:00
> **Note**
>
> Service accounts included in the Team plan are limited to 5,000 pulls per day. See [Service Accounts](/docker-hub/service-accounts/) for more details.
2017-05-15 19:44:40 +02:00
### Configure the cache
2016-09-28 23:46:28 +02:00
2016-11-04 23:38:40 +01:00
To configure a Registry to run as a pull through cache, the addition of a
`proxy` section is required to the config file.
2016-09-28 23:46:28 +02:00
2018-01-26 02:37:23 +01:00
To access private images on the Docker Hub, a username and password can
2016-11-04 23:38:40 +01:00
be supplied.
2016-09-28 23:46:28 +02:00
2017-05-15 19:44:40 +02:00
```yaml
proxy:
remoteurl: https://registry-1.docker.io
username: [username]
password: [password]
```
2016-09-28 23:46:28 +02:00
2017-05-15 19:44:40 +02:00
> **Warning**: If you specify a username and password, it's very important to
2018-01-26 02:37:23 +01:00
> understand that private resources that this user has access to Docker Hub is
> made available on your mirror. **You must secure your mirror** by
2017-05-15 19:44:40 +02:00
> implementing authentication if you expect these resources to stay private!
2016-09-28 23:46:28 +02:00
2018-01-26 02:37:23 +01:00
> **Warning**: For the scheduler to clean up old entries, `delete` must
2017-05-15 19:44:40 +02:00
> be enabled in the registry configuration. See
2020-04-08 17:45:34 +02:00
> [Registry Configuration](../configuration.md) for more details.
2016-10-14 23:24:14 +02:00
2017-05-15 19:44:40 +02:00
### Configure the Docker daemon
2016-09-28 23:46:28 +02:00
2017-05-15 19:44:40 +02:00
Either pass the `--registry-mirror` option when starting `dockerd` manually,
2020-04-08 17:45:34 +02:00
or edit [`/etc/docker/daemon.json` ](../../engine/reference/commandline/dockerd.md#daemon-configuration-file )
2017-10-27 21:56:04 +02:00
and add the `registry-mirrors` key and value, to make the change persistent.
2016-09-28 23:46:28 +02:00
2017-05-15 19:44:40 +02:00
```json
{
"registry-mirrors": ["https://< my-docker-mirror-host > "]
}
```
2016-09-28 23:46:28 +02:00
2017-10-27 21:56:04 +02:00
Save the file and reload Docker for the change to take effect.
2017-06-22 22:08:43 +02:00
2017-07-13 22:21:08 +02:00
> Some log messages that appear to be errors are actually informational messages.
>
> Check the `level` field to determine whether
2017-07-13 21:07:43 +02:00
> the message is warning you about an error or is giving you information.
> For example, this log message is informational:
>
> ```conf
2017-10-27 21:56:04 +02:00
> time="2017-06-02T15:47:37Z" level=info msg="error statting local store, serving from upstream: unknown blob" go.version=go1.7.4
2017-07-13 21:07:43 +02:00
> ```
>
> It's telling you that the file doesn't exist yet in the local cache and is
2021-04-20 12:39:12 +02:00
> being pulled from upstream.