TrueCloudLab/distribution
12
0
Fork 3
Code Issues 2 Pull requests Projects Releases 2 Packages Wiki Activity Actions

docs: fix yaml sections format at docs.docker.com

Browse source 
yaml sections in the documentation does not display well on
docs.docker.com. This is due to the syntax highlighting
which uses highlight.js and does not support yaml
currently.
The fix is to remove triple back ticks and indent instead.
We loose yaml syntax highlighting on github, but it displays
an acceptable version on both github and docs.docker.com.

Signed-off-by: Olivier Jacques <olivier.jacques@hp.com>
This commit is contained in:
Olivier Jacques 2015-07-10 23:22:06 +02:00
parent 419bbc2da6
commit b3683863dd
2 changed files with 291 additions and 328 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

599
docs/configuration.md
View file

@ -24,17 +24,13 @@ 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.
@ -53,128 +49,126 @@ 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.
```yaml version: 0.1
version: 0.1 log:
log: level: debug
level: debug formatter: text
formatter: text fields:
fields: service: registry
service: registry environment: staging
environment: staging hooks:
hooks: - type: mail
- type: mail disabled: true
disabled: true levels:
levels: - panic
- panic options:
options: smtp:
smtp: addr: mail.example.com:25
addr: mail.example.com:25 username: mailuser
username: mailuser password: password
password: password insecure: true
insecure: true 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 azure:
azure: accountname: accountname
accountname: accountname accountkey: base64encodedaccountkey
accountkey: base64encodedaccountkey container: containername
container: containername s3:
s3: accesskey: awsaccesskey
accesskey: awsaccesskey secretkey: awssecretkey
secretkey: awssecretkey region: us-west-1
region: us-west-1 bucket: bucketname
bucket: bucketname encrypt: true
encrypt: true secure: true
secure: true v4auth: true
v4auth: true chunksize: 5242880
chunksize: 5242880 rootdirectory: /s3/object/name/prefix
rootdirectory: /s3/object/name/prefix rados:
rados: poolname: radospool
poolname: radospool username: radosuser
username: radosuser chunksize: 4194304
chunksize: 4194304 cache:
cache: blobdescriptor: redis
blobdescriptor: redis maintenance:
maintenance: uploadpurging:
uploadpurging: enabled: true
enabled: true age: 168h
age: 168h interval: 24h
interval: 24h dryrun: false
dryrun: false auth:
auth: silly:
silly: realm: silly-realm
realm: silly-realm service: silly-service
service: silly-service token:
token: realm: token-realm
realm: token-realm service: token-service
service: token-service issuer: registry-token-issuer
issuer: registry-token-issuer rootcertbundle: /root/certs/bundle
rootcertbundle: /root/certs/bundle 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: foo: bar
foo: bar repository:
repository: - name: ARepositoryMiddleware
- name: ARepositoryMiddleware options:
options: foo: bar
foo: bar storage:
storage: - name: cloudfront
- name: cloudfront options:
options: baseurl: https://my.cloudfronted.domain.com/
baseurl: https://my.cloudfronted.domain.com/ privatekey: /path/to/pem
privatekey: /path/to/pem keypairid: cloudfrontkeypairid
keypairid: cloudfrontkeypairid duration: 3000
duration: 3000 reporting:
reporting: bugsnag:
bugsnag: apikey: bugsnagapikey
apikey: bugsnagapikey releasestage: bugsnagreleasestage
releasestage: bugsnagreleasestage endpoint: bugsnagendpoint
endpoint: bugsnagendpoint newrelic:
newrelic: 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/ secret: asecretforlocaldevelopment
secret: asecretforlocaldevelopment tls:
tls: certificate: /path/to/x509/public
certificate: /path/to/x509/public key: /path/to/x509/private
key: /path/to/x509/private clientcas:
clientcas: - /path/to/ca.pem
- /path/to/ca.pem - /path/to/another/ca.pem
- /path/to/another/ca.pem debug:
debug: addr: localhost:5001
addr: localhost:5001 notifications:
notifications: endpoints:
endpoints: - name: alistener
- name: alistener disabled: false
disabled: false url: https://my.listener.com/event
url: https://my.listener.com/event headers: <http.Header>
headers: <http.Header> timeout: 500
timeout: 500 threshold: 5
threshold: 5 backoff: 1000
backoff: 1000 redis:
redis: addr: localhost:6379
addr: localhost:6379 password: asecret
password: asecret db: 0
db: 0 dialtimeout: 10ms
dialtimeout: 10ms readtimeout: 10ms
readtimeout: 10ms writetimeout: 10ms
writetimeout: 10ms pool:
pool: maxidle: 16
maxidle: 16 maxactive: 64
maxactive: 64 idletimeout: 300s
idletimeout: 300s
```
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
@ -185,9 +179,7 @@ the children marked **required**.
## version ## version
```yaml 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
@ -199,14 +191,12 @@ 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.
```yaml log:
log: level: debug
level: debug formatter: text
formatter: text fields:
fields: service: registry
service: registry environment: staging
environment: staging
```
<table> <table>
<tr> <tr>
@ -256,22 +246,19 @@ log:
## hooks ## hooks
hooks:
```yaml - type: mail
hooks: levels:
- type: mail - panic
levels: options:
- panic smtp:
options: addr: smtp.sendhost.com:25
smtp: username: sendername
addr: smtp.sendhost.com:25 password: password
username: sendername insecure: true
password: password from: name@sendhost.com
insecure: true to:
from: name@sendhost.com - name@receivehost.com
to:
- 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.
@ -281,46 +268,42 @@ Refer to `loglevel` to configure the level of messages printed.
> **DEPRECATED:** Please use [log](#logs) instead. > **DEPRECATED:** Please use [log](#logs) instead.
```yaml 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
```yaml storage:
storage: filesystem:
filesystem: rootdirectory: /var/lib/registry
rootdirectory: /var/lib/registry azure:
azure: accountname: accountname
accountname: accountname accountkey: base64encodedaccountkey
accountkey: base64encodedaccountkey container: containername
container: containername s3:
s3: accesskey: awsaccesskey
accesskey: awsaccesskey secretkey: awssecretkey
secretkey: awssecretkey region: us-west-1
region: us-west-1 bucket: bucketname
bucket: bucketname encrypt: true
encrypt: true secure: true
secure: true v4auth: true
v4auth: true chunksize: 5242880
chunksize: 5242880 rootdirectory: /s3/object/name/prefix
rootdirectory: /s3/object/name/prefix rados:
rados: poolname: radospool
poolname: radospool username: radosuser
username: radosuser chunksize: 4194304
chunksize: 4194304 cache:
cache: blobdescriptor: inmemory
blobdescriptor: inmemory maintenance:
maintenance: uploadpurging:
uploadpurging: enabled: true
enabled: true age: 168h
age: 168h interval: 24h
interval: 24h dryrun: false
dryrun: 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 must configure one backend; if you configure more, the registry returns an error.
@ -599,20 +582,18 @@ Note: `age` and `interval` are strings containing a number with optional fractio
## auth ## auth
```yaml auth:
auth: silly:
silly: realm: silly-realm
realm: silly-realm service: silly-service
service: silly-service token:
token: realm: token-realm
realm: token-realm service: token-service
service: token-service issuer: registry-token-issuer
issuer: registry-token-issuer rootcertbundle: /root/certs/bundle
rootcertbundle: /root/certs/bundle 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 2 possible auth providers, `silly` and `token`. You can configure only currently 2 possible auth providers, `silly` and `token`. You can configure only
@ -711,7 +692,7 @@ the token so it must match the value configured for the issuer.
<code>rootcertbundle</code> <code>rootcertbundle</code>
</td> </td>
<td> <td>
yes yes
</td> </td>
<td> <td>
The absolute path to the root certificate bundle. This bundle contains the The absolute path to the root certificate bundle. This bundle contains the
@ -777,24 +758,22 @@ object they're wrapping. This means a registry middleware must implement the
Currently only one middleware, `cloudfront`, a storage middleware, is supported Currently only one middleware, `cloudfront`, a storage middleware, is supported
in the registry implementation. in the registry implementation.
```yaml middleware:
middleware: registry:
registry: - name: ARegistryMiddleware
- name: ARegistryMiddleware options:
options: foo: bar
foo: bar repository:
repository: - name: ARepositoryMiddleware
- name: ARepositoryMiddleware options:
options: foo: bar
foo: bar storage:
storage: - name: cloudfront
- name: cloudfront options:
options: baseurl: https://my.cloudfronted.domain.com/
baseurl: https://my.cloudfronted.domain.com/ privatekey: /path/to/pem
privatekey: /path/to/pem keypairid: cloudfrontkeypairid
keypairid: cloudfrontkeypairid duration: 3000
duration: 3000
```
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
@ -861,17 +840,15 @@ interpretation of the options.
## reporting ## reporting
```yaml reporting:
reporting: bugsnag:
bugsnag: apikey: bugsnagapikey
apikey: bugsnagapikey releasestage: bugsnagreleasestage
releasestage: bugsnagreleasestage endpoint: bugsnagendpoint
endpoint: bugsnagendpoint newrelic:
newrelic: 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
@ -969,21 +946,19 @@ configuration may contain both.
## http ## http
```yaml http:
http: addr: localhost:5000
addr: localhost:5000 net: tcp
net: tcp prefix: /my/nested/registry/
prefix: /my/nested/registry/ secret: asecretforlocaldevelopment
secret: asecretforlocaldevelopment tls:
tls: certificate: /path/to/x509/public
certificate: /path/to/x509/public key: /path/to/x509/private
key: /path/to/x509/private clientcas:
clientcas: - /path/to/ca.pem
- /path/to/ca.pem - /path/to/another/ca.pem
- /path/to/another/ca.pem debug:
debug: addr: localhost:5001
addr: localhost:5001
```
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.
@ -1109,17 +1084,15 @@ specifies the `HOST:PORT` on which the debug server should accept connections.
## notifications ## notifications
```yaml notifications:
notifications: endpoints:
endpoints: - name: alistener
- name: alistener disabled: false
disabled: false url: https://my.listener.com/event
url: https://my.listener.com/event headers: <http.Header>
headers: <http.Header> timeout: 500
timeout: 500 threshold: 5
threshold: 5 backoff: 1000
backoff: 1000
```
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`.
@ -1161,7 +1134,7 @@ A boolean to enable/disable notifications for a service.
<code>url</code> <code>url</code>
</td> </td>
<td> <td>
yes yes
</td> </td>
<td> <td>
The URL to which events should be published. The URL to which events should be published.
@ -1189,11 +1162,11 @@ The URL to which events should be published.
An HTTP timeout value. This field takes a positive integer and an optional An HTTP timeout value. This field takes a positive integer and an optional
suffix indicating the unit of time. Possible units are: suffix indicating the unit of time. Possible units are:
<ul> <ul>
<li><code>ns</code> (nanoseconds)</li> <li><code>ns</code> (nanoseconds)</li>
<li><code>us</code> (microseconds)</li> <li><code>us</code> (microseconds)</li>
<li><code>ms</code> (milliseconds)</li> <li><code>ms</code> (milliseconds)</li>
<li><code>s</code> (seconds)</li> <li><code>s</code> (seconds)</li>
<li><code>m</code> (minutes)</li> <li><code>m</code> (minutes)</li>
<li><code>h</code> (hours)</li> <li><code>h</code> (hours)</li>
</ul> </ul>
If you omit the suffix, the system interprets the value as nanoseconds. If you omit the suffix, the system interprets the value as nanoseconds.
@ -1222,11 +1195,11 @@ The URL to which events should be published.
integer and an optional suffix indicating the unit of time. Possible units integer and an optional suffix indicating the unit of time. Possible units
are: are:
<ul> <ul>
<li><code>ns</code> (nanoseconds)</li> <li><code>ns</code> (nanoseconds)</li>
<li><code>us</code> (microseconds)</li> <li><code>us</code> (microseconds)</li>
<li><code>ms</code> (milliseconds)</li> <li><code>ms</code> (milliseconds)</li>
<li><code>s</code> (seconds)</li> <li><code>s</code> (seconds)</li>
<li><code>m</code> (minutes)</li> <li><code>m</code> (minutes)</li>
<li><code>h</code> (hours)</li> <li><code>h</code> (hours)</li>
</ul> </ul>
If you omit the suffix, the system interprets the value as nanoseconds. If you omit the suffix, the system interprets the value as nanoseconds.
@ -1237,19 +1210,17 @@ The URL to which events should be published.
## redis ## redis
```yaml redis:
redis: addr: localhost:6379
addr: localhost:6379 password: asecret
password: asecret db: 0
db: 0 dialtimeout: 10ms
dialtimeout: 10ms readtimeout: 10ms
readtimeout: 10ms writetimeout: 10ms
writetimeout: 10ms pool:
pool: 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
@ -1334,12 +1305,10 @@ with the [pool](#pool) subsection.
### pool ### pool
```yaml 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.
@ -1391,19 +1360,17 @@ Configure the behavior of the Redis connection pool.
The following is a simple example you can use for local development: The following is a simple example you can use for local development:
```yaml version: 0.1
version: 0.1 log:
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
@ -1446,25 +1413,23 @@ conjunction with the S3 storage driver.
<li><code>baseurl:</code> The Cloudfront base URL.</li> <li><code>baseurl:</code> The Cloudfront base URL.</li>
<li><code>privatekey:</code> The location of your AWS private key on the filesystem. </li> <li><code>privatekey:</code> The location of your AWS private key on the filesystem. </li>
<li><code>keypairid:</code> The ID of your Cloudfront keypair. </li> <li><code>keypairid:</code> The ID of your Cloudfront keypair. </li>
<li><code>duration:</code> The duration in minutes for which the URL is valid. Default is 20. </li> <li><code>duration:</code> The duration in minutes for which the URL is valid. Default is 20. </li>
</ul> </ul>
</td> </td>
</tr> </tr>
</table> </table>
The following example illustrates these values: The following example illustrates these values:
``` middleware:
middleware: storage:
storage: - name: cloudfront
- name: cloudfront disabled: false
disabled: false options:
options: baseurl: http://d111111abcdef8.cloudfront.net
baseurl: http://d111111abcdef8.cloudfront.net 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

20
docs/notifications.md
View file

@ -36,17 +36,15 @@ order is not guaranteed.
To setup a registry instance to send notifications to endpoints, one must add To setup a registry instance to send notifications to endpoints, one must add
them to the configuration. A simple example follows: them to the configuration. A simple example follows:
```yaml notifications:
notifications: endpoints:
endpoints: - name: alistener
- name: alistener url: https://mylistener.example.com/event
url: https://mylistener.example.com/event headers:
headers: Authorization: [Bearer <your token, if needed>]
Authorization: [Bearer <your token, if needed>] timeout: 500ms
timeout: 500ms threshold: 5
threshold: 5 backoff: 1s
backoff: 1s
```
The above would configure the registry with an endpoint to send events to The above would configure the registry with an endpoint to send events to
`https://mylistener.example.com/event`, with the header "Authorization: Bearer `https://mylistener.example.com/event`, with the header "Authorization: Bearer