---
url: /en/artifact/docker.md
---
## Login to CNB Docker Artifact Registry

You can use CNB access token as login credentials. For how to get `CNB_TOKEN`, please refer to [Creating an Access Token](./intro.md#creating-an-access-token). Login command:

```bash
docker login docker.cnb.share.ralphlauren.cn -u cnb -p <YOUR_TOKEN>
```

## Docker Artifact Path Rules

When publishing artifacts to a repository, two naming rules are supported:

1. Same-name artifacts - Artifact path matches repository path, e.g.: `docker.cnb.share.ralphlauren.cn/${CNB_REPO_SLUG_LOWERCASE}`
2. Different-name artifacts - Repository path serves as namespace for artifacts, artifact path = repository path/artifact name, e.g.: `docker.cnb.share.ralphlauren.cn/${CNB_REPO_SLUG_LOWERCASE}/<IMAGE_NAME>`

## Pushing Artifacts

### Push from Local Command Line

Same-name artifacts

```bash
docker build -t docker.cnb.share.ralphlauren.cn/${CNB_REPO_SLUG_LOWERCASE}:latest .
docker push docker.cnb.share.ralphlauren.cn/${CNB_REPO_SLUG_LOWERCASE}:latest
```

Different-name artifacts

```bash
docker build -t docker.cnb.share.ralphlauren.cn/${CNB_REPO_SLUG_LOWERCASE}/<IMAGE_NAME>:latest .
docker push docker.cnb.share.ralphlauren.cn/${CNB_REPO_SLUG_LOWERCASE}/<IMAGE_NAME>:latest
```

### Push in Cloud Native Build

```yaml title=".cnb.yml"
main:
  push:
    - services:
        - docker
      stages:
        - name: docker build
          script: docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest .
        - name: docker push
          script: docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest
```

### Push in Workspaces

Same-name artifacts

```bash
docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest .
docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest
```

Different-name artifacts

```bash
docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}/<IMAGE_NAME>:latest .
docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}/<IMAGE_NAME>:latest
```

## Using Artifacts

### Use in Command Line

```bash
docker pull docker.cnb.share.ralphlauren.cn/<ARTIFACT_PATH>:latest
```

### Customize Cloud Native Build Environment

```yaml{4} title=".cnb.yml"
main:
  push:
    - docker:
        image: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest
      stages:
        - name: hello world
          script: echo "Hello World"
```

### Customize Workspaces Environment

```yaml{4} title=".cnb.yml"
$:
  vscode:
    - docker:
        image: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest
      services:
        - vscode
        - docker
```

## Limitations

* Maximum quota per layer: 64GB
* Maximum number of layers per image: 64
* Maximum size of artifact metadata: 64KB
* Docker Registry V1 API is not supported. Please use Docker 20.10+ client. Older versions (e.g. 1.13.1), while supporting V2, will generate both V1 and V2 endpoints for non-Docker Hub registries by default and automatically fall back to V1 when V2 requests fail, causing requests to be rejected. If you encounter the following errors, please upgrade your Docker version:

  ```text
  Error: image <IMAGE_NAME> not found
  ```

  ```text
  Failed to pull image: rpc error: code = Unknown desc = missing signature key
  ```

  If you must use an older version of Docker (below 17.12), you need to manually disable the V1 protocol:

  | Configuration | Platform | Default | Description |
  |--------------|----------|---------|-------------|
  | `dockerd --disable-legacy-registry` | Linux | `false` | Disable V1 via startup parameter |
  | Set `"disable-legacy-registry": true` in `daemon.json` | All platforms | Not set | Disable V1 via config file |

  > Note: Windows/macOS platforms automatically enforce V2 protocol, no additional configuration needed. This option was removed in Docker 17.12+ as V1 support was completely dropped.

## More Usage

For more Docker usage, please refer to the official documentation