Skip to content

Latest commit

 

History

History
314 lines (219 loc) · 9.5 KB

ADVANCED.md

File metadata and controls

314 lines (219 loc) · 9.5 KB
Raw

Docker-Registry advanced use

"extras"

The registry supports additional features (that require additional dependencies) that you may require at install time.

Installation

If you are using the official registry container, you don't need to do anything, as all extras are installed by default.

If you are using pip, you have to explicitly request the extra you want, using pip extra syntax:

pip install docker-registry[someextra]

You can request several different extras at the same time by specifying a coma separated list, eg:

pip install docker-registry[someextra,anotherextra]

Available "extras"

"bugsnag"

This enables bugsnag reporter in your registry.

  1. bugsnag: your bugsnag API key

Note the bugsnag "stage" will be set to the specified configuration "flavor".

"newrelic"

This encapsulates your registry inside the new-relic agent.

You need to write a new-relic ini file, then use the following environment variables:

  • NEW_RELIC_INI to point to your ini file
  • NEW_RELIC_STAGE to specify what stage you want

"cors"

To enable CORS support on your registry, you need to specify at least the cors.origins key in your config.

The complete list of what you can configure is as follow:

    cors:
        origins: _env:CORS_ORIGINS
        methods: _env:CORS_METHODS
        headers: _env:CORS_HEADERS:[Content-Type]
        expose_headers: _env:CORS_EXPOSE_HEADERS
        supports_credentials: _env:CORS_SUPPORTS_CREDENTIALS
        max_age: _env:CORS_MAX_AGE
        send_wildcard: _env:CORS_SEND_WILDCARD
        always_send: _env:CORS_ALWAYS_SEND
        automatic_options: _env:CORS_AUTOMATIC_OPTIONS
        vary_header: _env:CORS_VARY_HEADER
        resources: _env:CORS_RESOURCES

Note that:

  • the official, docker-operated registry doesn't enable CORS
  • if you enable CORS, it will be available on all endpoints
  • you should be careful with CORS as it presents numerous security pitfalls for you and your users in case of misuse/misconfiguration

Proxying

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

This is especially useful if you want to run standalone and implement your own authentication mechanism.

nginx

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):

Apache

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/

High Availability and Scaling

It is possible to run multiple containers against the same storage back-end for performance and availability reasons.

Here is an example using a shared s3 storage back-end, Redis cache and MySQL search database (all should be common across containers for consistency)

docker run \
         -e SETTINGS_FLAVOR=s3 \
         -e AWS_BUCKET=mybucket \
         -e AWS_KEY=myawskey \
         -e AWS_SECRET=myawssecret \
         -e CACHE_REDIS_HOST=redis.host \
         -e CACHE_REDIS_PORT=6379 \
         -e CACHE_REDIS_DB=1 \
         -e CACHE_LRU_REDIS_HOST=redis.host \
         -e CACHE_LRU_REDIS_PORT=6379 \
         -e CACHE_LRU_REDIS_DB=0 \
         -e AWS_REGION=us-east-1 \
         -e SEARCH_BACKEND=sqlalchemy \
         -e SQLALCHEMY_INDEX_DATABASE=mysql://user:[email protected]/db_name
         -p 5000:5000 \
         registry

note: Depending on your version of Docker you may need to add the appropriate python mysql drivers to the container

Alternative uses

If you don't want to run the registry inside a docker container, you may do so by running it directly, as follow:

Ubuntu

Install the system requirements:

sudo apt-get install python-dev libevent-dev python-pip liblzma-dev swig libssl-dev

Then install the Registry app:

sudo pip install docker-registry

If you need extra requirements (see above), specify them:

sudo pip install docker-registry[bugsnag,newrelic,cors]

Alternatively, you may clone the github repository and run pip install .

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 repositories enabled. Fedora should not require the additional repositories.

Then install the Registry app:

sudo python-pip install docker-registry[bugsnag,newrelic,cors]

Alternatively, you may clone the github repository and run pip install .

Run it

docker-registry

Advanced start options (NOT recommended)

If you want greater control over gunicorn:

gunicorn -c contrib/gunicorn_config.py docker_registry.wsgi:application

or even bare

gunicorn --access-logfile - --error-logfile - -k gevent -b 0.0.0.0:5000 -w 4 --max-requests 100 docker_registry.wsgi:application

non-Amazon S3-compliant object stores (e.g. Ceph and Riak CS)

Example:

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 \
         -e AWS_HOST=myowns3.com \
         -e AWS_SECURE=false \
         -e AWS_ENCRYPT=false \
         -e AWS_PORT=80 \
         -e AWS_DEBUG=true \
         -e AWS_CALLING_FORMAT=boto.s3.connection.OrdinaryCallingFormat \
         -p 5000:5000 \
         registry

S3 Storage with Cloudfront

It is possible Cloudfront in tandem with S3 storage, you need to configure Cloudfront to point it to your S3 bucket.

This flavor can be started as:

docker run \
        -e SETTINGS_FLAVOR=cloudfronts3 \
        -e STORAGE_REDIRECT=true \
        -e AWS_BUCKET=mybucket \
        -e STORAGE_PATH=/registry \
        -e AWS_KEY=myawskey \
        -e AWS_SECRET=myawssecret \
        -e SEARCH_BACKEND=sqlalchemy \
        -e AWS_SECURE=false \
        -e AWS_ENCRYPT=false \
        -e AWS_PORT=80 \
        -e AWS_DEBUG=true \
        -e CF_BASE_URL=cloudfront_url
        -e CF_KEYID=cloudfront_key_id
        -e CF_KEYSECRET=cloudfront_private_key
        -p 5000:5000 \
        registry

CF_BASE_URL is the Cloudfront base URL example: https://abcd.cloudfront.net CF_KEYID is the ID of the Cloudfront keypair you are going to use to sign the URLs so the the registry can 302 to Cloudfront. CF_KEYSECRET is either the private key as string or file location of the private key used to sign the URLS.

Microsoft Azure Blob Storage

In order to use Microsoft Azure Blob Storage Service, you need to create a storage account from Azure Management Portal or other management scripts.

In the configuration use azureblob flavor.

  1. azure_storage_account_name: string, storage account name
  2. azure_storage_account_key: string, storage account key
  3. azure_storage_container: string, container name to be used or created
  4. azure_use_https: boolean, (default:true) use HTTPS for communication

Example configuration:

prod:
  storage: azureblob
  azure_storage_account_name: contoso
  azure_storage_account_key: Fb8cgp___YOUR_KEY___/o8isRdsuHqrHF==
  azure_storage_container: registry
  azure_use_https: true

Advanced configuration options

Privileged access

It's possible to allow privileged access to your registry using an RSA key (useful for administration scripts for example).

To do so, specify in your config:

  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.

To generate said key using 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

Email exceptions

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

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

Example:

test:
    email_exceptions:
        smtp_host: localhost