Package: docker-registry
> **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===============[![Build Status](https://travis-ci.org/docker/docker-registry.png)](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 versionThe 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 startThe 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 overviewBy 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 flavorsThe 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 settings1. `local`: stores data on the local filesystem1. `s3`: stores data in an AWS S3 bucket1. `ceph-s3`: stores data in a Ceph cluster via a Ceph Object Gateway, using the S3 API1. `azureblob`: stores data in an Microsoft Azure Blob Storage ([(docs)](ADVANCED.md))1. `dev`: basic configuration using the `local` flavor1. `test`: used by unit tests1. `prod`: production configuration (basically a synonym for the `s3` flavor)1. `gcs`: stores data in Google cloud storage1. `swift`: stores data in OpenStack Swift1. `glance`: stores data in OpenStack Glance, with a fallback to local storage1. `glance-swift`: stores data in OpenStack Glance, with a fallback to Swift1. `elliptics`: stores data in Elliptics key/value storageYou 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 filewith a simple syntax: `_env:VARIABLENAME[:DEFAULT]`. Check this syntaxin action in the example below...## Example config```yamlcommon: &commonstandalone: trueloglevel: infosearch_backend: "_env:SEARCH_BACKEND:"sqlalchemy_index_database:"_env:SQLALCHEMY_INDEX_DATABASE:sqlite:////tmp/docker-registry.db"prod:<<: *commonloglevel: warnstorage: s3s3_access_key: _env:AWS_S3_ACCESS_KEYs3_secret_key: _env:AWS_S3_SECRET_KEYs3_bucket: _env:AWS_S3_BUCKETboto_bucket: _env:AWS_S3_BUCKETstorage_path: /srv/dockersmtp_host: localhostfrom_addr: docker@myself.comto_addr: my@myself.comdev:<<: *commonloglevel: debugstorage: localstorage_path: /home/myself/dockertest:<<: *commonstorage: localstorage_path: /tmp/tmpdockertmp```# Available configuration optionsWhen 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 options1. `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 supportsthis, e.g. S3 will redirect signed URLs, this can be used to offload theserver.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 theservice you are using. Alternatively, set `boto_host` and `boto_port` in the config file.## Authentication options1. `standalone`: boolean, run the server in stand-alone mode. This means thatthe Index service on index.docker.io will not be used for anything. Thisimplies `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 tohttps://index.docker.io. You should probably leave this to its default.1. `disable_token_auth`: boolean, disable checking of tokens with the Dockerindex. You should provide your own method of authentication (such as Basicauth).## Search-engine optionsThe Docker Registry can optionally index repository information in adatabase for the `GET /v1/search` [endpoint][search-endpoint].  Youcan 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 alwaysreturns 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, itshould point to a module.Example:```yamlcommon: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.### sqlalchemyUse [SQLAlchemy][] as the search backend.1. `sqlalchemy_index_database`: The database URL passed through to[create_engine][].Example:```yamlcommon:search_backend: sqlalchemysqlalchemy_index_database: sqlite:////tmp/docker-registry.db```On initialization, the `SQLAlchemyIndex` class checks the databaseversion.  If the database doesn't exist yet (or does exist, but lacksa `version` table), the `SQLAlchemyIndex` creates the database andrequired tables.## Mirroring OptionsAll mirror options are placed in a `mirroring` section.1. `mirroring`:1. `source`:1. `source_index`:1. `tags_cache_ttl`:Example:```yamlcommon:mirroring:source: https://registry-1.docker.iosource_index: https://index.docker.iotags_cache_ttl: 172800 # 2 days```## Cache optionsIt's possible to add an LRU cache to access small files. In this case you needto 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 cachedin Redis. When using a remote storage backend (like Amazon S3), it will speedthings 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 server1. `port`: Port server listens on1. `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 file1. `storage_path`: Path on the filesystem where to store dataExample:```yamllocal:storage: filestorage_path: /mnt/registry```#### Persistent storageIf you use any type of local store along with a registry running within a dockerremember to use a data volume for the `storage_path`. Please read the documentationfor [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 s3AWS Simple Storage Service options1. `s3_access_key`: string, S3 access key1. `s3_secret_key`: string, S3 secret key1. `s3_bucket`: string, S3 bucket name1. `s3_region`: S3 region where the bucket is located1. `s3_encrypt`: boolean, if true, the container will be encrypted on theserver-side by S3 and will be stored in an encrypted form while at restin S3.1. `s3_secure`: boolean, true for HTTPS to S31. `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 store1. `boto_host`: string, host for *non*-Amazon S3-compliant object store1. `boto_port`: for *non*-Amazon S3-compliant object store1. `boto_debug`: for *non*-Amazon S3-compliant object store1. `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 store1. `storage_path`: string, the sub "folder" where image data will be stored.Example:```yamlprod:storage: s3s3_region: us-west-1s3_bucket: acme-dockerstorage_path: /registrys3_access_key: AKIAHSHB43HS3J92MXZs3_secret_key: xdDowwlK7TJajV1Y7EoOZrmuPEJlHYcNP2k4j49T```# Your own configStart 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 useFor more features and advanced options, have a look at the [advanced features documentation](ADVANCED.md)# DriversFor more backend drivers, please read [drivers.md](DRIVERS.md)# For developersRead [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