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