> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/setup/docker.md).

# Docker

Docker - push container images to Harness Artifacts

Use a **Docker** registry to host private container images. The registry works with the Docker CLI.

## What you will learn from this topic

By the end of this guide, you will know how to:

* Create a registry in Harness Artifacts.
* Publish an image to the registry.
* Pull the image from the registry, and confirm that it works.

## Before you begin

* Install the Docker CLI (`docker`) on your local machine.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a Docker Registry

To create a Docker Registry:

1. In Artifact Registry, select **Registries**.
2. Click **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**Registry name criteria**

The registry name must start with a letter, can only contain lowercase alphanumerics, `_`, `.`, and `-`, and must be unique to your Harness account.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Docker** as the **Registry type**.
7. Click **Save**.
8. Select **Create** to finalize.

## Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch Docker images from external container registries when they are not available locally.

### Create upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Click the drop-down next to **+ Create Registry** and select **Upstream Proxy**.
3. Specify the **Registry name**.
4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Docker** as the **Registry type**.
7. Select the **Source**:
   * **Docker Hub**: No remote registry URL required.
   * **AWS ECR**: Specify the **Remote registry URL**.
   * **Custom**: Specify the **Remote registry URL**.
8. Select the **Authentication method**:
   * **Docker Hub**:
     * **Username and password**: Specify the username and password. Use an existing secret, or create a new secret by specifying the **Name** and entering the **Secret text**.
     * **Anonymous**: No credentials required. This works for public Docker Hub images.
   * **AWS ECR**:
     * **Access key**: Specify the access key as plain text or as an encrypted secret, then specify the secret key by creating a new secret or selecting an existing one.
     * **Anonymous**: No credentials required. This works for public ECR repositories.
   * **Custom**:
     * **Username and password**: Specify the username and password. Use an existing secret, or create a new secret by specifying the **Name** and entering the **Secret text**.
     * **Anonymous**: No credentials required. This works for registries that need no authentication.
9. Select **Create** to finalize.

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

1. In Artifact Registry, select an existing Docker artifact.
2. Navigate to the **Configuration** tab.
3. Select **Edit** in the **Upstream proxy** section.
4. Click **+ Add upstream proxy**.
5. Select the required proxy from the list.
6. Select **Apply**.
7. Click **Update** to finalize.

{% hint style="info" %}
**Upstream proxy caching**

If an image is not found in your Harness registry, the upstream proxy fetches it from the remote registry and caches it.
{% endhint %}

## Docker client setup

In your Harness Docker Artifact, select **Setup Client**. The dialog gives you an identity token, then setup instructions for logging in, publishing, and pulling images with the Docker CLI.

### Generate an identity token

An identity token serves as the password for authenticating with the registry.

1. In your Docker Artifact, select **Setup Client**.
2. Select **Generate Token**.
3. Select an **Expiration** for the token:
   * **30 Days**
   * **90 Days**
   * **180 Days**
   * **Custom**
4. Copy the token. You use it in the following steps in place of `<IDENTITY_TOKEN>`.

{% hint style="info" %}
**Token expiration**

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.
{% endhint %}

### Configure the client

Replace the values in angle brackets with your own values.

**1. Configure**

Run the following command in your terminal to authenticate the Docker CLI with the registry:

```bash
docker login pkg.harness.io
```

At the prompts, enter the following:

* **Username**: your Harness account email address.
* **Password**: `<IDENTITY_TOKEN>`.

**2. Publish an image**

Tag the image to match the registry path, then push it:

```bash
docker tag <IMAGE_NAME>:<TAG> pkg.harness.io/<ACCOUNT_ID>/<REGISTRY_NAME>/<IMAGE_NAME>:<TAG>
docker push pkg.harness.io/<ACCOUNT_ID>/<REGISTRY_NAME>/<IMAGE_NAME>:<TAG>
```

**3. Use the image**

Make sure you are authenticated with the registry (see step 1), then pull the image by tag or by digest:

```bash
docker pull pkg.harness.io/<ACCOUNT_ID>/<REGISTRY_NAME>/<IMAGE_NAME>:<TAG>
docker pull pkg.harness.io/<ACCOUNT_ID>/<REGISTRY_NAME>/<IMAGE_NAME>@<DIGEST>
```

## Setup verification

Confirm that your registry serves the image you published. To verify your setup:

1. On a host with no locally cached layers for the image you pushed, pull the image using the client command from the earlier steps.
2. Confirm that the client pulled the image from your Harness registry address, which is shown in **Setup Client**.
3. In Harness, open your registry and confirm that the image and tag appear in the artifact list.

If a step fails, go to [Troubleshooting](#troubleshooting) to resolve common authentication and resolution issues before you retry.

## Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one image tag in the registry.

The following Run step shows the shape of a publish step. Replace `<ACCOUNT_ID>`, `<REGISTRY_NAME>`, and `<IMAGE_NAME>` with the values from the earlier steps. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

```yaml
- step:
    type: Run
    name: Publish image
    identifier: publish_image
    spec:
      shell: Sh
      envVariables:
        IMAGE_TAG: <+codebase.tag>
      command: |
        docker tag <IMAGE_NAME>:latest pkg.harness.io/<ACCOUNT_ID>/<REGISTRY_NAME>/<IMAGE_NAME>:"$IMAGE_TAG"
        docker push pkg.harness.io/<ACCOUNT_ID>/<REGISTRY_NAME>/<IMAGE_NAME>:"$IMAGE_TAG"
```

## Troubleshooting

<details>

<summary>`docker login` fails with `401 Unauthorized` or `403 Forbidden`</summary>

Check that you entered your Harness account email address as the username, and the identity token, not your account password, as the password. If the token expired or was revoked, generate a new one and log in again.

</details>

<details>

<summary>`docker push` fails with `DENIED: requested access to the resource is denied` for an existing tag</summary>

Harness Artifacts enforces tag immutability for existing versions, depending on your registry configuration. Push a new tag, or delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>`docker pull` fails with `manifest unknown` or `not found`</summary>

Check that the image name, tag or digest, and registry name in your pull command match the values you used when you pushed the image.

</details>

<details>

<summary>`docker pull` returns a cached image after a new push to the same tag</summary>

Docker caches image layers locally by tag. Remove the stale local image with `docker rmi`, or pull by digest instead of tag to always resolve the exact image you published.

</details>

<details>

<summary>Setup Client does not show a push command for an upstream proxy registry</summary>

An upstream proxy registry is pull-only. To push images, create a local registry of the same format and push to that instead. Go to [Create a registry](https://developer.harness.io/artifact-registry/3.0/registries/create-a-registry.md) to set one up.

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
