alexvanin/distribution
1
0
Fork 0
forked from TrueCloudLab/distribution
Code Pull requests Activity

Merge pull request #2103 from joaofnfernandes/fix-configuration.md

Browse source 
Format configuration.md with code fences to avoid render issues
This commit is contained in:
Derek McGowan 2016-12-15 16:56:36 -08:00 committed by GitHub
commit 6a74c94bf8
1 changed files with 510 additions and 460 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

158
docs/configuration.md
View file

@ -17,13 +17,17 @@ To override a configuration option, create an environment variable named
and the `_` (underscore) represents indention levels. For example, you can and the `_` (underscore) represents indention levels. For example, you can
configure the `rootdirectory` of the `filesystem` storage backend: configure the `rootdirectory` of the `filesystem` storage backend:
storage: ```
storage:
filesystem: filesystem:
rootdirectory: /var/lib/registry rootdirectory: /var/lib/registry
```
To override this value, set an environment variable like this: To override this value, set an environment variable like this:
REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere ```
REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere
```
This variable overrides the `/var/lib/registry` value to the `/somewhere` This variable overrides the `/var/lib/registry` value to the `/somewhere`
directory. directory.
@ -36,9 +40,11 @@ If the default configuration is not a sound basis for your usage, or if you are
Typically, create a new configuration file from scratch, and call it `config.yml`, then: Typically, create a new configuration file from scratch, and call it `config.yml`, then:
docker run -d -p 5000:5000 --restart=always --name registry \ ```
docker run -d -p 5000:5000 --restart=always --name registry \
-v `pwd`/config.yml:/etc/docker/registry/config.yml \ -v `pwd`/config.yml:/etc/docker/registry/config.yml \
registry:2 registry:2
```
You can (and probably should) use [this as a starting point](https://github.com/docker/distribution/blob/master/cmd/registry/config-example.yml). You can (and probably should) use [this as a starting point](https://github.com/docker/distribution/blob/master/cmd/registry/config-example.yml).
@ -48,8 +54,9 @@ This section lists all the registry configuration options. Some options in
the list are mutually exclusive. So, make sure to read the detailed reference the list are mutually exclusive. So, make sure to read the detailed reference
information about each option that appears later in this page. information about each option that appears later in this page.
version: 0.1 ```
log: version: 0.1
log:
accesslog: accesslog:
disabled: true disabled: true
level: debug level: debug
@ -71,8 +78,8 @@ information about each option that appears later in this page.
from: sender@example.com from: sender@example.com
to: to:
- errors@example.com - errors@example.com
loglevel: debug # deprecated: use "log" loglevel: debug # deprecated: use "log"
storage: storage:
filesystem: filesystem:
rootdirectory: /var/lib/registry rootdirectory: /var/lib/registry
maxthreads: 100 maxthreads: 100
@ -138,7 +145,7 @@ information about each option that appears later in this page.
dryrun: false dryrun: false
readonly: readonly:
enabled: false enabled: false
auth: auth:
silly: silly:
realm: silly-realm realm: silly-realm
service: silly-service service: silly-service
@ -150,7 +157,7 @@ information about each option that appears later in this page.
htpasswd: htpasswd:
realm: basic-realm realm: basic-realm
path: /path/to/htpasswd path: /path/to/htpasswd
middleware: middleware:
registry: registry:
- name: ARegistryMiddleware - name: ARegistryMiddleware
options: options:
@ -170,7 +177,7 @@ information about each option that appears later in this page.
- name: redirect - name: redirect
options: options:
baseurl: https://example.com/ baseurl: https://example.com/
reporting: reporting:
bugsnag: bugsnag:
apikey: bugsnagapikey apikey: bugsnagapikey
releasestage: bugsnagreleasestage releasestage: bugsnagreleasestage
@ -179,7 +186,7 @@ information about each option that appears later in this page.
licensekey: newreliclicensekey licensekey: newreliclicensekey
name: newrelicname name: newrelicname
verbose: true verbose: true
http: http:
addr: localhost:5000 addr: localhost:5000
prefix: /my/nested/registry/ prefix: /my/nested/registry/
host: https://myregistryaddress.org:5000 host: https://myregistryaddress.org:5000
@ -200,7 +207,7 @@ information about each option that appears later in this page.
X-Content-Type-Options: [nosniff] X-Content-Type-Options: [nosniff]
http2: http2:
disabled: false disabled: false
notifications: notifications:
endpoints: endpoints:
- name: alistener - name: alistener
disabled: false disabled: false
@ -211,7 +218,7 @@ information about each option that appears later in this page.
backoff: 1000 backoff: 1000
ignoredmediatypes: ignoredmediatypes:
- application/octet-stream - application/octet-stream
redis: redis:
addr: localhost:6379 addr: localhost:6379
password: asecret password: asecret
db: 0 db: 0
@ -222,7 +229,7 @@ information about each option that appears later in this page.
maxidle: 16 maxidle: 16
maxactive: 64 maxactive: 64
idletimeout: 300s idletimeout: 300s
health: health:
storagedriver: storagedriver:
enabled: true enabled: true
interval: 10s interval: 10s
@ -243,20 +250,21 @@ information about each option that appears later in this page.
timeout: 3s timeout: 3s
interval: 10s interval: 10s
threshold: 3 threshold: 3
proxy: proxy:
remoteurl: https://registry-1.docker.io remoteurl: https://registry-1.docker.io
username: [username] username: [username]
password: [password] password: [password]
compatibility: compatibility:
schema1: schema1:
signingkeyfile: /etc/registry/key.json signingkeyfile: /etc/registry/key.json
validation: validation:
manifests: manifests:
urls: urls:
allow: allow:
- ^https?://([^/]+\.)*example\.com/ - ^https?://([^/]+\.)*example\.com/
deny: deny:
- ^https?://www\.example\.com/ - ^https?://www\.example\.com/
```
In some instances a configuration option is **optional** but it contains child In some instances a configuration option is **optional** but it contains child
options marked as **required**. This indicates that you can omit the parent with options marked as **required**. This indicates that you can omit the parent with
@ -265,7 +273,9 @@ the children marked **required**.
## version ## version
version: 0.1 ```
version: 0.1
```
The `version` option is **required**. It specifies the configuration's version. The `version` option is **required**. It specifies the configuration's version.
It is expected to remain a top-level field, to allow for a consistent version It is expected to remain a top-level field, to allow for a consistent version
@ -277,7 +287,8 @@ The `log` subsection configures the behavior of the logging system. The logging
system outputs everything to stdout. You can adjust the granularity and format system outputs everything to stdout. You can adjust the granularity and format
with this configuration section. with this configuration section.
log: ```
log:
accesslog: accesslog:
disabled: true disabled: true
level: debug level: debug
@ -285,6 +296,7 @@ with this configuration section.
fields: fields:
service: registry service: registry
environment: staging environment: staging
```
<table> <table>
<tr> <tr>
@ -335,8 +347,10 @@ with this configuration section.
### accesslog ### accesslog
accesslog: ```
accesslog:
disabled: true disabled: true
```
Within `log`, `accesslog` configures the behavior of the access logging Within `log`, `accesslog` configures the behavior of the access logging
system. By default, the access logging system outputs to stdout in system. By default, the access logging system outputs to stdout in
@ -345,7 +359,8 @@ Access logging can be disabled by setting the boolean flag `disabled` to `true`.
## hooks ## hooks
hooks: ```
hooks:
- type: mail - type: mail
levels: levels:
- panic - panic
@ -358,6 +373,7 @@ Access logging can be disabled by setting the boolean flag `disabled` to `true`.
from: name@sendhost.com from: name@sendhost.com
to: to:
- name@receivehost.com - name@receivehost.com
```
The `hooks` subsection configures the logging hooks' behavior. This subsection The `hooks` subsection configures the logging hooks' behavior. This subsection
includes a sequence handler which you can use for sending mail, for example. includes a sequence handler which you can use for sending mail, for example.
@ -367,14 +383,17 @@ Refer to `loglevel` to configure the level of messages printed.
> **DEPRECATED:** Please use [log](#log) instead. > **DEPRECATED:** Please use [log](#log) instead.
loglevel: debug ```
loglevel: debug
```
Permitted values are `error`, `warn`, `info` and `debug`. The default is Permitted values are `error`, `warn`, `info` and `debug`. The default is
`info`. `info`.
## storage ## storage
storage: ```
storage:
filesystem: filesystem:
rootdirectory: /var/lib/registry rootdirectory: /var/lib/registry
azure: azure:
@ -436,12 +455,13 @@ Permitted values are `error`, `warn`, `info` and `debug`. The default is
dryrun: false dryrun: false
redirect: redirect:
disable: false disable: false
```
The storage option is **required** and defines which storage backend is in use. The storage option is **required** and defines which storage backend is in use.
You must configure one backend; if you configure more, the registry returns an error. You can choose any of these backend storage drivers: You must configure one backend; if you configure more, the registry returns an error. You can choose any of these backend storage drivers:
| Storage&nbsp;driver | Description | Storage&nbsp;driver | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | |:--------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `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). | | `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). |
| `azure` | Uses Microsoft's Azure Blob Storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/azure.md). | | `azure` | Uses Microsoft's Azure Blob Storage. See the [driver's reference documentation](https://github.com/docker/docker.github.io/tree/master/registry/storage-drivers/azure.md). |
| `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). | | `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). |
@ -460,7 +480,9 @@ backing data-store. If you do use a Windows volume, you must ensure that the
`PATH` to the mount point is within Windows' `MAX_PATH` limits (typically 255 `PATH` to the mount point is within Windows' `MAX_PATH` limits (typically 255
characters). Failure to do so can result in the following error message: characters). Failure to do so can result in the following error message:
mkdir /XXX protocol error and your registry will not function properly. ```
mkdir /XXX protocol error and your registry will not function properly.
```
### Maintenance ### Maintenance
@ -476,12 +498,12 @@ configure upload directory purging, the following parameters
must be set. must be set.
| Parameter | Required | Description | Parameter | Required | Description |
--------- | -------- | ----------- |:-----------|:---------|:---------------------------------------------------------------------------------------------------|
`enabled` | yes | Set to true to enable upload purging. Default=true. | | `enabled` | yes | Set to true to enable upload purging. Default=true. |
`age` | yes | Upload directories which are older than this age will be deleted. Default=168h (1 week) | `age` | yes | Upload directories which are older than this age will be deleted. Default=168h (1 week) |
`interval` | yes | The interval between upload directory purging. Default=24h. | `interval` | yes | The interval between upload directory purging. Default=24h. |
`dryrun` | yes | dryrun can be set to true to obtain a summary of what directories will be deleted. Default=false. | `dryrun` | yes | dryrun can be set to true to obtain a summary of what directories will be deleted. Default=false. |
Note: `age` and `interval` are strings containing a number with optional fraction and a unit suffix: e.g. 45m, 2h10m, 168h (1 week). Note: `age` and `interval` are strings containing a number with optional fraction and a unit suffix: e.g. 45m, 2h10m, 168h (1 week).
@ -501,8 +523,10 @@ Use the `delete` subsection to enable the deletion of image blobs and manifests
by digest. It defaults to false, but it can be enabled by writing the following by digest. It defaults to false, but it can be enabled by writing the following
on the configuration file: on the configuration file:
delete: ```
delete:
enabled: true enabled: true
```
### cache ### cache
@ -530,13 +554,15 @@ doing aggressive caching.
Redirects can be disabled by adding a single flag `disable`, set to `true` Redirects can be disabled by adding a single flag `disable`, set to `true`
under the `redirect` section: under the `redirect` section:
redirect: ```
redirect:
disable: true disable: true
```
## auth ## auth
auth: ```
auth:
silly: silly:
realm: silly-realm realm: silly-realm
service: silly-service service: silly-service
@ -548,6 +574,7 @@ under the `redirect` section:
htpasswd: htpasswd:
realm: basic-realm realm: basic-realm
path: /path/to/htpasswd path: /path/to/htpasswd
```
The `auth` option is **optional**. There are The `auth` option is **optional**. There are
currently 3 possible auth providers, `silly`, `token` and `htpasswd`. You can configure only currently 3 possible auth providers, `silly`, `token` and `htpasswd`. You can configure only
@ -712,7 +739,8 @@ object they're wrapping. This means a registry middleware must implement the
An example configuration of the `cloudfront` middleware, a storage middleware: An example configuration of the `cloudfront` middleware, a storage middleware:
middleware: ```
middleware:
registry: registry:
- name: ARegistryMiddleware - name: ARegistryMiddleware
options: options:
@ -728,6 +756,7 @@ An example configuration of the `cloudfront` middleware, a storage middleware:
privatekey: /path/to/pem privatekey: /path/to/pem
keypairid: cloudfrontkeypairid keypairid: cloudfrontkeypairid
duration: 3000s duration: 3000s
```
Each middleware entry has `name` and `options` entries. The `name` must Each middleware entry has `name` and `options` entries. The `name` must
correspond to the name under which the middleware registers itself. The correspond to the name under which the middleware registers itself. The
@ -798,12 +827,13 @@ storage middleware can be used to specify a custom URL to a location
of a proxy for the layer stored by the S3 storage driver. of a proxy for the layer stored by the S3 storage driver.
| Parameter | Required | Description | | Parameter | Required | Description |
| --- | --- | --- | |:----------|:---------|:------------------------------------------------------------------------------------------------------------|
| baseurl | yes | `SCHEME://HOST` at which layers are served. Can also contain port. For example, `https://example.com:5443`. | | baseurl | yes | `SCHEME://HOST` at which layers are served. Can also contain port. For example, `https://example.com:5443`. |
## reporting ## reporting
reporting: ```
reporting:
bugsnag: bugsnag:
apikey: bugsnagapikey apikey: bugsnagapikey
releasestage: bugsnagreleasestage releasestage: bugsnagreleasestage
@ -812,6 +842,7 @@ of a proxy for the layer stored by the S3 storage driver.
licensekey: newreliclicensekey licensekey: newreliclicensekey
name: newrelicname name: newrelicname
verbose: true verbose: true
```
The `reporting` option is **optional** and configures error and metrics The `reporting` option is **optional** and configures error and metrics
reporting tools. At the moment only two services are supported, [New reporting tools. At the moment only two services are supported, [New
@ -909,7 +940,8 @@ configuration may contain both.
## http ## http
http: ```
http:
addr: localhost:5000 addr: localhost:5000
net: tcp net: tcp
prefix: /my/nested/registry/ prefix: /my/nested/registry/
@ -931,6 +963,7 @@ configuration may contain both.
X-Content-Type-Options: [nosniff] X-Content-Type-Options: [nosniff]
http2: http2:
disabled: false disabled: false
```
The `http` option details the configuration for the HTTP server that hosts the registry. The `http` option details the configuration for the HTTP server that hosts the registry.
@ -1164,7 +1197,8 @@ settings for the registry.
## notifications ## notifications
notifications: ```
notifications:
endpoints: endpoints:
- name: alistener - name: alistener
disabled: false disabled: false
@ -1175,6 +1209,7 @@ settings for the registry.
backoff: 1000 backoff: 1000
ignoredmediatypes: ignoredmediatypes:
- application/octet-stream - application/octet-stream
```
The notifications option is **optional** and currently may contain a single The notifications option is **optional** and currently may contain a single
option, `endpoints`. option, `endpoints`.
@ -1306,7 +1341,8 @@ The URL to which events should be published.
## redis ## redis
redis: ```
redis:
addr: localhost:6379 addr: localhost:6379
password: asecret password: asecret
db: 0 db: 0
@ -1317,6 +1353,7 @@ The URL to which events should be published.
maxidle: 16 maxidle: 16
maxactive: 64 maxactive: 64
idletimeout: 300s idletimeout: 300s
```
Declare parameters for constructing the redis connections. Registry instances Declare parameters for constructing the redis connections. Registry instances
may use the Redis instance for several applications. The current purpose is may use the Redis instance for several applications. The current purpose is
@ -1404,10 +1441,12 @@ as the registry does not set an expire value on keys.
### pool ### pool
pool: ```
pool:
maxidle: 16 maxidle: 16
maxactive: 64 maxactive: 64
idletimeout: 300s idletimeout: 300s
```
Configure the behavior of the Redis connection pool. Configure the behavior of the Redis connection pool.
@ -1456,7 +1495,8 @@ Configure the behavior of the Redis connection pool.
## health ## health
health: ```
health:
storagedriver: storagedriver:
enabled: true enabled: true
interval: 10s interval: 10s
@ -1477,6 +1517,7 @@ Configure the behavior of the Redis connection pool.
timeout: 3s timeout: 3s
interval: 10s interval: 10s
threshold: 3 threshold: 3
```
The health option is **optional**. It may contain preferences for a periodic The health option is **optional**. It may contain preferences for a periodic
health check on the storage driver's backend storage, and optional periodic health check on the storage driver's backend storage, and optional periodic
@ -1785,10 +1826,12 @@ The TCP address to connect to, including a port number.
## Proxy ## Proxy
proxy: ```
proxy:
remoteurl: https://registry-1.docker.io remoteurl: https://registry-1.docker.io
username: [username] username: [username]
password: [password] password: [password]
```
Proxy enables a registry to be configured as a pull through cache to the official Docker Hub. See [mirror](https://github.com/docker/docker.github.io/tree/master/registry/recipes/mirror.md) for more information. Pushing to a registry configured as a pull through cache is currently unsupported. Proxy enables a registry to be configured as a pull through cache to the official Docker Hub. See [mirror](https://github.com/docker/docker.github.io/tree/master/registry/recipes/mirror.md) for more information. Pushing to a registry configured as a pull through cache is currently unsupported.
@ -1837,9 +1880,11 @@ To enable pulling private repositories (e.g. `batman/robin`) a username and pass
## Compatibility ## Compatibility
compatibility: ```
compatibility:
schema1: schema1:
signingkeyfile: /etc/registry/key.json signingkeyfile: /etc/registry/key.json
```
Configure handling of older and deprecated features. Each subsection Configure handling of older and deprecated features. Each subsection
defines such a feature with configurable behavior. defines such a feature with configurable behavior.
@ -1869,13 +1914,15 @@ defines such a feature with configurable behavior.
## Validation ## Validation
validation: ```
validation:
manifests: manifests:
urls: urls:
allow: allow:
- ^https?://([^/]+\.)*example\.com/ - ^https?://([^/]+\.)*example\.com/
deny: deny:
- ^https?://www\.example\.com/ - ^https?://www\.example\.com/
```
### disabled ### disabled
@ -1905,17 +1952,19 @@ one of the `allow` regular expressions and one of the following holds:
The following is a simple example you can use for local development: The following is a simple example you can use for local development:
version: 0.1 ```
log: version: 0.1
log:
level: debug level: debug
storage: storage:
filesystem: filesystem:
rootdirectory: /var/lib/registry rootdirectory: /var/lib/registry
http: http:
addr: localhost:5000 addr: localhost:5000
secret: asecretforlocaldevelopment secret: asecretforlocaldevelopment
debug: debug:
addr: localhost:5001 addr: localhost:5001
```
The above configures the registry instance to run on port `5000`, binding to The above configures the registry instance to run on port `5000`, binding to
`localhost`, with the `debug` server enabled. Registry data storage is in the `localhost`, with the `debug` server enabled. Registry data storage is in the
@ -1947,7 +1996,7 @@ conjunction with the S3 storage driver.
<td>The storage middleware name. Currently <code>cloudfront</code> is an accepted value.</td> <td>The storage middleware name. Currently <code>cloudfront</code> is an accepted value.</td>
</tr> </tr>
<tr> <tr>
<td><code>disabled<code></td> <td><code>disabled</code></td>
<td>Set to <code>false</code> to easily disable the middleware.</td> <td>Set to <code>false</code> to easily disable the middleware.</td>
</tr> </tr>
<tr> <tr>
@ -1966,7 +2015,8 @@ conjunction with the S3 storage driver.
The following example illustrates these values: The following example illustrates these values:
middleware: ```
middleware:
storage: storage:
- name: cloudfront - name: cloudfront
disabled: false disabled: false
@ -1975,7 +2025,7 @@ The following example illustrates these values:
privatekey: /path/to/asecret.pem privatekey: /path/to/asecret.pem
keypairid: asecret keypairid: asecret
duration: 60 duration: 60
```
>**Note**: Cloudfront keys exist separately to other AWS keys. See >**Note**: Cloudfront keys exist separately to other AWS keys. See
>[the documentation on AWS credentials](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html) >[the documentation on AWS credentials](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html)