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