docker-registry 0.9.1

Registry server for Docker

> **Notice:** *This repository hosts the classic (stable) python docker-registry. If you are looking for the next-generation of docker distribution tools (including the new golang registry), please head over to [docker/distribution](https://github.com/docker/distribution) instead.*

Docker-Registry
===============

[](https://travis-ci.org/docker/docker-registry)

About this document
===================

As the documentation evolves with different registry versions, be sure that before reading any further you:

* check which version of the registry you are running
* switch to the corresponding tag to access the README that matches your product version

The stable, released version is the [0.9.1 tag](https://github.com/docker/docker-registry/tree/0.9.1).

Please also have a quick look at the [FAQ](FAQ.md) before reporting bugs.

# Table of Contents
- [Quick Start](#quick-start)
- [Configuration mechanism overview](#configuration-mechanism-overview)
- [Configuration flavors](#configuration-flavors)
- [Example config](#example-config)
- [Available configuration options](#available-configuration-options)
- [General options](#general-options)
- [Authentication options](#authentication-options)
- [Search-engine options](#search-engine-options)
- [sqlalchemy](#sqlalchemy)
- [Mirroring Options](#mirroring-options)
- [Cache options](#cache-options)
- [Storage options](#storage-options)
- [storage file](#storage-file)
- [Persistent storage](#persistent-storage)
- [storage s3](#storage-s3)
- [Your own config](#your-own-config)
- [Advanced use](#advanced-user)
- [Drivers](#drivers)
- [For developers](#for-developers)

# Quick start

The fastest way to get running:

* [install docker](https://docs.docker.com/installation/#installation)
* run the registry: `docker run -p 5000:5000 registry`

That will use the [official image from the Docker hub](https://registry.hub.docker.com/_/registry/).

Here is a slightly more complex example that launches a registry on port 5000, using an Amazon S3 bucket to store images with a custom path, and enables the search endpoint:

```
docker run \
-e SETTINGS_FLAVOR=s3 \
-e AWS_BUCKET=mybucket \
-e STORAGE_PATH=/registry \
-e AWS_KEY=myawskey \
-e AWS_SECRET=myawssecret \
-e SEARCH_BACKEND=sqlalchemy \
-p 5000:5000 \
registry
```


# Configuration mechanism overview

By default, the registry will use the [config_sample.yml](config/config_sample.yml) configuration to start.

Individual configuration options from that file may be overridden using environment variables. Example: `docker run -e STORAGE_PATH=/registry`.

You may also use different "flavors" from that file (see below).

Finally, you can use your own configuration file (see below).


# Configuration flavors

The registry can be instructed to use a specific flavor from a configuration file.

This mechanism lets you define different running "mode" (eg: "development", "production" or anything else).

In the `config_sample.yml` file, you'll see several sample flavors:

1. `common`: used by all other flavors as base settings
1. `local`: stores data on the local filesystem
1. `s3`: stores data in an AWS S3 bucket
1. `ceph-s3`: stores data in a Ceph cluster via a Ceph Object Gateway, using the S3 API
1. `azureblob`: stores data in an Microsoft Azure Blob Storage ([(docs)](ADVANCED.md))
1. `dev`: basic configuration using the `local` flavor
1. `test`: used by unit tests
1. `prod`: production configuration (basically a synonym for the `s3` flavor)
1. `gcs`: stores data in Google cloud storage
1. `swift`: stores data in OpenStack Swift
1. `glance`: stores data in OpenStack Glance, with a fallback to local storage
1. `glance-swift`: stores data in OpenStack Glance, with a fallback to Swift
1. `elliptics`: stores data in Elliptics key/value storage

You can define your own flavors by adding a new top-level yaml key.

To specify which flavor you want to run, set the `SETTINGS_FLAVOR`
environment variable: `export SETTINGS_FLAVOR=dev`

The default flavor is `dev`.

NOTE: it's possible to load environment variables from within the config file
with a simple syntax: `_env:VARIABLENAME[:DEFAULT]`. Check this syntax
in action in the example below...


## Example config

```yaml

common: &common
standalone: true
loglevel: info
search_backend: "_env:SEARCH_BACKEND:"
sqlalchemy_index_database:
"_env:SQLALCHEMY_INDEX_DATABASE:sqlite:////tmp/docker-registry.db"

prod:
<<: *common
loglevel: warn
storage: s3
s3_access_key: _env:AWS_S3_ACCESS_KEY
s3_secret_key: _env:AWS_S3_SECRET_KEY
s3_bucket: _env:AWS_S3_BUCKET
boto_bucket: _env:AWS_S3_BUCKET
storage_path: /srv/docker
smtp_host: localhost
from_addr: [e-mail]
to_addr: [e-mail]

dev:
<<: *common
loglevel: debug
storage: local
storage_path: /home/myself/docker

test:
<<: *common
storage: local
storage_path: /tmp/tmpdockertmp
```



# Available configuration options

When using the `config_sample.yml`, you can pass all options through as environment variables. See [`config_sample.yml`](config/config_sample.yml) for the mapping.

## General options

1. `loglevel`: string, level of debugging. Any of python's
[logging](http://docs.python.org/2/library/logging.html) module levels:
`debug`, `info`, `warn`, `error` or `critical`
1. `debug`: boolean, make the `/_ping` endpoint output more useful information, such as library versions and host information.
1. `storage_redirect`: Redirect resource requested if storage engine supports
this, e.g. S3 will redirect signed URLs, this can be used to offload the
server.
1. `boto_host`/`boto_port`: If you are using `storage: s3` the
[standard boto config file locations](http://docs.pythonboto.org/en/latest/boto_config_tut.html#details)
(`/etc/boto.cfg, ~/.boto`) will be used. If you are using a
*non*-Amazon S3-compliant object store (such as Ceph), in one of the boto config files'
`[Credentials]` section, set `boto_host`, `boto_port` as appropriate for the
service you are using. Alternatively, set `boto_host` and `boto_port` in the config file.

## Authentication options

1. `standalone`: boolean, run the server in stand-alone mode. This means that
the Index service on index.docker.io will not be used for anything. This
implies `disable_token_auth`.

1. `index_endpoint`: string, configures the hostname of the Index endpoint.
This is used to verify passwords of users that log in. It defaults to
https://index.docker.io. You should probably leave this to its default.

1. `disable_token_auth`: boolean, disable checking of tokens with the Docker
index. You should provide your own method of authentication (such as Basic
auth).

## Search-engine options

The Docker Registry can optionally index repository information in a
database for the `GET /v1/search` [endpoint][search-endpoint]. You
can configure the backend with a configuration like:

The `search_backend` setting selects the search backend to use. If
`search_backend` is empty, no index is built, and the search endpoint always
returns empty results.

1. `search_backend`: The name of the search backend engine to use.
Currently supported backends are:
1. `sqlalchemy`

If `search_backend` is neither empty nor one of the supported backends, it
should point to a module.

Example:

```yaml
common:
search_backend: foo.registry.index.xapian
```

In this case, the module is imported, and an instance of its `Index`
class is used as the search backend.

### sqlalchemy

Use [SQLAlchemy][] as the search backend.

1. `sqlalchemy_index_database`: The database URL passed through to
[create_engine][].

Example:

```yaml
common:
search_backend: sqlalchemy
sqlalchemy_index_database: sqlite:////tmp/docker-registry.db
```

On initialization, the `SQLAlchemyIndex` class checks the database
version. If the database doesn't exist yet (or does exist, but lacks
a `version` table), the `SQLAlchemyIndex` creates the database and
required tables.

## Mirroring Options

All mirror options are placed in a `mirroring` section.

1. `mirroring`:
1. `source`:
1. `source_index`:
1. `tags_cache_ttl`:

Example:

```yaml
common:
mirroring:
source: https://registry-1.docker.io
source_index: https://index.docker.io
tags_cache_ttl: 172800 # 2 days
```

## Cache options

It's possible to add an LRU cache to access small files. In this case you need
to spawn a [redis-server](http://redis.io/) configured in
[LRU mode](http://redis.io/topics/config). The config file "config_sample.yml"
shows an example to enable the LRU cache using the config directive `cache_lru`.

Once this feature is enabled, all small files (tags, meta-data) will be cached
in Redis. When using a remote storage backend (like Amazon S3), it will speed
things up dramatically since it will reduce roundtrips to S3.

All config settings are placed in a `cache` or `cache_lru` section.

1. `cache`/`cache_lru`:
1. `host`: Host address of server
1. `port`: Port server listens on
1. `password`: Authentication password



## Storage options

`storage` selects the storage engine to use. The registry ships with two storage engine by default (`file` and `s3`).

If you want to find other (community provided) storages: `pip search docker-registry-driver`

To use and install one of these alternate storages:

* `pip install docker-registry-driver-NAME`
* in the configuration set `storage` to `NAME`
* add any other storage dependent configuration option to the conf file
* review the storage specific documentation for additional dependency or configuration instructions.

Currently, we are aware of the following storage drivers:

* [azure](https://github.com/ahmetalpbalkan/docker-registry-driver-azure)
* [elliptics](https://github.com/noxiouz/docker-registry-driver-elliptics)
* [swift](https://github.com/bacongobbler/docker-registry-driver-swift)
* [gcs](https://github.com/dmp42/docker-registry-driver-gcs)
* [glance](https://github.com/dmp42/docker-registry-driver-glance)
* [oss](https://github.com/chris-jin/docker-registry-driver-alioss.git)

### storage file

1. `storage_path`: Path on the filesystem where to store data

Example:

```yaml
local:
storage: file
storage_path: /mnt/registry
```

#### Persistent storage
If you use any type of local store along with a registry running within a docker
remember to use a data volume for the `storage_path`. Please read the documentation
for [data volumes](http://docs.docker.io/en/latest/use/working_with_volumes/) for more information.

Example:

```
docker run -p 5000 -v /tmp/registry:/tmp/registry registry
```

### storage s3
AWS Simple Storage Service options

1. `s3_access_key`: string, S3 access key
1. `s3_secret_key`: string, S3 secret key
1. `s3_bucket`: string, S3 bucket name
1. `s3_region`: S3 region where the bucket is located
1. `s3_encrypt`: boolean, if true, the container will be encrypted on the
server-side by S3 and will be stored in an encrypted form while at rest
in S3.
1. `s3_secure`: boolean, true for HTTPS to S3
1. `s3_use_sigv4`: boolean, true for USE_SIGV4 (boto_host needs to be set or use_sigv4 will be ignored by boto.)
1. `boto_bucket`: string, the bucket name for *non*-Amazon S3-compliant object store
1. `boto_host`: string, host for *non*-Amazon S3-compliant object store
1. `boto_port`: for *non*-Amazon S3-compliant object store
1. `boto_debug`: for *non*-Amazon S3-compliant object store
1. `boto_calling_format`: string, the fully qualified class name of the boto calling format to use when accessing S3 or a *non*-Amazon S3-compliant object store
1. `storage_path`: string, the sub "folder" where image data will be stored.

Example:
```yaml
prod:
storage: s3
s3_region: us-west-1
s3_bucket: acme-docker
storage_path: /registry
s3_access_key: AKIAHSHB43HS3J92MXZ
s3_secret_key: xdDowwlK7TJajV1Y7EoOZrmuPEJlHYcNP2k4j49T
```

# Your own config

Start from a copy of [config_sample.yml](config/config_sample.yml).

Then, start your registry with a mount point to expose your new configuration inside the container (`-v /home/me/myfolder:/registry-conf`), and point to it using the `DOCKER_REGISTRY_CONFIG` environment variable:

```
sudo docker run -p 5000:5000 -v /home/me/myfolder:/registry-conf -e DOCKER_REGISTRY_CONFIG=/registry-conf/mysuperconfig.yml registry
```

# Advanced use

For more features and advanced options, have a look at the [advanced features documentation](ADVANCED.md)

# Drivers

For more backend drivers, please read [drivers.md](DRIVERS.md)

# For developers

Read [contributing](CONTRIBUTING.md)

[search-endpoint]: http://docs.docker.com/reference/api/docker-io_api/#search
[SQLAlchemy]: http://docs.sqlalchemy.org/
[create_engine]: http://docs.sqlalchemy.org/en/latest/core/engines.html#sqlalchemy.create_engine