# Proxy Repository for Docker

To reduce duplicate downloads and improve download speeds for your developers and CI servers, you should proxy any registry you use for Docker images.

## Basic Steps to Proxy a Docker Registry

To proxy a Docker registry, you simply create a new _docker (proxy)_ as documented in [Repository Management](https://help.sonatype.com/en/repository-management.html "Repository Management").  
Minimal configuration steps are as follows:

1. Define a _Name_  
2. Define a URL of the remote registry you want to proxy for _Remote__Storage_  
3. Enable _Docker V1 API_ support if required by the remote repository  
4. Select the correct _Docker index_  
5. Further configure _Location of Docker__index_ if needed  
6. Select _Blob store_ for Storage

### Create a Proxy for Docker Hub

Docker Hub is the most common registry used by all image creators and consumers.

In order to configure a proxy for Docker Hub, you create a new _docker (proxy)_ as documented in [Repository Management](https://help.sonatype.com/en/repository-management.html "Repository Management") and make the following configurations:

1. Define a _Name_  
2. Define the URL for _Remote Storage_ as "`https://registry-1.docker.io`"  
3. Enable _Docker V1 API_ support  
4. For the _Docker__index_, select _Use Docker Hub_  
5. Select _Blob store_ for storage

### Create a Proxy for Amazon Elastic Container Registry (ECR)

Amazon Elastic Container Registry (ECR) is a managed container registry service from AWS. Nexus Repository can proxy ECR registries to cache container images and reduce data transfer costs.

Nexus Repository 3.95 and later supports both long-lived AWS IAM access keys and short-lived AWS Security Token Service (STS) credentials for authenticating to ECR.

#### Prerequisites
- An AWS account with access to ECR  
- Valid AWS IAM credentials  
- The 12-digit AWS account ID (Registry ID) for the ECR registry

**Choose an AWS Credential Type**

| Credential Type                  | Access Key ID | Required Credential Fields                              | Expiration                                                                                     |
|-----------------------------------|----------------|--------------------------------------------------------|------------------------------------------------------------------------------------------------|
| Long lived IAM credentials         | Starts with `AKIA` | Access key ID and secret access key                  | Does not have an STS session expiration. Rotate the credentials according to your organization's security policy. |
| Short-lived STS credentials        | Starts with `ASIA` | Access key ID, secret access key, and session token   | Expires when the underlying AWS STS session expires. You must update the repository with fresh credentials before or after expiration. |

To create a new ECR proxy repository, take the following steps:

1. Select _Settings_→ _Repository_→ _Repositories_.  
2. Select the _Create repository_ button.  
3. From the list of Recipes, select _docker (proxy)_.  
4. In the form that appears, complete the required fields.  
   - Repository Name, for example _docker-ecr-proxy_  
   - Enter the remote storage URL, for example, `https://<account-id>.dkr.ecr.<region>.amazonaws.com`. Depending on the registry endpoint, the URL might not include `dkr`.
   - Blob store for self hosted deployments

5. Under _HTTP_ section, select the _Authentication_ check box and set _Authentication type_ to `Username`.
6. Enter the AWS credentials  
   - **Username**: AWS ECR Access Key  
   - **Password**: AWS ECR Secret Access Key

7. Under AWS ECR Authentication, configure AWS Session Token  
   - For short-lived STS credentials, enter the session token associated with the access key ID and secret access key.  
   - For long-lived IAM credentials, leave AWS Session Token blank.

8. Complete the additional fields for configurations you wish to add for creating your repository. Available configurations differ by repository format and type. See Configurable Repository Fields for more details.
9. Select _Create repository_.

Nexus Repository validates the AWS credentials when you create or update the repository. When a client first requests an image, Nexus Repository uses the configured AWS credentials to request an ECR authorization token.

**Note**

Nexus Repository cannot renew an AWS STS session token. It can refresh the ECR authorization token only while the configured AWS credentials remain valid. After the STS credentials expire, a cached ECR authorization token may continue to work until Nexus Repository must refresh it. Subsequent image pulls fail until you update the repository with valid AWS credentials.

When you pull the images using AWS CLI through Nexus docker repository, Nexus Repository caches the 12-hour ECR token on the first pull. Nexus Repository reuses the cached token for every subsequent pull and refreshes the authorization token every six hours though the `ECR Token Refresh` task.

#### ECR Token Refresh Task

The `ECR Token Refresh` task is active by default and does not require manual intervention. The task refreshes the ECR authorization token. It does not renew or replace the AWS access key, secret access key, or STS session token configured on the repository. If you wish to edit the task, take the following steps:

1. Select _Settings_→ _System_ → _Tasks_ → _ECR Token Refresh_.  
2. Select _Settings_.  
3. Edit only the fields you wish to change.  
   - To send email notifications, enter your email address in the _Notification email_ field.  
   - To force refresh, select the _Force refresh_ checkbox. It evicts the cached ECR token by ignoring the 6-hour expiry horizon. Select this checkbox only if you want to change your credentials immediately.  
   - To schedule the task at your own pace, edit the _Task frequency_ and _CRON expression_ fields.

4. Select _Save_.  
5. If you wish to run the task immediately, select _Run_.

#### Rotate Short-Lived AWS Credentials

Take the following steps to rotate short-lived credentials before their STS session expires whenever possible:

1. Select _Settings_ → _Repository_ → _Repositories_.  
2. Select your Docker proxy repository that connects to ECR.  
3. Under _HTTP Authentication type_, update the _username_ and _password_ values if they were rotated.  
4. Under _AWS ECR Authentication_, enter the new AWS Session Token.  
5. Select _Save_.

## Configuring a Correct Remote Storage and Docker Index URL Pair

It is important to configure a correct pair of Remote Storage URL and Docker Index URL. If there is a mismatch, search results potentially will not reflect the remote repository's content, and other problems can occur.

The proxy configuration for a Docker proxy repository includes a configuration URL to access the _Docker Index_. The index is used for requests related to searches, users, Docker tokens and other aspects.

The same provider typically co-hosts the registry and the index; however, they can use different URLs. For example, the index for Docker Hub is exposed at `https://index.docker.io/`. By selecting the default option of _Use proxy registry (specified above)_, Nexus Repository will attempt to retrieve any index data from the same URL configured as the _Remote Storage_URL.

The option to _Use Docker Hub_ fulfills any index-related requests by querying the Docker Hub index at `https://index.docker.io/`. This configuration is desired when the proxy repository is Docker Hub itself or any of its mirrors.

The option to use a _Custom index_ allows you to specify the URL of the index for the remote repository.