1---
2title: "Configuring a registry"
3description: "Explains how to configure a registry"
4keywords: registry, on-prem, images, tags, repository, distribution, configuration
5---
6
7The Registry configuration is based on a YAML file, detailed below. While it
8comes with sane default values out of the box, you should review it exhaustively
9before moving your systems to production.
10
11## Override specific configuration options
12
13In a typical setup where you run your Registry from the official image, you can
14specify a configuration variable from the environment by passing `-e` arguments
15to your `docker run` stanza or from within a Dockerfile using the `ENV`
16instruction.
17
18To override a configuration option, create an environment variable named
19`REGISTRY_variable` where `variable` is the name of the configuration option
20and the `_` (underscore) represents indention levels. For example, you can
21configure the `rootdirectory` of the `filesystem` storage backend:
22
23```none
24storage:
25 filesystem:
26 rootdirectory: /var/lib/registry
27```
28
29To override this value, set an environment variable like this:
30
31```none
32REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere
33```
34
35This variable overrides the `/var/lib/registry` value to the `/somewhere`
36directory.
37
38> **Note**: Create a base configuration file with environment variables that can
39> be configured to tweak individual values. Overriding configuration sections
40> with environment variables is not recommended.
41
42## Overriding the entire configuration file
43
44If the default configuration is not a sound basis for your usage, or if you are
45having issues overriding keys from the environment, you can specify an alternate
46YAML configuration file by mounting it as a volume in the container.
47
48Typically, create a new configuration file from scratch,named `config.yml`, then
49specify it in the `docker run` command:
50
51```bash
52$ docker run -d -p 5000:5000 --restart=always --name registry \
53 -v `pwd`/config.yml:/etc/docker/registry/config.yml \
54 registry:2
55```
56
57Use this
58[example YAML file](https://github.com/docker/distribution/blob/master/cmd/registry/config-example.yml)
59as a starting point.
60
61## List of configuration options
62
63These are all configuration options for the registry. Some options in the list
64are mutually exclusive. Read the detailed reference information about each
65option before finalizing your configuration.
66
67```none
68version: 0.1
69log:
70 accesslog:
71 disabled: true
72 level: debug
73 formatter: text
74 fields:
75 service: registry
76 environment: staging
77 hooks:
78 - type: mail
79 disabled: true
80 levels:
81 - panic
82 options:
83 smtp:
84 addr: mail.example.com:25
85 username: mailuser
86 password: password
87 insecure: true
88 from: sender@example.com
89 to:
90 - errors@example.com
91loglevel: debug # deprecated: use "log"
92storage:
93 filesystem:
94 rootdirectory: /var/lib/registry
95 maxthreads: 100
96 azure:
97 accountname: accountname
98 accountkey: base64encodedaccountkey
99 container: containername
100 gcs:
101 bucket: bucketname
102 keyfile: /path/to/keyfile
103 credentials:
104 type: service_account
105 project_id: project_id_string
106 private_key_id: private_key_id_string
107 private_key: private_key_string
108 client_email: client@example.com
109 client_id: client_id_string
110 auth_uri: http://example.com/auth_uri
111 token_uri: http://example.com/token_uri
112 auth_provider_x509_cert_url: http://example.com/provider_cert_url
113 client_x509_cert_url: http://example.com/client_cert_url
114 rootdirectory: /gcs/object/name/prefix
115 chunksize: 5242880
116 s3:
117 accesskey: awsaccesskey
118 secretkey: awssecretkey
119 region: us-west-1
120 regionendpoint: http://myobjects.local
121 bucket: bucketname
122 encrypt: true
123 keyid: mykeyid
124 secure: true
125 v4auth: true
126 chunksize: 5242880
127 multipartcopychunksize: 33554432
128 multipartcopymaxconcurrency: 100
129 multipartcopythresholdsize: 33554432
130 rootdirectory: /s3/object/name/prefix
131 swift:
132 username: username
133 password: password
134 authurl: https://storage.myprovider.com/auth/v1.0 or https://storage.myprovider.com/v2.0 or https://storage.myprovider.com/v3/auth
135 tenant: tenantname
136 tenantid: tenantid
137 domain: domain name for Openstack Identity v3 API
138 domainid: domain id for Openstack Identity v3 API
139 insecureskipverify: true
140 region: fr
141 container: containername
142 rootdirectory: /swift/object/name/prefix
143 oss:
144 accesskeyid: accesskeyid
145 accesskeysecret: accesskeysecret
146 region: OSS region name
147 endpoint: optional endpoints
148 internal: optional internal endpoint
149 bucket: OSS bucket
150 encrypt: optional data encryption setting
151 secure: optional ssl setting
152 chunksize: optional size valye
153 rootdirectory: optional root directory
154 inmemory: # This driver takes no parameters
155 delete:
156 enabled: false
157 redirect:
158 disable: false
159 cache:
160 blobdescriptor: redis
161 maintenance:
162 uploadpurging:
163 enabled: true
164 age: 168h
165 interval: 24h
166 dryrun: false
167 readonly:
168 enabled: false
169auth:
170 silly:
171 realm: silly-realm
172 service: silly-service
173 token:
174 autoredirect: true
175 realm: token-realm
176 service: token-service
177 issuer: registry-token-issuer
178 rootcertbundle: /root/certs/bundle
179 htpasswd:
180 realm: basic-realm
181 path: /path/to/htpasswd
182middleware:
183 registry:
184 - name: ARegistryMiddleware
185 options:
186 foo: bar
187 repository:
188 - name: ARepositoryMiddleware
189 options:
190 foo: bar
191 storage:
192 - name: cloudfront
193 options:
194 baseurl: https://my.cloudfronted.domain.com/
195 privatekey: /path/to/pem
196 keypairid: cloudfrontkeypairid
197 duration: 3000s
198 ipfilteredby: awsregion
199 awsregion: us-east-1, use-east-2
200 updatefrenquency: 12h
201 iprangesurl: https://ip-ranges.amazonaws.com/ip-ranges.json
202 storage:
203 - name: redirect
204 options:
205 baseurl: https://example.com/
206reporting:
207 bugsnag:
208 apikey: bugsnagapikey
209 releasestage: bugsnagreleasestage
210 endpoint: bugsnagendpoint
211 newrelic:
212 licensekey: newreliclicensekey
213 name: newrelicname
214 verbose: true
215http:
216 addr: localhost:5000
217 prefix: /my/nested/registry/
218 host: https://myregistryaddress.org:5000
219 secret: asecretforlocaldevelopment
220 relativeurls: false
221 draintimeout: 60s
222 tls:
223 certificate: /path/to/x509/public
224 key: /path/to/x509/private
225 clientcas:
226 - /path/to/ca.pem
227 - /path/to/another/ca.pem
228 letsencrypt:
229 cachefile: /path/to/cache-file
230 email: emailused@letsencrypt.com
231 hosts: [myregistryaddress.org]
232 debug:
233 addr: localhost:5001
234 prometheus:
235 enabled: true
236 path: /metrics
237 headers:
238 X-Content-Type-Options: [nosniff]
239 http2:
240 disabled: false
241notifications:
242 events:
243 includereferences: true
244 endpoints:
245 - name: alistener
246 disabled: false
247 url: https://my.listener.com/event
248 headers: <http.Header>
249 timeout: 1s
250 threshold: 10
251 backoff: 1s
252 ignoredmediatypes:
253 - application/octet-stream
254 ignore:
255 mediatypes:
256 - application/octet-stream
257 actions:
258 - pull
259redis:
260 addr: localhost:6379
261 password: asecret
262 db: 0
263 dialtimeout: 10ms
264 readtimeout: 10ms
265 writetimeout: 10ms
266 pool:
267 maxidle: 16
268 maxactive: 64
269 idletimeout: 300s
270health:
271 storagedriver:
272 enabled: true
273 interval: 10s
274 threshold: 3
275 file:
276 - file: /path/to/checked/file
277 interval: 10s
278 http:
279 - uri: http://server.to.check/must/return/200
280 headers:
281 Authorization: [Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==]
282 statuscode: 200
283 timeout: 3s
284 interval: 10s
285 threshold: 3
286 tcp:
287 - addr: redis-server.domain.com:6379
288 timeout: 3s
289 interval: 10s
290 threshold: 3
291proxy:
292 remoteurl: https://registry-1.docker.io
293 username: [username]
294 password: [password]
295compatibility:
296 schema1:
297 signingkeyfile: /etc/registry/key.json
298 enabled: true
299validation:
300 manifests:
301 urls:
302 allow:
303 - ^https?://([^/]+\.)*example\.com/
304 deny:
305 - ^https?://www\.example\.com/
306```
307
308In some instances a configuration option is **optional** but it contains child
309options marked as **required**. In these cases, you can omit the parent with
310all its children. However, if the parent is included, you must also include all
311the children marked **required**.
312
313## `version`
314
315```none
316version: 0.1
317```
318
319The `version` option is **required**. It specifies the configuration's version.
320It is expected to remain a top-level field, to allow for a consistent version
321check before parsing the remainder of the configuration file.
322
323## `log`
324
325The `log` subsection configures the behavior of the logging system. The logging
326system outputs everything to stdout. You can adjust the granularity and format
327with this configuration section.
328
329```none
330log:
331 accesslog:
332 disabled: true
333 level: debug
334 formatter: text
335 fields:
336 service: registry
337 environment: staging
338```
339
340| Parameter | Required | Description |
341|-------------|----------|-------------|
342| `level` | no | Sets the sensitivity of logging output. Permitted values are `error`, `warn`, `info`, and `debug`. The default is `info`. |
343| `formatter` | no | This selects the format of logging output. The format primarily affects how keyed attributes for a log line are encoded. Options are `text`, `json`, and `logstash`. The default is `text`. |
344| `fields` | no | A map of field names to values. These are added to every log line for the context. This is useful for identifying log messages source after being mixed in other systems. |
345
346### `accesslog`
347
348```none
349accesslog:
350 disabled: true
351```
352
353Within `log`, `accesslog` configures the behavior of the access logging
354system. By default, the access logging system outputs to stdout in
355[Combined Log Format](https://httpd.apache.org/docs/2.4/logs.html#combined).
356Access logging can be disabled by setting the boolean flag `disabled` to `true`.
357
358## `hooks`
359
360```none
361hooks:
362 - type: mail
363 levels:
364 - panic
365 options:
366 smtp:
367 addr: smtp.sendhost.com:25
368 username: sendername
369 password: password
370 insecure: true
371 from: name@sendhost.com
372 to:
373 - name@receivehost.com
374```
375
376The `hooks` subsection configures the logging hooks' behavior. This subsection
377includes a sequence handler which you can use for sending mail, for example.
378Refer to `loglevel` to configure the level of messages printed.
379
380## `loglevel`
381
382> **DEPRECATED:** Please use [log](#log) instead.
383
384```none
385loglevel: debug
386```
387
388Permitted values are `error`, `warn`, `info` and `debug`. The default is
389`info`.
390
391## `storage`
392
393```none
394storage:
395 filesystem:
396 rootdirectory: /var/lib/registry
397 azure:
398 accountname: accountname
399 accountkey: base64encodedaccountkey
400 container: containername
401 gcs:
402 bucket: bucketname
403 keyfile: /path/to/keyfile
404 credentials:
405 type: service_account
406 project_id: project_id_string
407 private_key_id: private_key_id_string
408 private_key: private_key_string
409 client_email: client@example.com
410 client_id: client_id_string
411 auth_uri: http://example.com/auth_uri
412 token_uri: http://example.com/token_uri
413 auth_provider_x509_cert_url: http://example.com/provider_cert_url
414 client_x509_cert_url: http://example.com/client_cert_url
415 rootdirectory: /gcs/object/name/prefix
416 s3:
417 accesskey: awsaccesskey
418 secretkey: awssecretkey
419 region: us-west-1
420 regionendpoint: http://myobjects.local
421 bucket: bucketname
422 encrypt: true
423 keyid: mykeyid
424 secure: true
425 v4auth: true
426 chunksize: 5242880
427 multipartcopychunksize: 33554432
428 multipartcopymaxconcurrency: 100
429 multipartcopythresholdsize: 33554432
430 rootdirectory: /s3/object/name/prefix
431 swift:
432 username: username
433 password: password
434 authurl: https://storage.myprovider.com/auth/v1.0 or https://storage.myprovider.com/v2.0 or https://storage.myprovider.com/v3/auth
435 tenant: tenantname
436 tenantid: tenantid
437 domain: domain name for Openstack Identity v3 API
438 domainid: domain id for Openstack Identity v3 API
439 insecureskipverify: true
440 region: fr
441 container: containername
442 rootdirectory: /swift/object/name/prefix
443 oss:
444 accesskeyid: accesskeyid
445 accesskeysecret: accesskeysecret
446 region: OSS region name
447 endpoint: optional endpoints
448 internal: optional internal endpoint
449 bucket: OSS bucket
450 encrypt: optional data encryption setting
451 secure: optional ssl setting
452 chunksize: optional size valye
453 rootdirectory: optional root directory
454 inmemory:
455 delete:
456 enabled: false
457 cache:
458 blobdescriptor: inmemory
459 maintenance:
460 uploadpurging:
461 enabled: true
462 age: 168h
463 interval: 24h
464 dryrun: false
465 readonly:
466 enabled: false
467 redirect:
468 disable: false
469```
470
471The `storage` option is **required** and defines which storage backend is in
472use. You must configure exactly one backend. If you configure more, the registry
473returns an error. You can choose any of these backend storage drivers:
474
475| Storage driver | Description |
476|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
477| `filesystem` | Uses the local disk to store registry files. It is ideal for development and may be appropriate for some small-scale production applications. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/filesystem.md). |
478| `azure` | Uses Microsoft Azure Blob Storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/azure.md). |
479| `gcs` | Uses Google Cloud Storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/gcs.md). |
480| `s3` | Uses Amazon Simple Storage Service (S3) and compatible Storage Services. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/s3.md). |
481| `swift` | Uses Openstack Swift object storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/swift.md). |
482| `oss` | Uses Aliyun OSS for object storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/oss.md). |
483
484For testing only, you can use the [`inmemory` storage
485driver](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/inmemory.md).
486If you would like to run a registry from volatile memory, use the
487[`filesystem` driver](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/filesystem.md)
488on a ramdisk.
489
490If you are deploying a registry on Windows, a Windows volume mounted from the
491host is not recommended. Instead, you can use a S3 or Azure backing
492data-store. If you do use a Windows volume, the length of the `PATH` to
493the mount point must be within the `MAX_PATH` limits (typically 255 characters),
494or this error will occur:
495
496```none
497mkdir /XXX protocol error and your registry will not function properly.
498```
499
500### `maintenance`
501
502Currently, upload purging and read-only mode are the only `maintenance`
503functions available.
504
505### `uploadpurging`
506
507Upload purging is a background process that periodically removes orphaned files
508from the upload directories of the registry. Upload purging is enabled by
509default. To configure upload directory purging, the following parameters must
510be set.
511
512
513| Parameter | Required | Description |
514|------------|----------|----------------------------------------------------------------------------------------------------|
515| `enabled` | yes | Set to `true` to enable upload purging. Defaults to `true`. |
516| `age` | yes | Upload directories which are older than this age will be deleted.Defaults to `168h` (1 week). |
517| `interval` | yes | The interval between upload directory purging. Defaults to `24h`. |
518| `dryrun` | yes | Set `dryrun` to `true` to obtain a summary of what directories will be deleted. Defaults to `false`.|
519
520> **Note**: `age` and `interval` are strings containing a number with optional
521fraction and a unit suffix. Some examples: `45m`, `2h10m`, `168h`.
522
523### `readonly`
524
525If the `readonly` section under `maintenance` has `enabled` set to `true`,
526clients will not be allowed to write to the registry. This mode is useful to
527temporarily prevent writes to the backend storage so a garbage collection pass
528can be run. Before running garbage collection, the registry should be
529restarted with readonly's `enabled` set to true. After the garbage collection
530pass finishes, the registry may be restarted again, this time with `readonly`
531removed from the configuration (or set to false).
532
533### `delete`
534
535Use the `delete` structure to enable the deletion of image blobs and manifests
536by digest. It defaults to false, but it can be enabled by writing the following
537on the configuration file:
538
539```none
540delete:
541 enabled: true
542```
543
544### `cache`
545
546Use the `cache` structure to enable caching of data accessed in the storage
547backend. Currently, the only available cache provides fast access to layer
548metadata, which uses the `blobdescriptor` field if configured.
549
550You can set `blobdescriptor` field to `redis` or `inmemory`. If set to `redis`,a
551Redis pool caches layer metadata. If set to `inmemory`, an in-memory map caches
552layer metadata.
553
554> **NOTE**: Formerly, `blobdescriptor` was known as `layerinfo`. While these
555> are equivalent, `layerinfo` has been deprecated.
556
557### `redirect`
558
559The `redirect` subsection provides configuration for managing redirects from
560content backends. For backends that support it, redirecting is enabled by
561default. In certain deployment scenarios, you may decide to route all data
562through the Registry, rather than redirecting to the backend. This may be more
563efficient when using a backend that is not co-located or when a registry
564instance is aggressively caching.
565
566To disable redirects, add a single flag `disable`, set to `true`
567under the `redirect` section:
568
569```none
570redirect:
571 disable: true
572```
573
574## `auth`
575
576```none
577auth:
578 silly:
579 realm: silly-realm
580 service: silly-service
581 token:
582 realm: token-realm
583 service: token-service
584 issuer: registry-token-issuer
585 rootcertbundle: /root/certs/bundle
586 htpasswd:
587 realm: basic-realm
588 path: /path/to/htpasswd
589```
590
591The `auth` option is **optional**. Possible auth providers include:
592
593- [`silly`](#silly)
594- [`token`](#token)
595- [`htpasswd`](#htpasswd)
596- [`none`]
597
598You can configure only one authentication provider.
599
600### `silly`
601
602The `silly` authentication provider is only appropriate for development. It simply checks
603for the existence of the `Authorization` header in the HTTP request. It does not
604check the header's value. If the header does not exist, the `silly` auth
605responds with a challenge response, echoing back the realm, service, and scope
606for which access was denied.
607
608The following values are used to configure the response:
609
610| Parameter | Required | Description |
611|-----------|----------|-------------------------------------------------------|
612| `realm` | yes | The realm in which the registry server authenticates. |
613| `service` | yes | The service being authenticated. |
614
615### `token`
616
617Token-based authentication allows you to decouple the authentication system from
618the registry. It is an established authentication paradigm with a high degree of
619security.
620
621| Parameter | Required | Description |
622|-----------|----------|-------------------------------------------------------|
623| `realm` | yes | The realm in which the registry server authenticates. |
624| `service` | yes | The service being authenticated. |
625| `issuer` | yes | The name of the token issuer. The issuer inserts this into the token so it must match the value configured for the issuer. |
626| `rootcertbundle` | yes | The absolute path to the root certificate bundle. This bundle contains the public part of the certificates used to sign authentication tokens. |
627| `autoredirect` | no | When set to `true`, `realm` will automatically be set using the Host header of the request as the domain and a path of `/auth/token/`|
628
629
630For more information about Token based authentication configuration, see the
631[specification](spec/auth/token.md).
632
633### `htpasswd`
634
635The _htpasswd_ authentication backed allows you to configure basic
636authentication using an
637[Apache htpasswd file](https://httpd.apache.org/docs/2.4/programs/htpasswd.html).
638The only supported password format is
639[`bcrypt`](http://en.wikipedia.org/wiki/Bcrypt). Entries with other hash types
640are ignored. The `htpasswd` file is loaded once, at startup. If the file is
641invalid, the registry will display an error and will not start.
642
643> **Warning**: If the `htpasswd` file is missing, the file will be created and provisioned with a default user and automatically generated password.
644> The password will be printed to stdout.
645
646> **Warning**: Only use the `htpasswd` authentication scheme with TLS
647> configured, since basic authentication sends passwords as part of the HTTP
648> header.
649
650| Parameter | Required | Description |
651|-----------|----------|-------------------------------------------------------|
652| `realm` | yes | The realm in which the registry server authenticates. |
653| `path` | yes | The path to the `htpasswd` file to load at startup. |
654
655## `middleware`
656
657The `middleware` structure is **optional**. Use this option to inject middleware at
658named hook points. Each middleware must implement the same interface as the
659object it is wrapping. For instance, a registry middleware must implement the
660`distribution.Namespace` interface, while a repository middleware must implement
661`distribution.Repository`, and a storage middleware must implement
662`driver.StorageDriver`.
663
664This is an example configuration of the `cloudfront` middleware, a storage
665middleware:
666
667```none
668middleware:
669 registry:
670 - name: ARegistryMiddleware
671 options:
672 foo: bar
673 repository:
674 - name: ARepositoryMiddleware
675 options:
676 foo: bar
677 storage:
678 - name: cloudfront
679 options:
680 baseurl: https://my.cloudfronted.domain.com/
681 privatekey: /path/to/pem
682 keypairid: cloudfrontkeypairid
683 duration: 3000s
684 ipfilteredby: awsregion
685 awsregion: us-east-1, use-east-2
686 updatefrenquency: 12h
687 iprangesurl: https://ip-ranges.amazonaws.com/ip-ranges.json
688```
689
690Each middleware entry has `name` and `options` entries. The `name` must
691correspond to the name under which the middleware registers itself. The
692`options` field is a map that details custom configuration required to
693initialize the middleware. It is treated as a `map[string]interface{}`. As such,
694it supports any interesting structures desired, leaving it up to the middleware
695initialization function to best determine how to handle the specific
696interpretation of the options.
697
698### `cloudfront`
699
700
701| Parameter | Required | Description |
702|-----------|----------|-------------------------------------------------------|
703| `baseurl` | yes | The `SCHEME://HOST[/PATH]` at which Cloudfront is served. |
704| `privatekey` | yes | The private key for Cloudfront, provided by AWS. |
705| `keypairid` | yes | The key pair ID provided by AWS. |
706| `duration` | no | An integer and unit for the duration of the Cloudfront session. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, or `h`. For example, `3000s` is valid, but `3000 s` is not. If you do not specify a `duration` or you specify an integer without a time unit, the duration defaults to `20m` (20 minutes). |
707| `ipfilteredby` | no | A string with the following value `none`, `aws` or `awsregion`. |
708| `awsregion` | no | A comma separated string of AWS regions, only available when `ipfilteredby` is `awsregion`. For example, `us-east-1, us-west-2` |
709| `updatefrenquency` | no | The frequency to update AWS IP regions, default: `12h` |
710| `iprangesurl` | no | The URL contains the AWS IP ranges information, default: `https://ip-ranges.amazonaws.com/ip-ranges.json` |
711
712
713Value of `ipfilteredby` can be:
714
715| Value | Description |
716|-------------|------------------------------------|
717| `none` | default, do not filter by IP |
718| `aws` | IP from AWS goes to S3 directly |
719| `awsregion` | IP from certain AWS regions goes to S3 directly, use together with `awsregion`. |
720
721### `redirect`
722
723You can use the `redirect` storage middleware to specify a custom URL to a
724location of a proxy for the layer stored by the S3 storage driver.
725
726| Parameter | Required | Description |
727|-----------|----------|-------------------------------------------------------------------------------------------------------------|
728| `baseurl` | yes | `SCHEME://HOST` at which layers are served. Can also contain port. For example, `https://example.com:5443`. |
729
730## `reporting`
731
732```
733reporting:
734 bugsnag:
735 apikey: bugsnagapikey
736 releasestage: bugsnagreleasestage
737 endpoint: bugsnagendpoint
738 newrelic:
739 licensekey: newreliclicensekey
740 name: newrelicname
741 verbose: true
742```
743
744The `reporting` option is **optional** and configures error and metrics
745reporting tools. At the moment only two services are supported:
746
747- [Bugsnag](#bugsnag)
748- [New Relic](#new-relic)
749
750A valid configuration may contain both.
751
752### `bugsnag`
753
754| Parameter | Required | Description |
755|-----------|----------|-------------------------------------------------------|
756| `apikey` | yes | The API Key provided by Bugsnag. |
757| `releasestage` | no | Tracks where the registry is deployed, using a string like `production`, `staging`, or `development`.|
758| `endpoint`| no | The enterprise Bugsnag endpoint. |
759
760### `newrelic`
761
762| Parameter | Required | Description |
763|-----------|----------|-------------------------------------------------------|
764| `licensekey` | yes | License key provided by New Relic. |
765| `name` | no | New Relic application name. |
766| `verbose`| no | Set to `true` to enable New Relic debugging output on `stdout`. |
767
768## `http`
769
770```none
771http:
772 addr: localhost:5000
773 net: tcp
774 prefix: /my/nested/registry/
775 host: https://myregistryaddress.org:5000
776 secret: asecretforlocaldevelopment
777 relativeurls: false
778 draintimeout: 60s
779 tls:
780 certificate: /path/to/x509/public
781 key: /path/to/x509/private
782 clientcas:
783 - /path/to/ca.pem
784 - /path/to/another/ca.pem
785 minimumtls: tls1.2
786 ciphersuites:
787 - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
788 - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
789 letsencrypt:
790 cachefile: /path/to/cache-file
791 email: emailused@letsencrypt.com
792 hosts: [myregistryaddress.org]
793 debug:
794 addr: localhost:5001
795 headers:
796 X-Content-Type-Options: [nosniff]
797 http2:
798 disabled: false
799```
800
801The `http` option details the configuration for the HTTP server that hosts the
802registry.
803
804| Parameter | Required | Description |
805|-----------|----------|-------------------------------------------------------|
806| `addr` | yes | The address for which the server should accept connections. The form depends on a network type (see the `net` option). Use `HOST:PORT` for TCP and `FILE` for a UNIX socket. |
807| `net` | no | The network used to create a listening socket. Known networks are `unix` and `tcp`. |
808| `prefix` | no | If the server does not run at the root path, set this to the value of the prefix. The root path is the section before `v2`. It requires both preceding and trailing slashes, such as in the example `/path/`. |
809| `host` | no | A fully-qualified URL for an externally-reachable address for the registry. If present, it is used when creating generated URLs. Otherwise, these URLs are derived from client requests. |
810| `secret` | no | A random piece of data used to sign state that may be stored with the client to protect against tampering. For production environments you should generate a random piece of data using a cryptographically secure random generator. If you omit the secret, the registry will automatically generate a secret when it starts. **If you are building a cluster of registries behind a load balancer, you MUST ensure the secret is the same for all registries.**|
811| `relativeurls`| no | If `true`, the registry returns relative URLs in Location headers. The client is responsible for resolving the correct URL. **This option is not compatible with Docker 1.7 and earlier.**|
812| `draintimeout`| no | Amount of time to wait for HTTP connections to drain before shutting down after registry receives SIGTERM signal|
813
814
815### `tls`
816
817The `tls` structure within `http` is **optional**. Use this to configure TLS
818for the server. If you already have a web server running on
819the same host as the registry, you may prefer to configure TLS on that web server
820and proxy connections to the registry server.
821
822| Parameter | Required | Description |
823|-----------|----------|-------------------------------------------------------|
824| `certificate` | yes | Absolute path to the x509 certificate file. |
825| `key` | yes | Absolute path to the x509 private key file. |
826| `clientcas` | no | An array of absolute paths to x509 CA files. |
827| `minimumtls` | no | Minimum TLS version allowed (tls1.0, tls1.1, tls1.2, tls1.3). Defaults to tls1.2 |
828| `ciphersuites` | no | Cipher suites allowed. Please see below for allowed values and default. |
829
830Available cipher suites:
831- TLS_RSA_WITH_RC4_128_SHA
832- TLS_RSA_WITH_3DES_EDE_CBC_SHA
833- TLS_RSA_WITH_AES_128_CBC_SHA
834- TLS_RSA_WITH_AES_256_CBC_SHA
835- TLS_RSA_WITH_AES_128_CBC_SHA256
836- TLS_RSA_WITH_AES_128_GCM_SHA256
837- TLS_RSA_WITH_AES_256_GCM_SHA384
838- TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
839- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
840- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
841- TLS_ECDHE_RSA_WITH_RC4_128_SHA
842- TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
843- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
844- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
845- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
846- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
847- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
848- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
849- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
850- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
851- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
852- TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
853- TLS_AES_128_GCM_SHA256
854- TLS_AES_256_GCM_SHA384
855- TLS_CHACHA20_POLY1305_SHA256
856
857Default cipher suites:
858- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
859- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
860- TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
861- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
862- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
863- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
864- TLS_AES_128_GCM_SHA256
865- TLS_CHACHA20_POLY1305_SHA256
866- TLS_AES_256_GCM_SHA384
867
868### `letsencrypt`
869
870The `letsencrypt` structure within `tls` is **optional**. Use this to configure
871TLS certificates provided by
872[Let's Encrypt](https://letsencrypt.org/how-it-works/).
873
874>**NOTE**: When using Let's Encrypt, ensure that the outward-facing address is
875> accessible on port `443`. The registry defaults to listening on port `5000`.
876> If you run the registry as a container, consider adding the flag `-p 443:5000`
877> to the `docker run` command or using a similar setting in a cloud
878> configuration. You should also set the `hosts` option to the list of hostnames
879> that are valid for this registry to avoid trying to get certificates for random
880> hostnames due to malicious clients connecting with bogus SNI hostnames.
881
882| Parameter | Required | Description |
883|-----------|----------|-------------------------------------------------------|
884| `cachefile` | yes | Absolute path to a file where the Let's Encrypt agent can cache data. |
885| `email` | yes | The email address used to register with Let's Encrypt. |
886| `hosts` | no | The hostnames allowed for Let's Encrypt certificates. |
887
888### `debug`
889
890The `debug` option is **optional** . Use it to configure a debug server that
891can be helpful in diagnosing problems. The debug endpoint can be used for
892monitoring registry metrics and health, as well as profiling. Sensitive
893information may be available via the debug endpoint. Please be certain that
894access to the debug endpoint is locked down in a production environment.
895
896The `debug` section takes a single required `addr` parameter, which specifies
897the `HOST:PORT` on which the debug server should accept connections.
898
899## `prometheus`
900
901The `prometheus` option defines whether the prometheus metrics is enable, as well
902as the path to access the metrics.
903
904| Parameter | Required | Description |
905|-----------|----------|-------------------------------------------------------|
906| `enabled` | no | Set `true` to enable the prometheus server |
907| `path` | no | The path to access the metrics, `/metrics` by default |
908
909The url to access the metrics is `HOST:PORT/path`, where `HOST:PORT` is defined
910in `addr` under `debug`.
911
912### `headers`
913
914The `headers` option is **optional** . Use it to specify headers that the HTTP
915server should include in responses. This can be used for security headers such
916as `Strict-Transport-Security`.
917
918The `headers` option should contain an option for each header to include, where
919the parameter name is the header's name, and the parameter value a list of the
920header's payload values.
921
922Including `X-Content-Type-Options: [nosniff]` is recommended, so that browsers
923will not interpret content as HTML if they are directed to load a page from the
924registry. This header is included in the example configuration file.
925
926### `http2`
927
928The `http2` structure within `http` is **optional**. Use this to control http2
929settings for the registry.
930
931| Parameter | Required | Description |
932|-----------|----------|-------------------------------------------------------|
933| `disabled` | no | If `true`, then `http2` support is disabled. |
934
935## `notifications`
936
937```none
938notifications:
939 events:
940 includereferences: true
941 endpoints:
942 - name: alistener
943 disabled: false
944 url: https://my.listener.com/event
945 headers: <http.Header>
946 timeout: 1s
947 threshold: 10
948 backoff: 1s
949 ignoredmediatypes:
950 - application/octet-stream
951 ignore:
952 mediatypes:
953 - application/octet-stream
954 actions:
955 - pull
956```
957
958The notifications option is **optional** and currently may contain a single
959option, `endpoints`.
960
961### `endpoints`
962
963The `endpoints` structure contains a list of named services (URLs) that can
964accept event notifications.
965
966| Parameter | Required | Description |
967|-----------|----------|-------------------------------------------------------|
968| `name` | yes | A human-readable name for the service. |
969| `disabled` | no | If `true`, notifications are disabled for the service.|
970| `url` | yes | The URL to which events should be published. |
971| `headers` | yes | A list of static headers to add to each request. Each header's name is a key beneath `headers`, and each value is a list of payloads for that header name. Values must always be lists. |
972| `timeout` | yes | A value for the HTTP timeout. A positive integer and an optional suffix indicating the unit of time, which may be `ns`, `us`, `ms`, `s`, `m`, or `h`. If you omit the unit of time, `ns` is used. |
973| `threshold` | yes | An integer specifying how long to wait before backing off a failure. |
974| `backoff` | yes | How long the system backs off before retrying after a failure. A positive integer and an optional suffix indicating the unit of time, which may be `ns`, `us`, `ms`, `s`, `m`, or `h`. If you omit the unit of time, `ns` is used. |
975| `ignoredmediatypes`|no| A list of target media types to ignore. Events with these target media types are not published to the endpoint. |
976| `ignore` |no| Events with these mediatypes or actions are not published to the endpoint. |
977
978#### `ignore`
979| Parameter | Required | Description |
980|-----------|----------|-------------------------------------------------------|
981| `mediatypes`|no| A list of target media types to ignore. Events with these target media types are not published to the endpoint. |
982| `actions` |no| A list of actions to ignore. Events with these actions are not published to the endpoint. |
983
984### `events`
985
986The `events` structure configures the information provided in event notifications.
987
988| Parameter | Required | Description |
989|-----------|----------|-------------------------------------------------------|
990| `includereferences` | no | If `true`, include reference information in manifest events. |
991
992## `redis`
993
994```none
995redis:
996 addr: localhost:6379
997 password: asecret
998 db: 0
999 dialtimeout: 10ms
1000 readtimeout: 10ms
1001 writetimeout: 10ms
1002 pool:
1003 maxidle: 16
1004 maxactive: 64
1005 idletimeout: 300s
1006```
1007
1008Declare parameters for constructing the `redis` connections. Registry instances
1009may use the Redis instance for several applications. Currently, it caches
1010information about immutable blobs. Most of the `redis` options control
1011how the registry connects to the `redis` instance. You can control the pool's
1012behavior with the [pool](#pool) subsection.
1013
1014You should configure Redis with the **allkeys-lru** eviction policy, because the
1015registry does not set an expiration value on keys.
1016
1017| Parameter | Required | Description |
1018|-----------|----------|-------------------------------------------------------|
1019| `addr` | yes | The address (host and port) of the Redis instance. |
1020| `password`| no | A password used to authenticate to the Redis instance.|
1021| `db` | no | The name of the database to use for each connection. |
1022| `dialtimeout` | no | The timeout for connecting to the Redis instance. |
1023| `readtimeout` | no | The timeout for reading from the Redis instance. |
1024| `writetimeout` | no | The timeout for writing to the Redis instance. |
1025
1026### `pool`
1027
1028```none
1029pool:
1030 maxidle: 16
1031 maxactive: 64
1032 idletimeout: 300s
1033```
1034
1035Use these settings to configure the behavior of the Redis connection pool.
1036
1037| Parameter | Required | Description |
1038|-----------|----------|-------------------------------------------------------|
1039| `maxidle` | no | The maximum number of idle connections in the pool. |
1040| `maxactive`| no | The maximum number of connections which can be open before blocking a connection request. |
1041| `idletimeout`| no | How long to wait before closing inactive connections. |
1042
1043## `health`
1044
1045```none
1046health:
1047 storagedriver:
1048 enabled: true
1049 interval: 10s
1050 threshold: 3
1051 file:
1052 - file: /path/to/checked/file
1053 interval: 10s
1054 http:
1055 - uri: http://server.to.check/must/return/200
1056 headers:
1057 Authorization: [Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==]
1058 statuscode: 200
1059 timeout: 3s
1060 interval: 10s
1061 threshold: 3
1062 tcp:
1063 - addr: redis-server.domain.com:6379
1064 timeout: 3s
1065 interval: 10s
1066 threshold: 3
1067```
1068
1069The health option is **optional**, and contains preferences for a periodic
1070health check on the storage driver's backend storage, as well as optional
1071periodic checks on local files, HTTP URIs, and/or TCP servers. The results of
1072the health checks are available at the `/debug/health` endpoint on the debug
1073HTTP server if the debug HTTP server is enabled (see http section).
1074
1075### `storagedriver`
1076
1077The `storagedriver` structure contains options for a health check on the
1078configured storage driver's backend storage. The health check is only active
1079when `enabled` is set to `true`.
1080
1081| Parameter | Required | Description |
1082|-----------|----------|-------------------------------------------------------|
1083| `enabled` | yes | Set to `true` to enable storage driver health checks or `false` to disable them. |
1084| `interval`| no | How long to wait between repetitions of the storage driver health check. A positive integer and an optional suffix indicating the unit of time. The suffix is one of `ns`, `us`, `ms`, `s`, `m`, or `h`. Defaults to `10s` if the value is omitted. If you specify a value but omit the suffix, the value is interpreted as a number of nanoseconds. |
1085| `threshold`| no | A positive integer which represents the number of times the check must fail before the state is marked as unhealthy. If not specified, a single failure marks the state as unhealthy. |
1086
1087### `file`
1088
1089The `file` structure includes a list of paths to be periodically checked for the\
1090existence of a file. If a file exists at the given path, the health check will
1091fail. You can use this mechanism to bring a registry out of rotation by creating
1092a file.
1093
1094| Parameter | Required | Description |
1095|-----------|----------|-------------------------------------------------------|
1096| `file` | yes | The path to check for existence of a file. |
1097| `interval`| no | How long to wait before repeating the check. A positive integer and an optional suffix indicating the unit of time. The suffix is one of `ns`, `us`, `ms`, `s`, `m`, or `h`. Defaults to `10s` if the value is omitted. If you specify a value but omit the suffix, the value is interpreted as a number of nanoseconds. |
1098
1099### `http`
1100
1101The `http` structure includes a list of HTTP URIs to periodically check with
1102`HEAD` requests. If a `HEAD` request does not complete or returns an unexpected
1103status code, the health check will fail.
1104
1105| Parameter | Required | Description |
1106|-----------|----------|-------------------------------------------------------|
1107| `uri` | yes | The URI to check. |
1108| `headers` | no | Static headers to add to each request. Each header's name is a key beneath `headers`, and each value is a list of payloads for that header name. Values must always be lists. |
1109| `statuscode` | no | The expected status code from the HTTP URI. Defaults to `200`. |
1110| `timeout` | no | How long to wait before timing out the HTTP request. A positive integer and an optional suffix indicating the unit of time. The suffix is one of `ns`, `us`, `ms`, `s`, `m`, or `h`. If you specify a value but omit the suffix, the value is interpreted as a number of nanoseconds. |
1111| `interval`| no | How long to wait before repeating the check. A positive integer and an optional suffix indicating the unit of time. The suffix is one of `ns`, `us`, `ms`, `s`, `m`, or `h`. Defaults to `10s` if the value is omitted. If you specify a value but omit the suffix, the value is interpreted as a number of nanoseconds. |
1112| `threshold`| no | The number of times the check must fail before the state is marked as unhealthy. If this field is not specified, a single failure marks the state as unhealthy. |
1113
1114### `tcp`
1115
1116The `tcp` structure includes a list of TCP addresses to periodically check using
1117TCP connection attempts. Addresses must include port numbers. If a connection
1118attempt fails, the health check will fail.
1119
1120| Parameter | Required | Description |
1121|-----------|----------|-------------------------------------------------------|
1122| `addr` | yes | The TCP address and port to connect to. |
1123| `timeout` | no | How long to wait before timing out the TCP connection. A positive integer and an optional suffix indicating the unit of time. The suffix is one of `ns`, `us`, `ms`, `s`, `m`, or `h`. If you specify a value but omit the suffix, the value is interpreted as a number of nanoseconds. |
1124| `interval`| no | How long to wait between repetitions of the check. A positive integer and an optional suffix indicating the unit of time. The suffix is one of `ns`, `us`, `ms`, `s`, `m`, or `h`. Defaults to `10s` if the value is omitted. If you specify a value but omit the suffix, the value is interpreted as a number of nanoseconds. |
1125| `threshold`| no | The number of times the check must fail before the state is marked as unhealthy. If this field is not specified, a single failure marks the state as unhealthy. |
1126
1127
1128## `proxy`
1129
1130```
1131proxy:
1132 remoteurl: https://registry-1.docker.io
1133 username: [username]
1134 password: [password]
1135```
1136
1137The `proxy` structure allows a registry to be configured as a pull-through cache
1138to Docker Hub. See
1139[mirror](https://github.com/docker/docker.github.io/tree/master/registry/recipes/mirror.md)
1140for more information. Pushing to a registry configured as a pull-through cache
1141is unsupported.
1142
1143| Parameter | Required | Description |
1144|-----------|----------|-------------------------------------------------------|
1145| `remoteurl`| yes | The URL for the repository on Docker Hub. |
1146| `username` | no | The username registered with Docker Hub which has access to the repository. |
1147| `password` | no | The password used to authenticate to Docker Hub using the username specified in `username`. |
1148
1149
1150To enable pulling private repositories (e.g. `batman/robin`) specify the
1151username (such as `batman`) and the password for that username.
1152
1153> **Note**: These private repositories are stored in the proxy cache's storage.
1154> Take appropriate measures to protect access to the proxy cache.
1155
1156## `compatibility`
1157
1158```none
1159compatibility:
1160 schema1:
1161 signingkeyfile: /etc/registry/key.json
1162 enabled: true
1163```
1164
1165Use the `compatibility` structure to configure handling of older and deprecated
1166features. Each subsection defines such a feature with configurable behavior.
1167
1168### `schema1`
1169
1170| Parameter | Required | Description |
1171|-----------|----------|-------------------------------------------------------|
1172| `signingkeyfile` | no | The signing private key used to add signatures to `schema1` manifests. If no signing key is provided, a new ECDSA key is generated when the registry starts. |
1173| `enabled` | no | If this is not set to true, `schema1` manifests cannot be pushed. |
1174
1175## `validation`
1176
1177```none
1178validation:
1179 manifests:
1180 urls:
1181 allow:
1182 - ^https?://([^/]+\.)*example\.com/
1183 deny:
1184 - ^https?://www\.example\.com/
1185```
1186
1187### `disabled`
1188
1189The `disabled` flag disables the other options in the `validation`
1190section. They are enabled by default. This option deprecates the `enabled` flag.
1191
1192### `manifests`
1193
1194Use the `manifests` subsection to configure validation of manifests. If
1195`disabled` is `false`, the validation allows nothing.
1196
1197#### `urls`
1198
1199The `allow` and `deny` options are each a list of
1200[regular expressions](https://godoc.org/regexp/syntax) that restrict the URLs in
1201pushed manifests.
1202
1203If `allow` is unset, pushing a manifest containing URLs fails.
1204
1205If `allow` is set, pushing a manifest succeeds only if all URLs match
1206one of the `allow` regular expressions **and** one of the following holds:
1207
12081. `deny` is unset.
12092. `deny` is set but no URLs within the manifest match any of the `deny` regular
1210 expressions.
1211
1212## Example: Development configuration
1213
1214You can use this simple example for local development:
1215
1216```none
1217version: 0.1
1218log:
1219 level: debug
1220storage:
1221 filesystem:
1222 rootdirectory: /var/lib/registry
1223http:
1224 addr: localhost:5000
1225 secret: asecretforlocaldevelopment
1226 debug:
1227 addr: localhost:5001
1228```
1229
1230This example configures the registry instance to run on port `5000`, binding to
1231`localhost`, with the `debug` server enabled. Registry data is stored in the
1232`/var/lib/registry` directory. Logging is set to `debug` mode, which is the most
1233verbose.
1234
1235See
1236[config-example.yml](https://github.com/docker/distribution/blob/master/cmd/registry/config-example.yml)
1237for another simple configuration. Both examples are generally useful for local
1238development.
1239
1240
1241## Example: Middleware configuration
1242
1243This example configures [Amazon Cloudfront](http://aws.amazon.com/cloudfront/)
1244as the storage middleware in a registry. Middleware allows the registry to serve
1245layers via a content delivery network (CDN). This reduces requests to the
1246storage layer.
1247
1248Cloudfront requires the S3 storage driver.
1249
1250This is the configuration expressed in YAML:
1251
1252```none
1253middleware:
1254 storage:
1255 - name: cloudfront
1256 disabled: false
1257 options:
1258 baseurl: http://d111111abcdef8.cloudfront.net
1259 privatekey: /path/to/asecret.pem
1260 keypairid: asecret
1261 duration: 60s
1262```
1263
1264See the configuration reference for [Cloudfront](#cloudfront) for more
1265information about configuration options.
1266
1267> **Note**: Cloudfront keys exist separately from other AWS keys. See
1268> [the documentation on AWS credentials](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html)
1269> for more information.
View as plain text