Public | Automated Build

Last pushed: 3 years ago
Short Description
Short description is empty for this repo.
Full Description


About this document

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

  • 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 currently the 0.7.3 tag.

Quick start

The fastest way to get running:

That will use the
official image from the Docker index.

Here is another example that will launch a container on port 5000, and store images in an Amazon S3 bucket:

docker run \
         -e SETTINGS_FLAVOR=s3 \
         -e AWS_BUCKET=acme-docker \
         -e STORAGE_PATH=/registry \
         -e AWS_KEY=AKIAHSHB43HS3J92MXZ \
         -e AWS_SECRET=xdDowwlK7TJajV1Y7EoOZrmuPEJlHYcNP2k4j49T \
         -e SEARCH_BACKEND=sqlalchemy \
         -p 5000:5000 \

See config_sample.yml for all available environment variables.

Create the configuration

The Docker Registry comes with a sample configuration file,
config_sample.yml. Copy this to config.yml to provide a basic

cp config/config_sample.yml config/config.yml

Configuration flavors

Docker Registry can run in several flavors. This enables you to run it
in development mode, production mode or your own predefined mode.

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

  1. common: used by all other flavors as base settings
  2. local: stores data on the local filesystem
  3. s3: stores data in an AWS S3 bucket
  4. dev: basic configuration using the local flavor
  5. test: used by unit tests
  6. prod: production configuration (basically a synonym for the s3 flavor)
  7. gcs: stores data in Google cloud storage
  8. swift: stores data in OpenStack Swift
  9. glance: stores data in OpenStack Glance, with a fallback to local storage
  10. glance-swift: stores data in OpenStack Glance, with a fallback to Swift
  11. elliptics: stores data in Elliptics key/value storage

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

You can specify which flavor to run by setting SETTINGS_FLAVOR in your
environment: export SETTINGS_FLAVOR=dev

The default flavor is dev.

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

Example config

    loglevel: info
    search_backend: "_env:SEARCH_BACKEND:"

    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

    loglevel: debug
    storage: local
    storage_path: /home/myself/docker

    storage: local
    storage_path: /tmp/tmpdockertmp

Location of the config file


Specify the config file to be used by setting DOCKER_REGISTRY_CONFIG in your
environment: export DOCKER_REGISTRY_CONFIG=config.yml

The default location of the config file is config.yml, located in
the config subdirectory. If DOCKER_REGISTRY_CONFIG is a relative
path, that path is expanded relative to the config subdirectory.

Docker image

When building an image using the Dockerfile or using an image from the
Docker index, the default config is

It is also possible to mount the configuration file into the docker image

sudo docker run -p 5000:5000 -v /home/user/registry-conf:/registry-conf -e DOCKER_REGISTRY_CONFIG=/registry-conf/config.yml registry

Available configuration options

When using the config_sample.yml, you can pass all options through as environment variables. See config_sample.yml for the mapping.

General options

  1. loglevel: string, level of debugging. Any of python's
    logging module levels:
    debug, info, warn, error or critical
  2. storage_redirect: Redirect resource requested if storage engine supports
    this, e.g. S3 will redirect signed URLs, this can be used to offload the
  3. boto_host/boto_port: If you are using storage: s3 the
    standard boto config file locations
    (/etc/boto.cfg, ~/.boto) will be used. If you are using a
    non-Amazon S3-compliant object store, in one of the boto config files'
    [Credentials] section, set boto_host, boto_port as appropriate for the
    service you are using.
  4. bugsnag: The bugsnag API key (note that if you don't use the official docker container, you need to install the registry with bugsnag enabled: pip install docker-registry[bugsnag])

Authentication options

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

  2. index_endpoint: string, configures the hostname of the Index endpoint.
    This is used to verify passwords of users that log in. It defaults to You should probably leave this to its default.

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

Privileged access

  1. privileged_key: allows you to make direct requests to the registry by using
    an RSA key pair. The value is the path to a file containing the public key.
    If it is not set, privileged access is disabled.
Generating keys with openssl

You will need to install the python-rsa package (pip install rsa) in addition to using openssl.
Generating the public key using openssl will lead to producing a key in a format not supported by
the RSA library the registry is using.

Generate private key:

openssl genrsa  -out private.pem 2048

Associated public key :

pyrsa-priv2pub -i private.pem -o public.pem

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.


  search_backend: foo.registry.index.xapian


  1. sqlalchemy_index_database: The database URL


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

In this case, the module is imported, and an instance of it's Index
class is used as the search backend.

Mirroring Options

All mirror options are placed in a mirroring section.

  1. mirroring:
    1. source:
    2. source_index:
    3. tags_cache_ttl:


    tags_cache_ttl: 864000 # 10 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 configured in
LRU mode. 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 speeds
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
    2. port: Port server listens on
    3. password: Authentication password

Email options

Settings these options makes the Registry send an email on each code Exception:

  1. email_exceptions:
    1. smtp_host: hostname to connect to using SMTP
    2. smtp_port: port number to connect to using SMTP
    3. smtp_login: username to use when connecting to authenticated SMTP
    4. smtp_password: password to use when connecting to authenticated SMTP
    5. smtp_secure: boolean, true for TLS to using SMTP. this could be a path
                to the TLS key file for client authentication.
    6. from_addr: email address to use when sending email
    7. to_addr: email address to send exceptions to


        smtp_host: localhost

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 configuraiton option to the conf file
  • review the storage specific documentation for additional dependency or configuration instructions.

    Currently, we are aware of the following storage driver:

storage: file

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


  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 for more information.


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
  2. s3_secret_key: string, S3 secret key
  3. s3_bucket: string, S3 bucket name
  4. s3_region: S3 region where the bucket is located
  5. 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.
  6. s3_secure: boolean, true for HTTPS to S3
  7. boto_bucket: string, the bucket name
  8. storage_path: string, the sub "folder" where image data will be stored.


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

Run the Registry

Recommended: run the registry docker container


docker run \
         -e SETTINGS_FLAVOR=s3 \
         -e AWS_BUCKET=acme-docker \
         -e STORAGE_PATH=/registry \
         -e AWS_KEY=AKIAHSHB43HS3J92MXZ \
         -e AWS_SECRET=xdDowwlK7TJajV1Y7EoOZrmuPEJlHYcNP2k4j49T \
         -e SEARCH_BACKEND=sqlalchemy \
         -p 5000:5000 \

NOTE: The container will try to allocate the port 5000. If the port
is already taken, find out which container is already using it by running docker ps

Advanced: install the registry on an existing server

On Ubuntu

Install the system requirements for building a Python library:

sudo apt-get install build-essential python-dev libevent-dev python-pip liblzma-dev

Then install the Registry app:

sudo pip install docker-registry

If you need extra requirements, like bugsnag, specify them:

sudo pip install docker-registry[bugsnag]

(or clone the repository and pip install .)

On Red Hat-based systems:

Install the required dependencies:

sudo yum install python-devel libevent-devel python-pip gcc xz-devel

NOTE: On RHEL and CentOS you will need the
EPEL repostitories enabled. Fedora
should not require the additional repositories.

Then install the Registry app:

sudo python-pip install docker-registry[bugsnag]

(or clone the repository and pip install .)

Run it

gunicorn --access-logfile - --debug -k gevent -b -w 1 docker_registry.wsgi:application

How do I setup user accounts?

The first time someone tries to push to your registry, it will prompt
them for a username, password, and email.

What about a Production environment?

The recommended setting to run the Registry in a prod environment is gunicorn
behind a nginx server which supports chunked transfer-encoding (nginx >= 1.3.9).

You could use for instance supervisord to spawn the registry with 8 workers
using this command:

gunicorn -k gevent --max-requests 100 --graceful-timeout 3600 -t 3600 -b localhost:5000 -w 8 docker_registry.wsgi:application


Here is an nginx configuration file example., which applies to versions < 1.3.9 which are compiled with the HttpChunkinModule.

This is another example nginx configuration file that applies to versions of nginx greater than 1.3.9 that have support for the chunked_transfer_encoding directive.

And you might want to add
Basic auth on Nginx to protect it
(if you're not using it on your local network):


Enable mod_proxy using a2enmod proxy_http, then use this snippet forward
requests to the Docker Registry:

  ProxyPreserveHost  On
  ProxyRequests      Off
  ProxyPass          /  http://localhost:5000/
  ProxyPassReverse   /  http://localhost:5000/


The central Registry runs on the dotCloud platform:

cd docker-registry/
dotcloud create myregistry
dotcloud push

For developers


Docker Pull Command
Source Repository