# About the Replicated registry option for KOTS installations

This topic describes how to push images to the Replicated registry. The information in this topic applies only to installations managed with Replicated KOTS.

## Overview

For applications installed with KOTS, you can optionally host private images on the Replicated registry. Hosting your images on the Replicated registry can be useful for testing purposes.

For all production releases, Replicated recommends using the Replicated proxy registry for both private and public image distribution, rather than hosting images on the Replicated registry. The proxy registry provides a globally-distributed and highly-performant method to grant pull-through access to application images. For more information, see [About the Replicated Proxy Registry](/vendor/private-images-about).

Images pushed to the Replicated registry are displayed on the **Images** page in the Vendor Portal:

![Replicated Private Registry section of the vendor portal Images page](/images/images-replicated-registry.png)

[View a larger version of this image](/images/images-replicated-registry.png)

For information about security for the Replicated registry, see [Replicated Registry Security](packaging-private-registry-security).

## Limitations

The Replicated registry has the following limitations:

* You cannot delete images from the Replicated registry. As a workaround, you can push a new, empty image to the registry using the same tags as the target image. Replicated does not recommend removing tags from the registry because it could break older releases of your application.

* When using Docker Build to build and push images to the Replicated registry, provenance attestations are not supported. To avoid a 400 error, include the `--provenance=false` flag to disable all provenance attestations. For more information, see [docker buildx build](https://docs.docker.com/engine/reference/commandline/buildx_build/#provenance) and [Provenance Attestations](https://docs.docker.com/build/attestations/slsa-provenance/) in the Docker documentation.

* You might encounter a timeout error when pushing images with layers close to or exceeding 2GB in size, such as: "received unexpected HTTP status: 524." To work around this, reduce the size of the image layers and push the image again. If the 524 error persists, continue decreasing the layer sizes until the push is successful.

* The ability to push images to the Replicated registry is available only for KOTS-managed installations. Pushing images to the Replicated registry is not supported for Helm installations.

## Push images to the Replicated registry

This procedure describes how to tag and push images to the Replicated registry. For more information about building, tagging, and pushing Docker images, see the
[Docker CLI documentation](https://docs.docker.com/engine/reference/commandline/cli/).

To push images to the Replicated registry:

1. Do one of the following to connect with the `registry.replicated.com` container registry:
   * **(Recommended) Log in with a user token**: Use `docker login registry.replicated.com` with your Vendor Portal email as the username and a Vendor Portal user token as the password. For more information, see [User API Tokens](replicated-api-tokens#user-api-tokens) in _Generating API Tokens_.
   * **Log in with a service account token:** Use `docker login registry.replicated.com` with a Replicated Vendor Portal service account as the password. If you have an existing team token, you can use that instead. You can use any string as the username. For more information, see [Service Accounts](replicated-api-tokens#service-accounts) in _Generating API Tokens_.
   
      :::note
      Team API tokens are deprecated and cannot be generated. If you are already using team API tokens, Replicated recommends that you migrate to Service Accounts or User API tokens instead because these options provide better granular control over token access.
      :::

   * **Log in with your credentials**: Use `docker login registry.replicated.com` with your Vendor Portal email and password as the credentials.

1. Tag your private image with the Replicated registry hostname in the standard
Docker format:

   ```
   docker tag IMAGE_NAME registry.replicated.com/APPLICATION_SLUG/TARGET_IMAGE_NAME:TAG
   ```

   Where:
   * `IMAGE_NAME` is the name of the existing private image for your application.
   * `APPLICATION_SLUG` is the unique slug for the application. You can find the application slug on the **Application Settings** page in the Vendor Portal. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug) in _Managing Applications_.
   * `TARGET_IMAGE_NAME` is a name for the image. Replicated recommends that the `TARGET_IMAGE_NAME` is the same as the `IMAGE_NAME`.
   * `TAG` is a tag for the image.

   For example:

   ```bash
   docker tag worker registry.replicated.com/myapp/worker:1.0.1
   ```

1. Push your private image to the Replicated registry using the following format:

   ```
   docker push registry.replicated.com/APPLICATION_SLUG/TARGET_IMAGE_NAME:TAG
   ```
   Where:
   * `APPLICATION_SLUG` is the unique slug for the application.
   * `TARGET_IMAGE_NAME` is a name for the image. Use the same name that you used when tagging the image in the previous step. 
   * `TAG` is a tag for the image. Use the same tag that you used when tagging the image in the previous step.

   For example:

   ```bash
   docker push registry.replicated.com/myapp/worker:1.0.1
   ```    

1. In the [Vendor Portal](https://vendor.replicated.com/), go to **Images** and scroll down to the **Replicated Private Registry** section to confirm that the image was pushed.